Referência sobre Webhooks da Voice API
A Vonage utiliza webhooks em conjunto com sua Voice API para permitir que seu aplicativo interaja com a chamada. Existem dois endpoints de webhook obrigatórios e um opcional:
- Webhook de resposta é enviada quando uma chamada é atendida. Isso se aplica tanto a chamadas recebidas quanto a chamadas feitas.
- Webhook de evento é enviado para todos os eventos que ocorrem durante uma chamada. Seu aplicativo pode registrar, reagir ou ignorar cada tipo de evento.
- URL alternativa é utilizado quando o webhook “Resposta” ou “Evento” falha ou retorna um código de erro HTTP.
- Erros também são enviadas para o endpoint do webhook do evento, caso ocorram.
Para obter mais informações gerais, consulte nosso guia de webhooks.
Webhooks assinados
Os webhooks assinados são uma forma de verificar se a solicitação está vindo da Vonage e se sua carga útil não foi adulterada durante o trânsito. Voice API, assim como Mensagens e Despacho As APIs suportam callbacks assinados por padrão. Consulte Decodificação de webhooks assinados para aprender a decodificar uma assinatura JWT recebida.
Webhook de resposta
Quando uma chamada recebida é atendida, uma solicitação HTTP é enviada para o answer_url que você especificou ao configurar o aplicativo. Para chamadas de saída, especifique o answer_url quando você fizer a ligação.
Por padrão, o webhook de resposta será um GET solicitação, mas isso pode ser substituído por POST definindo o answer_method campo. Para chamadas recebidas, você configura esses valores ao criar o aplicativo. Para chamadas efetuadas, você especifica esses valores ao fazer uma chamada.
Campos de dados do webhook de resposta
| Campo | Exemplo | Descrição |
|---|---|---|
to |
442079460000 |
O número que atendeu a chamada. (Este é o número virtual vinculado ao seu aplicativo.) |
from |
447700900000 |
O número de quem ligou to. Pode ser um número de telefone fixo ou celular, ou outro número virtual, caso a chamada tenha sido feita por meio de um programa. |
from_user |
JaneDoe |
O nome de usuário que fez a chamada to somente se a chamada tiver sido feita usando o Client SDK. Nesse caso, from estará ausente (ou seja, from e from_user (nunca estarão presentes ao mesmo tempo). |
endpoint_type |
phone |
O tipo de canal de voz que atendeu a chamada. Os valores possíveis são: phone, sip, websocket, app, vbc, whatsapp. |
uuid |
aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
Um identificador único para esta chamada |
conversation_uuid |
CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
Um identificador único para esta conversa |
region_url |
https://api-ap-3.vonage.com |
Endpoint da API regional que deve ser usado para controlar a chamada com API REST; veja a lista completa de regiões aqui |
custom_data |
{ "key": "value" } |
Um objeto de dados personalizado, opcionalmente passado como parâmetro na serverCall método quando uma chamada é iniciada a partir de um aplicativo que utiliza o Client SDK |
Transmissão de dados adicionais por meio de cabeçalhos SIP
Além dos campos acima, você pode especificar quaisquer cabeçalhos adicionais necessários ao usar o SIP Connect. Quaisquer cabeçalhos fornecidos devem começar com X- e será enviado para o seu answer_url com o prefixo SipHeader_. Por exemplo, se você adicionar um cabeçalho com o texto X-UserId com um valor de 1938ND9, a Vonage irá adicionar SipHeader_X-UserId=1938ND9 em resposta ao pedido feito ao seu answer_url.
Aviso: Cabeçalhos que começam com X-Nexmo não será enviado para o seu answer_url
A Vonage oferece suporte a ambos X- cabeçalhos e o De usuário para usuário cabeçalho. Esses mecanismos podem ser usados individualmente ou em conjunto na mesma chamada.
O cabeçalho User-to-User permite enviar dados contextuais durante uma chamada do seu equipamento SIP para o seu aplicativo de Voice API. Para usar esse cabeçalho, seu equipamento SIP deve enviar um cabeçalho User-to-User para o seu domínio SIP programável. Além disso, seu aplicativo de Voice API precisará receber o webhook de resposta que contém o conteúdo desse cabeçalho.
O Cabeçalho “Usuário para usuário” deve ser formatado da seguinte maneira: SipHeader_User-to-User=1234567890abcdef;encoding=hex
O cabeçalho “User-to-User” é validado apenas para garantir que contenha caracteres válidos e não exceda 256 caracteres. O conteúdo em si não é validado de nenhuma outra forma.
Exemplos de campos de dados do webhook de resposta
Para um GET Na solicitação, as variáveis estarão na URL, assim:
/answer.php?to=442079460000&from=447700900000&conversation_uuid=CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab&uuid=aaaaaaaa-bbbb-cccc-dddd-0123456789ab&SipHeader_X-UserId=1938ND9
Se você definir o answer_method para POST nesse caso, você receberá a solicitação com dados no formato JSON no corpo da mensagem:
{
"from": "442079460000",
"to": "447700900000",
"uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"conversation_uuid": "CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"SipHeader_X-UserId": "1938ND9"
}
Respondendo ao webhook de resposta
A Vonage espera que você devolva um NCCO no formato JSON, contendo as ações a serem executadas.
Webhook de evento
As solicitações HTTP do webhook de eventos chegarão ao endpoint do webhook de eventos sempre que houver alguma alteração no status de uma chamada.
A URL será a event_url que você especificou ao criar seu aplicativo, a menos que você o substitua definindo um event_url ao iniciar uma chamada.
Por padrão, as solicitações recebidas são POST solicitações com corpo em JSON.
Você pode sobrescrever o método para GET configurando o event_method além do event_url.
Espera-se que seu sistema responda à solicitação HTTP.
Se o seu sistema não confirmar o evento ou, em vez disso, responder com um código 429, 502, 503 ou 504, será feita uma nova tentativa.
Para eventos que exigem o retorno de um NCCO, a URL alternativa será então utilizada. Consulte o URL de reserva seção para mais detalhes.
O formato dos dados incluídos depende do evento que ocorreu:
Observação: Os exemplos e as tabelas de campos nesta seção mostram os campos normalmente presentes após a criação bem-sucedida de uma chamada. Em alguns cenários, uma chamada pode ser rejeitada antes que um recurso de chamada seja criado, e um uuid portanto, não estará presente. Por exemplo, se uma chamada for rejeitada porque o limite de CPS da Account foi excedido, nenhum recurso de chamada será criado e nenhum UUID de chamada será gerado.
startedringingansweredbusycancelledunansweredreconnectingreconnecteddisconnectedrejectedfailedhuman/machinetimeoutcompletedrecordinputtransfer
Observação: Para websocket pontos finais que definem pelo menos um dos Opções de resiliência do WebSocket (failover, connectionTimeout, keepalive, ou reconnect), o answered, unanswered, failed, disconnected, e completed Os eventos incluem campos WebSocket adicionais, descritos nas seções a seguir. O reconnecting e reconnected os eventos só são enviados quando o endpoint define reconnect.
Iniciado
Indica que a chamada foi criada.
Observação: O cps_region_usage, cps_global_usage, e cps_limit os campos só estão presentes no started carga útil do evento, quando ativada explicitamente. Use "return_cps_on_started": true (snake_case) como parâmetro de nível superior em um POST /calls solicitação, ou "returnCpsOnStarted": true (camelCase) em um NCCO connect ação. Se esse parâmetro for omitido ou definido como false, esses campos não serão exibidos. Para obter mais informações, consulte Limite de chamadas por segundo (CPS).
| Campo | Exemplo | Descrição |
|---|---|---|
from |
442079460000 |
O número de onde a ligação foi feita |
to |
447700900000 |
O número para o qual a ligação foi feita |
uuid |
aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
O identificador exclusivo desta chamada |
conversation_uuid |
CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
O identificador exclusivo desta conversa |
status |
started |
Status da chamada |
direction |
outbound |
Direção da chamada: pode ser inbound ou outbound |
timestamp |
2020-01-01T12:00:00.000Z |
Carimbo de data e hora (formato ISO 8601) |
cps_region_usage |
1 |
O número de chamadas por segundo atualmente em uso na região no momento em que esta chamada foi criada. Reflete o consumo regional de CPS. |
cps_global_usage |
0 |
O número de chamadas por segundo atualmente em uso em todas as regiões do mundo no momento em que esta chamada foi criada. |
cps_limit |
3 |
O número máximo de chamadas por segundo (CPS) configurado para esta conta. |
{
"from": "442079460000",
"to": "447700900000",
"uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"conversation_uuid": "CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"status": "started",
"direction": "outbound",
"timestamp": "2020-01-01T12:00:00.000Z",
"cps_region_usage": 1,
"cps_global_usage": 0,
"cps_limit": 3
}
Voltar à lista de webhooks de eventos
Zumbido
O telefone do destinatário da chamada está tocando.
| Campo | Exemplo | Descrição |
|---|---|---|
from |
442079460000 |
O número de onde a ligação foi feita |
to |
447700900000 |
O número para o qual a ligação foi feita |
uuid |
aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
O identificador exclusivo desta chamada |
conversation_uuid |
CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
O identificador exclusivo desta conversa |
status |
ringing |
Status da chamada |
direction |
outbound |
Direção da chamada: pode ser inbound ou outbound |
timestamp |
2020-01-01T12:00:00.000Z |
Carimbo de data e hora (formato ISO 8601) |
Voltar à lista de webhooks de eventos
Respondido
A ligação foi atendida.
| Campo | Exemplo | Descrição |
|---|---|---|
start_time |
null |
Atualmente, esse campo não é compatível. |
rate |
0.12 |
Custo da ligação em euros |
from |
442079460000 |
O número de onde a ligação foi feita |
to |
447700900000 |
O número para o qual a ligação foi feita |
uuid |
aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
O identificador exclusivo desta chamada |
conversation_uuid |
CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
O identificador exclusivo desta conversa |
status |
answered |
Status da chamada |
direction |
inbound |
Direção da chamada: pode ser inbound ou outbound |
network |
null |
Tipo de rede utilizada na chamada |
endpoint_type |
phone |
O tipo de canal de voz da chamada. Os valores possíveis são: phone, sip, websocket, app, vbc, whatsapp. |
timestamp |
2020-01-01T12:00:00.000Z |
Carimbo de data e hora (formato ISO 8601) |
connected_uri |
wss://secondary.example.com/socket |
O URI ao qual a Vonage se conectou: o principal uri ou um dos failover URIs. Estão presentes apenas quando o endpoint define pelo menos uma das opções de resiliência do WebSocket. |
Voltar à lista de webhooks de eventos
Ocupado
O destinatário está na linha com outro interlocutor.
| Campo | Exemplo | Descrição |
|---|---|---|
from |
442079460000 |
O número de onde a ligação foi feita |
to |
447700900000 |
O número para o qual a ligação foi feita |
uuid |
aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
O identificador exclusivo desta chamada |
conversation_uuid |
CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
O identificador exclusivo desta conversa |
status |
busy |
Status da chamada |
direction |
outbound |
Direção da chamada, será esta outbound nesse contexto |
timestamp |
2020-01-01T12:00:00.000Z |
Carimbo de data e hora (formato ISO 8601) |
sip_code |
404 |
O código de status SIP retornado (por exemplo, 404, 480, ou 487) por meio do endereço registrado event_url, fornecendo detalhes adicionais sobre o motivo da conclusão ou da falha da chamada. Consulte os códigos de status SIP descritos aqui. |
Voltar à lista de webhooks de eventos
Cancelado
Uma chamada efetuada é cancelada pelo autor antes de ser atendida.
| Campo | Exemplo | Descrição |
|---|---|---|
from |
442079460000 |
O número de onde a ligação foi feita |
to |
447700900000 |
O número para o qual a ligação foi feita |
uuid |
aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
O identificador exclusivo desta chamada |
conversation_uuid |
CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
O identificador exclusivo desta conversa |
status |
cancelled |
Status da chamada |
direction |
outbound |
Direção da chamada, será esta outbound nesse contexto |
timestamp |
2020-01-01T12:00:00.000Z |
Carimbo de data e hora (formato ISO 8601) |
Voltar à lista de webhooks de eventos
Sem resposta
Ou o destinatário está indisponível ou recusou a chamada.
| Campo | Exemplo | Descrição |
|---|---|---|
from |
442079460000 |
O número de onde a ligação foi feita |
to |
447700900000 |
O número para o qual a ligação foi feita |
uuid |
aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
O identificador exclusivo desta chamada |
conversation_uuid |
CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
O identificador exclusivo desta conversa |
status |
unanswered |
Status da chamada |
detail |
unavailable |
Indica se o assinante está temporariamente indisponível (unavailable) ou a operadora não conseguiu dar uma resposta dentro de um prazo razoável (timeout) |
direction |
outbound |
Direção da chamada, será esta outbound nesse contexto |
timestamp |
2020-01-01T12:00:00.000Z |
Carimbo de data e hora (formato ISO 8601) |
sip_code |
404 |
O código de status SIP retornado (por exemplo, 404, 480, ou 487) por meio do endereço registrado event_url, fornecendo detalhes adicionais sobre o motivo da conclusão ou da falha da chamada. Consulte os códigos de status SIP descritos aqui. |
attempts |
[{"uri": "wss://a.example.com", "result": "timeout"}] |
Apenas presente quando o endpoint define pelo menos uma das opções de resiliência do WebSocket. O resultado de cada tentativa de conexão quando não foi possível estabelecer conexão com nenhum URI, com uma entrada por URI tentado. Cada entrada contém uri e result: timeout, refused, tls_error, ou http_ seguido pelo código de status HTTP, por exemplo http_503. Falhas na resolução de nomes e reinicializações de conexão são relatadas como refused, exceto uma consulta de DNS que atinge o tempo limite, o que é relatado como timeout. |
Voltar à lista de webhooks de eventos
Reconectando-se
Uma conexão WebSocket estabelecida foi encerrada de forma inadequada e a Vonage está começando a se reconectar. Esse evento só é enviado quando o websocket conjuntos de pontos finais reconnect. Veja Reconexão automática para mais detalhes.
Este evento tem caráter meramente informativo. A Vonage desconsidera qualquer NCCO devolvido em resposta a ele.
| Campo | Exemplo | Descrição |
|---|---|---|
from |
447700900000 |
O número de onde a ligação foi feita |
to |
wss://primary.example.com/socket |
A principal uri do websocket ponto de extremidade. Ele não se altera após um failover ou uma reconexão. |
uuid |
aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
O identificador exclusivo desta chamada. Ele não se altera durante a reconexão. |
conversation_uuid |
CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
O identificador exclusivo desta conversa. Ele não muda durante a reconexão. |
status |
reconnecting |
Status da chamada |
direction |
outbound |
Direção da chamada: pode ser inbound ou outbound |
cause |
remote_closed |
Por que a conexão foi encerrada. Pode ser uma das seguintes razões:
|
close_code |
1012 |
O código de status do quadro Close enviado pelo seu servidor. Aparece apenas quando um quadro Close é recebido. |
close_reason |
service restart |
O texto de justificativa do quadro “Close” enviado pelo seu servidor, ou uma string vazia caso o quadro não contenha texto de justificativa. Apenas aparece quando um quadro “Close” é recebido. |
timestamp |
2020-01-01T12:00:00.000Z |
Carimbo de data e hora (formato ISO 8601) |
headers |
{"caller-id": "447700900123"} |
O headers você definiu no websocket ponto final |
Voltar à lista de webhooks de eventos
Reconectado
Uma tentativa de reconexão foi bem-sucedida e a conexão WebSocket foi restabelecida. Esse evento só é enviado quando o websocket conjuntos de pontos finais reconnect. Veja Reconexão automática para mais detalhes.
Este evento tem caráter meramente informativo. A Vonage desconsidera qualquer NCCO devolvido em resposta a ele.
| Campo | Exemplo | Descrição |
|---|---|---|
from |
447700900000 |
O número de onde a ligação foi feita |
to |
wss://primary.example.com/socket |
A principal uri do websocket ponto de extremidade. Ele não se altera após um failover ou uma reconexão. |
uuid |
aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
O identificador exclusivo desta chamada. Ele não se altera durante a reconexão. |
conversation_uuid |
CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
O identificador exclusivo desta conversa. Ele não muda durante a reconexão. |
status |
reconnected |
Status da chamada |
direction |
outbound |
Direção da chamada: pode ser inbound ou outbound |
attempt |
1 |
O número da tentativa de reconexão que foi bem-sucedida. Esse número é contabilizado no mesmo maxAttempts limite, portanto, se a conexão cair novamente em até 30 segundos, a contagem continua a partir das tentativas anteriores. |
connected_uri |
wss://secondary.example.com/socket |
O URI ao qual a Vonage se reconectou: o principal uri ou um dos failover URIs |
timestamp |
2020-01-01T12:00:00.000Z |
Carimbo de data e hora (formato ISO 8601) |
headers |
{"caller-id": "447700900123"} |
O headers você definiu no websocket ponto final |
Voltar à lista de webhooks de eventos
Desconectado
A conexão WebSocket foi encerrada pelo seu servidor ou foi perdida e não será restabelecida. Isso ocorre quando a reconexão não está configurada, quando o seu servidor encerra a conexão de forma normal ou quando todas as tentativas de reconexão já foram esgotadas. Consulte Fechamentos puros e impuros. Se a resposta contiver um NCCO, ele será processado; caso não haja nenhum NCCO, a execução normal continuará.
| Campo | Exemplo | Descrição |
|---|---|---|
from |
442079460000 |
O número de onde a ligação foi feita |
to |
wss://primary.example.com/socket |
A principal uri do websocket ponto de extremidade. Ele não se altera após um failover ou uma reconexão. |
uuid |
aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
O identificador exclusivo desta chamada |
conversation_uuid |
CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
O identificador exclusivo desta conversa |
status |
disconnected |
Status da chamada |
timestamp |
2020-01-01T12:00:00.000Z |
Carimbo de data e hora (formato ISO 8601) |
cause |
remote_closed |
Por que a conexão foi encerrada. Aparece apenas quando o endpoint define pelo menos uma das opções de resiliência do WebSocket. Pode ser uma das seguintes opções:
|
reconnect_attempts |
0 |
O número de tentativas de reconexão realizadas antes de a Vonage desistir. 0 após um fechamento limpo ou quando reconnect não está definido. Só está presente quando o endpoint define pelo menos uma das opções de resiliência do WebSocket. |
close_code |
1012 |
O código de status do quadro Close enviado pelo seu servidor. Um quadro Close sem código é relatado como 1005. Aparece apenas quando um quadro de fechamento é recebido. |
close_reason |
service restart |
O texto de justificativa do quadro “Close” enviado pelo seu servidor, ou uma string vazia caso o quadro não contenha texto de justificativa. Apenas aparece quando um quadro “Close” é recebido. |
Observação: O cause, reconnect_attempts, close_code, e close_reason os campos não são incluídos quando a Vonage encerra a conexão, por exemplo, quando o limit do connect a ação é concluída.
Voltar à lista de webhooks de eventos
Rejeitado
A chamada foi rejeitada pela Vonage antes de ser conectada.
Observação: Em alguns cenários de rejeição, como a limitação do CPS, a chamada pode ser rejeitada antes que um recurso de chamada seja criado. Nesses casos, um uuid não está disponível.
| Campo | Exemplo | Descrição |
|---|---|---|
from |
442079460000 |
O número de onde a ligação foi feita |
to |
447700900000 |
O número para o qual a ligação foi feita |
uuid |
aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
O identificador exclusivo desta chamada |
conversation_uuid |
CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
O identificador exclusivo desta conversa |
status |
rejected |
Status da chamada |
detail |
restricted |
Indica se to ou from os números são inválidos (invalid_number), a chamada rejeitada pela operadora (restricted) ou rejeitada pelo destinatário (declined), ou limitada devido à ultrapassagem do limite de CPS da conta (throttled) |
direction |
outbound |
Direção da chamada, será esta outbound nesse contexto |
timestamp |
2020-01-01T12:00:00.000Z |
Carimbo de data e hora (formato ISO 8601) |
sip_code |
404 |
O código de status SIP retornado (por exemplo, 404, 480, ou 487) por meio do endereço registrado event_url, fornecendo detalhes adicionais sobre o motivo da conclusão ou da falha da chamada. Consulte os códigos de status SIP descritos aqui. |
Voltar à lista de webhooks de eventos
Falha
Não foi possível estabelecer a ligação.
| Campo | Exemplo | Descrição |
|---|---|---|
from |
442079460000 |
O número de onde a ligação foi feita |
to |
447700900000 |
O número para o qual a ligação foi feita |
uuid |
aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
O identificador exclusivo desta chamada |
conversation_uuid |
CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
O identificador exclusivo desta conversa |
status |
failed |
Status da chamada |
detail |
cannot_route |
Indica que o destino não é compatível ou está bloqueado para a Account (cannot_route), o número não está disponível (number_out_of_service) ou ocorreu um erro no servidor (internal_error) |
direction |
outbound |
Direção da chamada, será esta outbound nesse contexto |
timestamp |
2020-01-01T12:00:00.000Z |
Carimbo de data e hora (formato ISO 8601) |
sip_code |
404 |
O código de status SIP retornado (por exemplo, 404, 480, ou 487) por meio do endereço registrado event_url, fornecendo detalhes adicionais sobre o motivo da conclusão ou da falha da chamada. Consulte os códigos de status SIP descritos aqui. |
attempts |
[{"uri": "wss://a.example.com", "result": "timeout"}] |
Apenas presente quando o endpoint define pelo menos uma das opções de resiliência do WebSocket. O resultado de cada tentativa de conexão quando não foi possível estabelecer conexão com nenhum URI, com uma entrada por URI tentado. Cada entrada contém uri e result: timeout, refused, tls_error, ou http_ seguido pelo código de status HTTP, por exemplo http_503. Falhas na resolução de nomes e reinicializações de conexão são relatadas como refused, exceto uma consulta de DNS que atinge o tempo limite, o que é relatado como timeout. |
Voltar à lista de webhooks de eventos
Homem / Máquina
No caso de uma chamada de saída efetuada programaticamente, se o machine_detection Se a opção estiver definida, um evento com o status de human ou machine será enviada dependendo se a pessoa atendeu ou não a ligação.
| Campo | Exemplo | Descrição |
|---|---|---|
call_uuid |
aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
O identificador exclusivo desta chamada (Nota call_uuid, não uuid (assim como em alguns outros pontos finais) |
from |
442079460000 |
O número de onde a ligação foi feita |
to |
447700900000 |
O número para o qual a ligação foi feita |
status |
human |
Status da chamada: pode ser human se uma pessoa respondeu ou machine se a chamada foi atendida pelo correio de voz ou por outro serviço automatizado |
sub_state |
beep_start |
Indicador avançado da fase de detecção automática. Os valores possíveis são beep_start para o correio de voz, fax para aparelho de fax e beep_timeout. Quando o Call Screener Navigation [Beta] está ativo, são exibidos valores adicionais prompt_end e prompt_end_timeout. Veja Detecção Avançada por Máquina para mais detalhes. |
conversation_uuid |
CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
O identificador exclusivo desta conversa |
timestamp |
2020-01-01T12:00:00.000Z |
Carimbo de data e hora (formato ISO 8601) |
Voltar à lista de webhooks de eventos
Tempo limite
Se a duração da fase de toque exceder o valor especificado ringing_timeout durante esse período, este evento será enviado.
| Campo | Exemplo | Descrição |
|---|---|---|
from |
442079460000 |
O número de onde a ligação foi feita |
to |
447700900000 |
O número para o qual a ligação foi feita |
uuid |
aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
O identificador exclusivo desta chamada |
conversation_uuid |
CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
O identificador exclusivo desta conversa |
status |
timeout |
Status da chamada |
direction |
outbound |
Direção da chamada, será esta outbound nesse contexto |
timestamp |
2020-01-01T12:00:00.000Z |
Carimbo de data e hora (formato ISO 8601) |
Voltar à lista de webhooks de eventos
Concluído
A chamada terminou; este evento também inclui dados resumidos sobre a chamada.
| Campo | Exemplo | Descrição |
|---|---|---|
end_time |
2020-01-01T12:00:00.000Z |
Carimbo de data e hora (formato ISO 8601) |
uuid |
aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
O identificador exclusivo desta chamada |
network |
GB-FIXED |
O tipo de rede utilizada na chamada |
duration |
2 |
Duração da chamada (em segundos) |
start_time |
2020-01-01T12:00:00.000Z |
Carimbo de data e hora (formato ISO 8601) |
rate |
0.00450000 |
Custo por minuto da ligação (EUR) |
price |
0.00015000 |
Custo total da ligação (EUR) |
from |
442079460000 |
O número de onde a ligação foi feita |
to |
447700900000 |
O número para o qual a ligação foi feita |
conversation_uuid |
CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
O identificador exclusivo desta conversa |
status |
completed |
Status da chamada |
direction |
de entrada | Direção da chamada: pode ser inbound ou outbound |
timestamp |
2020-01-01T12:00:00.000Z |
Carimbo de data e hora (formato ISO 8601) |
disconnected_by |
user |
Pode assumir um dos dois valores:platform - A chamada foi encerrada pela plataforma da Voice API; por exemplo, o NCCO concluiu sua última ação e a chamada foi desconectada.user - A chamada foi encerrada pelo usuário; por exemplo, o usuário desligou, rejeitou a chamada ou não atendeu. |
sip_code |
404 |
O código de status SIP retornado (por exemplo, 404, 480, ou 487) por meio do endereço registrado event_url, fornecendo detalhes adicionais sobre o motivo da conclusão ou da falha da chamada. Consulte os códigos de status SIP descritos aqui. |
Observação: Para qualquer websocket trecho que define pelo menos uma das opções de resiliência do WebSocket, incluindo trechos criados por um connect ação, a completed O evento inclui os mesmos campos adicionais que Desconectado, quando a conexão foi encerrada pelo seu servidor ou se perdeu.
Voltar à lista de webhooks de eventos
Registro
Este webhook é acionado quando uma ação NCCO com a ação “registro” é concluída. Ao criar uma ação de registro, você pode definir um eventUrl para o qual esse evento deve ser enviado. Isso pode ser útil caso você queira usar um código separado para lidar com esse tipo de evento.
| Campo | Exemplo | Descrição |
|---|---|---|
start_time |
2020-01-01T12:00:00.000Z |
Carimbo de data e hora (formato ISO 8601) |
recording_url |
https://api.nexmo.com/v1/files/bbbbbbbb-aaaa-cccc-dddd-0123456789ab |
Onde baixar a gravação |
size |
12222 | O tamanho do arquivo de gravação (em bytes) |
recording_uuid |
aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
Um identificador único para esta gravação |
end_time |
2020-01-01T12:00:00.000Z |
Carimbo de data e hora (formato ISO 8601) |
conversation_uuid |
CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
O identificador exclusivo desta conversa |
timestamp |
2020-01-01T12:00:00.000Z |
Carimbo de data e hora (formato ISO 8601) |
Transcrição
| Campo | Exemplo | Descrição |
|---|---|---|
conversation_uuid |
CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
O identificador exclusivo desta conversa |
type |
record |
A ação NCCO do registro de tipo |
recording_uuid |
aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
Um identificador único para esta gravação |
status |
transcribed |
Status da transcrição |
transcription_url |
https://api.nexmo.com/v1/files/bbbbbbbb-aaaa-cccc-dddd-0123456789ab |
A URL do arquivo que contém a transcrição da gravação |
Voltar à lista de webhooks de eventos
Entrada
Este webhook é enviado pela Vonage quando um NCCO com a ação “input” é concluído.
| Campo | Exemplo | Descrição |
|---|---|---|
from |
447700900000 |
O número de onde a ligação foi feita |
to |
447700900000 |
O número para o qual a ligação foi feita |
dtmf |
veja abaixo | Resultados da captura de DTMF |
speech |
veja abaixo | Resultados do reconhecimento de fala |
uuid |
aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
O identificador exclusivo desta chamada. Essa propriedade pode não aparecer quando uma entrada atingir o tempo limite de DTMF. |
conversation_uuid |
CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
O identificador exclusivo desta conversa |
timestamp |
2020-01-01T12:00:00.000Z |
Carimbo de data e hora (formato ISO 8601) |
Resultados da captura de DTMF
| Campo | Exemplo | Descrição |
|---|---|---|
digits |
42 |
Os botões pressionados pelo usuário |
timed_out |
true |
Se a entrada de DTMF atingiu o tempo limite: true se fosse o caso, false se não |
Resultados do reconhecimento de fala
| Campo | Exemplo | Descrição |
|---|---|---|
timeout_reason |
end_on_silence_timeout |
Indica se a entrada foi encerrada quando o usuário parou de falar (end_on_silence_timeout), por tempo limite máximo (max_duration) ou se o usuário não tiver dito nada (start_timeout) |
results |
veja abaixo | Matriz de objetos de texto reconhecidos |
error |
ERR1: Failed to analyze audio |
Mensagem de erro. |
recording_url |
https://api-us.nexmo.com/v1/files/eeeeeee-ffff-0123-4567-0123456789ab |
Gravação de voz. Incluída se saveAudio o sinalizador está definido como true no input ação. Requer autorização JWT para o download; consulte Baixar uma gravação. |
Texto da transcrição
| Campo | Exemplo | Descrição |
|---|---|---|
text |
sales |
Texto da transcrição que representa as palavras que o usuário disse. |
confidence |
0.9405097 |
A estimativa de confiança varia entre 0,0 e 1,0. Um valor mais alto indica uma maior probabilidade estimada de que as palavras reconhecidas estejam corretas. |
Veja também o exemplo completo de payload apresentado em Referência NCCO
Voltar à lista de webhooks de eventos
Transferência
Este webhook é enviado pela Vonage quando uma etapa é transferida de uma conversa para outra. Isso pode ser feito por meio de um NCCO ou do transfer ação
| Campo | Exemplo | Descrição |
|---|---|---|
conversation_uuid_from |
CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
O ID da conversa em que a etapa estava originalmente |
conversation_uuid_to |
CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
O ID da conversa para a qual a etapa foi transferida |
uuid |
aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
O identificador exclusivo desta chamada |
timestamp |
2020-01-01T12:00:00.000Z |
Carimbo de data e hora (formato ISO 8601) |
Voltar à lista de webhooks de eventos
URL alternativa
O webhook de fallback é acionado quando o webhook de resposta ou o webhook de evento — caso se espere que o evento responda com um NCCO — retorna um código de erro HTTP ou fica inacessível. Os dados retornados pela URL de fallback são os mesmos que seriam recebidos na URL de resposta original ou na URL de evento, com a adição de dois novos parâmetros, reason e original_request:
{
"reason": "Connection closed.",
"original_request": {
"url": "https://api.example.com/webhooks/event",
"type": "event"
}
}
Se houve o fechamento ou a reinicialização de uma conexão, um tempo limite ou um código de status HTTP de 429, 503 ou 504 durante a NCCO inicial, a answer_url se for tentado duas vezes, então:
- Tentar entrar em contato com o
fallback_answer_urlduas vezes - Se não for bem-sucedida, a chamada é encerrada
Se houve o fechamento ou a reinicialização de uma conexão, um tempo limite ou um código de status HTTP de 429, 503 ou 504 durante uma chamada em andamento, o event_url para eventos que devem retornar um NCCO (por exemplo, retorno para um input ou notify ação) for tentada duas vezes, então:
- Tentar entrar em contato com o
fallback_answer_urlduas vezes - Se não for bem-sucedido, continue o fluxo da chamada
Erros
O endpoint de eventos também receberá webhooks em caso de erro. Isso pode ser útil na depuração do seu aplicativo.
| Campo | Exemplo | Descrição |
|---|---|---|
reason |
Syntax error in NCCO. Invalid value type or action. |
Informações sobre a natureza do erro |
conversation_uuid |
CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab |
O identificador exclusivo desta conversa |
timestamp |
2020-01-01T12:00:00.000Z |
Carimbo de data e hora (formato ISO 8601) |