To use TotalVoice telephony in Mavibot, you need to get an Access Token from the TotalVoice dashboard and enter it in the integration settings. TotalVoice is a Brazilian telephony service that is now part of the Zenvia group.

The bot can connect an employee with a client, transfer and end calls, retrieve call recordings, and send call events to the conversation. TotalVoice also provides the cost of each call.

Getting the required data

  1. Create a Zenvia Voice account and add funds to your balance.

  1. Log in to the dashboard. In the bottom-left corner of the main screen, next to Access Token, click the copy icon.

Access Token is the only key that provides access to your entire account, including making paid calls. Do not publish it or share it outside your company.

Connection

In the telephony settings, select TotalVoice and enter:

  • Access Token — the key from the TotalVoice dashboard.
  • Client-facing number — the number the client will see, in the format +551140028922. This field is optional. If left empty, the default number from your TotalVoice account will be used.


After saving, a notification URL will appear on the connection page. You need to add it to the TotalVoice dashboard — see the next section.

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

Notification setup

Unlike other telephony integrations, the notification URL must be configured manually because TotalVoice does not provide a way for Mavibot to do this automatically.

  1. Copy the URL shown on the connection page.

  1. In the TotalVoice dashboard, open Desenvolvedores → Configurações da API.
  2. Paste the same URL into all three webhook fields:
    • Status Tempo Real — call status changes while the call is in progress;
    • Chamada - Fim — end of a call;
    • DID - Fim de Chamada — end of an incoming call to your number.

⏳ Notifications may take up to 20 minutes to start arriving after you save the settings. This is a TotalVoice limitation. If no events appear in the conversation immediately after setup, just wait.

If you regenerate your Access Token, the notification URL will change. Save the new token in Mavibot and update the URL in the TotalVoice dashboard, otherwise call events will stop arriving.

Employees

In the employee settings, enter the employee's TotalVoice number.


You can use either an internal extension (ramal, usually 3–4 digits) or a regular mobile number in the format +5511987654321. This is one of the few integrations where the format is flexible: if the employee does not use an internal PBX extension, enter their mobile number.

Calling from the client card

A call button will appear next to the client's phone number in the conversation card. TotalVoice first calls the employee, and only after the employee answers does it call the client.

This order is intentional: the client will not hear silence on the line because the employee is already connected when the client's phone starts ringing.

Calculator Functions

Employee-to-Client Call

totalvoice_employee_call(client_phone, employee_number, bina, gravar_audio)

Parameters:

  • client_phone — the client's phone number in the format +5511987654321. Required.
  • employee_number — the employee's number: either an internal extension or a mobile number. Required.
  • bina — the number the client will see. Optional. If omitted, the number from the connection settings is used.
  • gravar_audio — whether to record the call. Optional. Recording is enabled by default.

Transfer Call

totalvoice_transfer_call(number, call_id, leg)

Parameters:

  • number — the number to which the call should be transferred. Required.
  • call_id — the call identifier. Optional. If omitted, the client's most recent call is used.
  • leg — which side of the call to transfer: destino (the client, default value) or origem (the employee).

End Call

totalvoice_hangup_call(call_id)

Parameters:

  • call_id — the call identifier. Optional. If omitted, the client's most recent call is used.
totalvoice_get_record_link(call_id)

Normally, the recording link is received automatically with the call-end event. This function is useful if the notification was not received or if you need a recording from an older call.

Parameters:

  • call_id — the call identifier. Optional. If omitted, the client's most recent call is used.

Callbacks During a Call

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

totalvoice_call_event atendida

Possible events:

Event When it is triggered
chamando The call is ringing
preparando The line is being prepared for connection
atendida The call has been answered
sem_resposta No answer
ocupado Busy
cancelada The call was canceled
congestionado Carrier network congestion
falha The call could not be completed
nao_existe The number does not exist

Status names are received in Portuguese because these are the status names used by TotalVoice.

A typical "no answer → send a message in the messenger" scenario can be built by checking the totalvoice_call_answered variable.

Call status notifications are sent no more than once every 2 seconds per call. For very short calls, some intermediate statuses may not arrive in time. The call-end event is always sent.

Client Variables After a Call

Variable Value
totalvoice_call_id Call identifier
totalvoice_call_status Call status as defined by TotalVoice
totalvoice_call_answered 1 — the call was answered, 0 — it was not
totalvoice_call_duration Call duration in seconds
totalvoice_call_price Call cost in Brazilian reais
totalvoice_hangup_reason Reason the call ended
totalvoice_record_link Link to the call recording

Duration means actual talk time, excluding the time spent waiting for the call to be answered. Keep in mind that TotalVoice calculates billing differently: billable time is rounded up to the next full minute, so a 24-second call will be billed as one minute. To verify charges, use the billing report in the TotalVoice dashboard rather than this variable.

Call Recordings

Recording is configured separately for each call and is enabled by default. You can disable it for a specific call using the gravar_audio parameter in the call function.

When the call ends, the recording link is received with the event and saved to the totalvoice_record_link variable. You do not need to request it separately.

Call recording is regulated by law. In Brazil, it is subject to LGPD requirements: the client must be informed that the call is being recorded, and there must be a lawful basis for storing the data. The TotalVoice account owner is responsible for complying with these requirements.

Troubleshooting

Error Cause / Solution
The call is not created and the error message is in Portuguese TotalVoice returns the reason as text. The most common causes are insufficient balance or an invalid phone number format.
Calls work, but no callbacks appear in the conversation The notification URL has not been added to the TotalVoice dashboard, has not been added to all three webhooks, or 20 minutes have not passed since configuration.
Everything worked before, but events suddenly stopped The Access Token was regenerated, which changed the notification URL. Save the new token in Mavibot and update the URL in the TotalVoice dashboard.
"TotalVoice number is not specified" The employee's TotalVoice number is missing from their settings.
Status nao_existe The client's number does not exist. Check the format. Brazilian mobile numbers use +55 + DDD + 9 digits.
Status congestionado There is a problem with the carrier's network and it is unrelated to the client's number. If the issue persists, contact TotalVoice support.
No recording link The call was created with recording disabled, or the call was not answered.