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

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.

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

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 exijam 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:

• started
• ringing
• answered
• busy
• cancelled
• unanswered
• disconnected
• rejected
• failed
• human/machine
• timeout
• completed
• record
• input
• transfer

Iniciado

Indica que a chamada foi criada.

{
  "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.

Voltar à lista de webhooks de eventos

Respondido

A ligação foi atendida.

Voltar à lista de webhooks de eventos

Ocupado

O destinatário está na linha com outro interlocutor.

Voltar à lista de webhooks de eventos

Cancelado

Uma chamada efetuada é cancelada pelo autor antes de ser atendida.

Voltar à lista de webhooks de eventos

Sem resposta

Ou o destinatário está indisponível ou recusou a chamada.

Voltar à lista de webhooks de eventos

Desconectado

Se a conexão WebSocket for encerrada pelo lado do aplicativo por qualquer motivo, a chamada de retorno do evento de desconexão será enviada; se a resposta contiver um NCCO, este será processado; caso não haja nenhum NCCO, a execução normal continuará.

Voltar à lista de webhooks de eventos

Rejeitado

A chamada foi rejeitada pela Vonage antes de ser conectada.

Voltar à lista de webhooks de eventos

Falha

Não foi possível estabelecer a ligação.

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.

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.

Voltar à lista de webhooks de eventos

Concluído

A chamada terminou; este evento também inclui dados resumidos sobre a chamada.

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.

Transcrição

Voltar à lista de webhooks de eventos

Entrada

Este webhook é enviado pela Vonage quando um NCCO com a ação “input” é concluído.

Resultados da captura de DTMF

Resultados do reconhecimento de fala

Texto da transcrição

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

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:

1. Tentar entrar em contato com o fallback_answer_url duas vezes
2. 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:

1. Tentar entrar em contato com o fallback_answer_url duas vezes
2. 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.