To use VoIPstudio telephony in Mavibot, you need to create an API key in your VoIPstudio account, enter it in the integration settings, and configure event delivery to the URL that Mavibot displays after the integration is connected.

VoIPstudio is a cloud PBX with phone numbers available in 70+ countries. Unlike a traditional telecom operator, it supports internal users, ring groups, queues, and IVR menus, while the bot operates on top of this PBX.

The bot can initiate calls to customers on behalf of employees, transfer and end calls, save recordings, and send call events to the conversation.

Getting the Required Information

  1. Register at voipstudio.com and purchase a phone number in the required country.
  2. Create users in the PBX — one for each employee who will receive calls. Calls are delivered to all devices registered to a user, so you do not need to specify a separate phone number for each employee.
  3. Go to Settings → API, create an API Key, and copy it.

Connecting the Integration

In the telephony settings, select VoIPstudio and enter:

  • API Key — the key from your VoIPstudio account.

The integration is now connected. To disconnect it, clear the API Key field and save the settings.

After saving, a notification URL will appear on the page. Copy it:

https://chatter.mavibot.ai/voipstudio_webhook/

Do not publish this URL or share it with anyone. If you disconnect and reconnect the integration, the key remains the same, so you will not need to configure notifications again.

Then, in your VoIPstudio account, go to Integrations → Webhooks → Enable → Add Webhook, paste the copied URL, and select the following events:

  • Call State Change — or select Call Ringing, Call Connected, Call Ended, and Call Missed individually;
  • Call Recording Ready — if you need call recordings.

Without this configuration, outbound calls will still work, but call events will not appear in the conversation.

Employees

In the employee settings, fill in the VoIPstudio User ID field — the numeric identifier of the user in your PBX, for example 10002.

Enter the PBX user ID, not a phone number. You can find the ID in the user list in your VoIPstudio account. Without it, the call button in the customer card will not work for that employee.

Calling from the Customer Card

A call button will appear next to the customer's phone number in the conversation card.

VoIPstudio first calls the employee on all of their registered devices simultaneously. Once the employee answers, VoIPstudio calls the customer and connects the two parties.

If the employee does not answer, the customer will not be called.

Calculator Functions

Employee-to-Customer Call

voipstudio_employee_call(client_phone, employee_user_id, caller_id)

Parameters:

  • client_phone — the customer's phone number. Required.
  • employee_user_id — the VoIPstudio user ID of the employee who should receive the first call. Required.
  • caller_id — the phone number displayed to the customer. Optional. You can pass anonymous to hide the caller ID.

Transfer a Call

voipstudio_transfer_call(phone, call_id)

Transfers an active call to another phone number.

Parameters:

  • phone — the phone number to which the call should be transferred. Required and must be the first parameter.
  • call_id — the call identifier. Optional. If omitted, the customer's current call is taken from the voipstudio_call_id variable.

End a Call

voipstudio_hangup_call(call_id)

Ends an active call.

Parameters:

  • call_id — the call identifier. Optional. If omitted, the customer's current call is used.

voipstudio_get_record_link(call_id)

Returns a link to the call recording. The link is normally saved automatically when the recording-ready event is received. This function is useful if that event was not received.

Parameters:

  • call_id — the call identifier. Optional. If omitted, the customer's current call is used.

The function searches the 100 most recent recordings in the account. For an older call on a high-volume PBX, it may not find the recording. In that case, retrieve the recording directly from your VoIPstudio account.

Callbacks During a Call

As the call progresses, callbacks are sent to the conversation in the following format:

voipstudio_call_event call.hangup

The event name is passed exactly as received from VoIPstudio, for example call.ringing, call.connected, call.hangup, and others. The available events depend on which events you selected when configuring notifications.

If no event name is provided, the call state is used instead:

INITIAL, RINGING, CONNECTED, ON_HOLD, HANGUP.

A separate callback is sent when the recording is ready:

voipstudio_call_event recording

Wait for the recording callback before using the recording link. The recording is processed after the call has ended, so the voipstudio_record_link variable is still empty when call.hangup is received.

If two employees within your own PBX are talking to each other, callbacks are not sent to the conversation and no customer card is created.

Customer Variables After a Call

Variable Value
voipstudio_call_id Call ID in VoIPstudio
voipstudio_call_state Call state: INITIAL, RINGING, CONNECTED, ON_HOLD, HANGUP
voipstudio_call_duration Call duration in seconds
voipstudio_call_cause Reason the call ended
voipstudio_terminated_by Who ended the call: caller or callee
voipstudio_record_link Link to the call recording
voipstudio_record_id Recording ID in VoIPstudio

Call Recordings

Call recording is enabled in the VoIPstudio settings and is managed by the PBX itself. If you need recordings, enable call recording in your VoIPstudio account and select the Call Recording Ready event when configuring notifications.

The voipstudio_record_link URL is protected by an access key. It cannot be opened directly in a browser or shared with a customer. You can download the recording from your VoIPstudio account in the call history section.

Call recording is subject to applicable laws. In Germany, France, Spain, and most U.S. states, consent from both parties may be required, and in some jurisdictions a spoken notice at the beginning of the call may also be necessary. The VoIPstudio account owner is responsible for complying with these requirements.

Troubleshooting

Error Cause
Authorization error when creating a call The API Key is incorrect or expired. Make sure the key was created under Settings → API rather than obtained through a login request.
Calls work, but no callbacks appear in the conversation No webhook has been created in VoIPstudio, the Enable toggle is off, or the wrong URL was entered. Copy the entire URL from the integration page, including the key at the end.
The call cannot be created or the employee's devices do not ring A phone number was entered instead of the VoIPstudio User ID, or the user has no registered devices.
The recording callback is not received Call recording is not enabled in VoIPstudio, or the Call Recording Ready event was not selected.

VoIPstudio is billed directly by VoIPstudio: there is a subscription fee for each PBX user, plus call charges. This differs from operators that charge per minute without a recurring subscription. When estimating costs, take the number of configured users into account, not just the volume of calls.