Webhooks (English) - TotalVoice

Webhooks / Callbacks Totalvoice

Webhooks are the best way to integrate with your system – they are HTTP POSTs that occur at certain events sending information to your system. Prefer to use webhooks over looped queries to optimize resources.

The webhook configuration is done through the panel under “API Settings (Configurações da API)“.

Calls

Call End

This webhook is triggered every time a call ends,

  • The call end occurs when it has been answered (chamada atendida) or has not been answered for some other reason.
  • Possible status: answered (atendida), unanswered (sem resposta), busy (ocupado), congested (congestionado), failed (falha) .
  • The status “active” (“ativa”) is returned as FALSE.
  • The webhook URL can be set within the panel under “Minha conta” / “Configurações da API” or via API (Documentation).
  • Note that there are several types of end webhooks: call_end (chamada_fim), tts_end (tts_fim), compound_end (composto_fim) and audio_end (audio_fim).

Data format chamada_fim:

{  
   "id":3273692,
   "data_criacao":"2018-08-15T08:22:30-03:00",
   "ativa":false,
   "url_gravacao":null,
   "cliente_id":6226380,
   "conta_id":6226380,
   "ramal_id_origem":null,
   "tags":"clienteX",
   "status_geral":"finalizada",
   "origem":{  
      "data_inicio":"2018-08-15T08:22:32-03:00",
      "numero":"1130505001",
      "tipo":"fixo",
      "status":"atendida",
      "duracao_segundos":0,
      "duracao":"00:00:00",
      "duracao_cobrada_segundos":0,
      "duracao_cobrada":"00:00:00",
      "duracao_falada_segundos":0,
      "duracao_falada":"00:00:00",
      "preco":0,
      "motivo_desconexao":"16. normal"
   },
   "destino":{  
      "data_inicio":"2018-08-15T08:22:32-03:00",
      "numero":"7171",
      "tipo":"ramal",
      "status":"atendida",
      "duracao_segundos":0,
      "duracao":"00:00:00",
      "duracao_cobrada_segundos":0,
      "duracao_cobrada":"00:00:00",
      "duracao_falada_segundos":0,
      "duracao_falada":"00:00:00",
      "preco":0,
      "motivo_desconexao":"indefinido"
   }
}
id (integer) Call Log ID.
data_criacao (datetime) Date of call record creation. Date and Time in UTC format.
ativa (boolean) Identifies whether the call is active or not.
url_gravacao (string) URL with audio of call recording.
cliente_id (integer) Customer ID of the call.
conta_id (integer) Account ID of the call.
ramal_id_origem (integer) ID of the extension that originated the call for the call, if any.
tags (string) Additional information that can be returned on the object, such as an External ID for example. You can submit this information in the Call Post and retrieve later in that query.
status_geral (string) Overall Call Status.

Data format tts_fim:

{  
   "id":7453678,
   "numero_destino":"1130505001",
   "data_criacao":"2018-08-15T08:21:45-03:00",
   "data_inicio":"2018-08-15T08:21:45-03:00",
   "tipo":"fixo",
   "status":"atendida",
   "duracao_segundos":9,
   "duracao":"00:00:09",
   "duracao_cobrada_segundos":60,
   "duracao_cobrada":"00:01:00",
   "duracao_falada_segundos":9,
   "duracao_falada":"00:00:09",
   "preco":0.06,
   "mensagem":"Esta é uma mensagem SMS",
   "velocidade":0,
   "resposta_usuario":false,
   "resposta":""
}
id (integer) TTS Registry ID.
numero_destino (string) Number of the recipient.
data_criacao (datetime) Date and time the record was created.
data_inicio (datetime) Date and time TTS processing started.
tipo (string) Phone type: fixed, mobile or extension.
status (string) Registration Status.
duracao_segundos (integer) Total duration in seconds of the call since processing started.
duracao (integer) Total call duration since processing started
duracao_cobrada_segundos (integer) Duration in seconds for billing purposes.
duracao_cobrada (integer) Duration considered for billing purposes.
duracao_falada_segundos (integer) Duration in seconds of the call since the destination answered.
duracao_falada (integer) Call duration since destination answered.
preco (float) Amount charged for the call.
mensagem (float) Text message you sent.
resposta_usuario (boolean) Value sent identifying whether to accept the user’s response.
resposta (string) If you sent resposta_usuario = true, when the user performs some action on the device’s numeric keypad, the value will be displayed in this field (DTMF).
motivo_desconexao (string) Here is the reason for the call drop, you can see more in disconnect reasons

Data format composto_fim:

{  
   "id":1722497,
   "numero_destino":"1130505001",
   "data_criacao":"2018-08-15T10:44:03-03:00",
   "data_inicio":"2018-08-15T10:44:04-03:00",
   "tipo":"fixo",
   "status":"atendida",
   "duracao_segundos":10,
   "duracao":"00:00:10",
   "duracao_cobrada_segundos":60,
   "duracao_cobrada":"00:01:00",
   "duracao_falada_segundos":10,
   "duracao_falada":"00:00:10",
   "preco":0.06,
   "resposta_usuario":false,
   "resposta":null,
   "tags":null,
   "motivo_desconexao":"16. normal",
   "url_gravacao":null
}
id (integer) Audio record ID.
numero_destino (string) Number of the recipient.
data_criacao (datetime) Date and time record was created
data_inicio (datetime) Date and time audio processing started
tipo (string) Phone type: fixed, mobile or extension
status (string) Registration Status
duracao_segundos (integer) Duration in seconds (integer) of total call since processing started
duracao (integer) Total call duration since processing started
duracao_cobrada_segundos (integer) Duration in seconds for billing purposes
duracao_cobrada (integer) Duration considered for billing purposes
duracao_falada_segundos (integer) Duration in seconds of call since destination answered
duracao_falada (integer) Call duration since destination answered
preco (float) Amount charged for the call
resposta_usuario (boolean) Awaiting user response: yes or no
resposta (string) When the user performs any action on the device keyboard, the value will be displayed in this field (DTMF).
url_gravacao (string) When Sent Record Audio = true, this field will provide a URL containing the audio of the link recording.
tags (string) Integration parameter – entered in post and returned in get. Ex: “customerX”
motivo_desconexao (string) Here is the reason for the call drop, you can see more in disconnect reasons

Data format audio_fim:

{  
   "id":3273691,
   "numero_destino":"1130505001",
   "data_criacao":"2018-08-15T08:22:22-03:00",
   "data_inicio":"2018-08-15T08:22:23-03:00",
   "tipo":"fixo",
   "status":"atendida",
   "duracao_segundos":10,
   "duracao":"00:00:10",
   "duracao_cobrada_segundos":60,
   "duracao_cobrada":"00:01:00",
   "duracao_falada_segundos":10,
   "duracao_falada":"00:00:10",
   "preco":0.06,
   "url_audio":"https://foooo.bar/audio.mp3",
   "resposta_usuario":false,
   "resposta":"",
   "url_gravacao":null
}
id (integer) Audio record ID.
numero_destino (string) Number of the recipient.
data_criacao (datetime) Date and time the record was created.
data_inicio (datetime) Date and time audio processing started.
tipo (string) Phone type: fixed, mobile or extension.
status (string) Registration Status.
duracao_segundos (integer) Total duration in seconds of the call since processing began.
duracao (String) Total call duration since processing started
duracao_cobrada_segundos (integer) Duration in seconds for billing purposes.
duracao_cobrada (string) Duration considered for billing purposes.
duracao_falada_segundos (integer) Duration in seconds of the call since the destination answered.
duracao_falada (string) Call duration since destination answered.
preco (float) Amount charged for the call.
url_audio (string) Audio URL sent to the call.
resposta_usuario (boolean) Value sent identifying whether to accept user response.
resposta (string) If you submitted resposta_usuario = true, when the user performs some action on the device’s numeric keypad, the value will be displayed in this field (DTMF).
motivo_desconexao (string) Here is the reason for the call drop, you can see more in disconnect reasons
url_gravacao (string) When Sent Record Audio = true, this field will provide a URL containing the audio of the link recording.

Data Format

Data is sent via HTTP (or HTTPS) with the following header:

“Content-type: application/json”

This is a brief example in PHP:

 <?php
 $json_dados= file_get_contents("php://input");
 $LOGFILE = __DIR__."/log.txt";
 $pf = fopen($LOGFILE, "a+");
 fwrite($pf, date('Y/m/d H:i:s'));
 fwrite($pf, "n".$json_dados."nn");
 $array_dados = json_decode($json_dados, true);
 fwrite($pf, "ID>".$array_dados['id']."n");
 fclose($pf);
 ?>
Dont forget to create the log.txt file and give write permission to user.

Result:

 more log.txt
 2017/03/16 18:34:20{"id":4163,"sms_id":1092334,"resposta":" 3","data_resposta":"2017-03-16T15:34:20-03:00"}

Real Time Webhook

These Webhooks fire as the status of the call changes. They are important for real-time call tracking systems, such as displaying a notification if a call is coming to an extension (ramal), for example.

The status parameter can have the following values: preparing (preparando), calling (chamando), answered (atendida), busy (ocupado) .

The active (ativo) parameter informs if the call is active, having only true / false as its value .

Real Time Calls

This webhook is triggered every time one of the call legs changes state. This is valid only for calls made by API or Webphone / Softphone / Calling Devices connected to our system.

Format of data posted to webhook URL:

{
   "data_criacao":"2018-06-08T13:20:29",
   "gravar_audio":false,
   "id":121947,
   "cliente_id":111111,
   "tags":"MINHA_TAG,CLIENTE_LEGAL",
   "origem":{
      "data_criacao":"2018-06-08T10:20:31",
      "tipo":"ramal",
      "ativo":true,
      "numero":"4000",
      "status":"atendida",
      "data_atendimento":"2018-06-08T10:20:34",
      "duracao_segundos":9,
      "duracao_falada_segundos":6
   },
   "destino":{
      "data_criacao":"2018-06-08T10:20:34",
      "tipo":"movel",
      "ativo":false,
      "numero":"489999999999",
      "status":"chamando"
   }
}
id (integer) Call Log ID.
data_criacao (datetime) Date of call record creation. Date and Time in UTC format.
ativa (boolean) Identifies whether the call is active or not.
url_gravacao (string) URL with audio of call recording.
cliente_id (integer) Customer ID for the call.
conta_id (integer) Account ID for the call.
ramal_id_origem (integer) ID of the extension that originated the call for the call, if any.
tags (string) Additional information that can be returned on the object, such as an External ID for example. You can submit this information in the Call Post and retrieve later in that query.
status_geral (string) Overall Call Status.
origem / destino (object) Returns source / destination objects

Real Time Extension

Whenever an account extension (ramal) configured with this webhook receives / answers / hangs up an call, an event is triggered to the chosen URL.

The origin number (numero_origem) is the telephone number that is dialing this extension (ramal).

Format of data posted to webhook URL:

{
   "data_criacao":"2018-06-08T10:20:31",
   "id":121947,
   "tipo":"ramal",
   "ativo":true,
   "ramal":"4000",
   "numero_origem":4899999999,
   "status":"atendida",
   "data_atendimento":"2018-06-08T10:20:34",
   "duracao_segundos":9
   "duracao_falada_segundos":6,
   "tags":"MINHA_TAG,CLIENTE_LEGAL"
}
data_criacao (datetime) Date and time the extension call was created.
id (integer) Unique identifier of this extension.
tipo (string) The phone type of this leg always comes extension.
ativo (boolean) Informs if the call is active, if true, the extension answered and the call is still connected.
ramal (integer) The extension number of this call.
status (string) Represents the current status of this leg in the call.
data_atendimento (datetime) Date and time when the call was answered, if the call was not answered this attribute does not come.
duracao_segundos (integer) Total duration in seconds of the call from creation to termination (either for hanging up or not answering).
duracao_falada_segundos (integer) Duration in seconds from the time the extension answered the call until it was hung up.
motivo_desconexao (string) Here is the reason for the call drop, you can see more in disconnect reasons

Real Time DID

This event is triggered whenever a DID (telephone number registered with us) receives a call or a status change (transfer, end, etc).

The extension parameter (ramal) will only be filled if the call that went to the DID ends up falling at some extension.

Source number (numero_origem) is the number that called the DID and the destination number (numero_destino) is the DID receiving the call.

Format of data posted to webhook URL:

{
   "id":121947,
   "data_criacao":"2018-06-08T13:20:29",
   "gravar_audio":false,
   "cliente_id":111111,
   "numero_origem":"4822221111",
   "numero_destino":"4833332222",
   "data_atendimento":"2018-06-08T10:20:34",
   "ativo":true,
   "data_criacao":"2018-06-08T10:20:31",
   "status":"atendida",
   "duracao_segundos":20,
   "duracao_falada_segundos":19,
   "ramal":{
      "ativo":true,
      "data_criacao":"2018-06-08T10:20:34",
      "numero":"4000",
      "status":"atendida",
      "duracao_segundos":9,
      "duracao_falada_segundos":6,
   }
}
id (integer) Unique identifier of this call.
data_criacao (datetime) Date and time the connection was created.
data_atendimento (datetime) Date and time when the call was answered by the DID.
ativo (boolean) Informs if the call is active.
status (string) Represents the current status of this call to the DID.
duracao_segundos (integer) Total duration of the call in seconds, from creation to termination (either by hanging up or not answering).
duracao_falada_segundos (integer) Duration in seconds from the time the DID answered the call to the moment it was hung up.
ramal (object) If the call to this DID drops at any extension, this field is populated with extension leg information.
tipo (string) Phone type: fixed, mobile or extension.
SMS

SMS – Status Change and Delivery

This webhook is triggered whenever an SMS message changes status.

  • Possible status:  waiting (aguardando), sent (enviada), error (erro), delivered (entregue).

Webhook Content

Format of data posted to webhook URL:

{
        "id": 2323,
        "numero_destino": "9912341234",
        "data_criacao": "2016-04-05T15:00:34-03:00",
        "mensagem": "Texto mensagem SMS",
        "preco": 0.15,
        "status_envio": "entregue",
        "data_status": "2016-04-05T15:01:23-03:00",
        "resposta_usuario": 1,
        "respostas": [
                {
                        "id": 3301,
                        "resposta": "Texto da Resposta",
                        "data_resposta": "2016-04-05T15:05:13-03:00"
                },
                {
                        "id": 3302,
                        "resposta": "Outra resposta",
                        "data_resposta": "2016-04-05T15:07:11-03:00"
                }

        ]
}
data_criacao (datetime) Date and time the SMS was created.
id (integer) Unique identifier of this SMS.
numero_destino (string) Phone number to receive SMS, DDD format + Number. Example: 4832830151.
mensagem (string) Message that will be sent to the number.
preco (float) Amount charged for shipping
status_envio (float) SMS sending status.
data_status (datetime) Date and time the status was changed.
resposta_usuario (boolean_ Awaiting user response: yes or no
respostas (boolean) Array containing the response objects.

SMS Reply

The SMS reply webhook is a JSON with callback ID, SMS ID, reply, and date.

Example:

{"id":16347,"sms_id":133830,"resposta":"SIM","data_resposta":"2016-10-17T18:02:20-02:00"}

d (integer) Response record ID.
sms_id (integer) SMS ID linked to the response.
resposta (string) Text with user response
data_resposta (datetime)  Date and time that was answered by the user