Detalhes técnicos

NOTA: Esta seção da documentação descreve Applications V2 funcionalidade.

Um aplicativo da API da Vonage contém as informações de segurança e configuração necessárias para se conectar aos terminais da Vonage e utilizar as APIs da Vonage.

Cada Application da Vonage criado pode oferecer vários recursos — por exemplo, é possível criar um aplicativo que ofereça suporte ao uso das Voice API, Messages API e RTC.

Para ilustrar o uso das Applications da Vonage, apresentamos aqui um breve resumo sobre como criar e utilizar uma Application de voz da Vonage:

Crie um aplicativo Vonage usando a CLI, o Painel de Controle ou a API do aplicativo.
Certifique-se de configurar as URLs dos seus webhooks. A Vonage enviará respostas para essas URLs com informações importantes.
Associe um número da Vonage ao seu aplicativo da Vonage.
Crie seu aplicativo web. Implemente os endpoints de webhook que você configurou na etapa 2, utilizando as APIs da Vonage conforme necessário.

Por exemplo, se você quiser criar um aplicativo que reencaminha as chamadas recebidas para um telefone de destino, você deve seguir os seguintes passos:

Você cria uma aplicação da Vonage que possui recursos de voz.
Você configura as URLs de resposta e de webhook de eventos.
Você associa um número da Vonage ao seu aplicativo da Vonage.
Você implementa um aplicativo web que responde a chamadas de retorno nas URLs de webhook.
Quando é recebida uma chamada no número da Vonage associado ao aplicativo da Vonage, uma NCCO é retornado no answer_url.

Outros tipos de applications, como aqueles com recursos de Mensagens e Despacho, seguem um processo ligeiramente diferente, descrito nas seções pertinentes deste documentação.

As seções a seguir explicam as aplicações da Vonage com mais detalhes.

Estrutura

Cada aplicativo possui o seguinte:

Nome	Descrição
`id`	Utilizado para identificar cada aplicativo e usado em conjunto com `private_key` para gerar JWTs.
`name`	O nome do aplicativo.
`capabilities`	Descreve os tipos de funcionalidades que este aplicativo oferecerá. Os recursos `voice`, `messages`, `rtc`, `vbc`. É possível oferecer qualquer número desses recursos em um único aplicativo. Você também define `webhooks` para cada recurso especificado. A Vonage envia e recebe informações por meio dos pontos de conexão do webhook.
`keys`	Contém `private_key` e `public_key`. Você usa a chave privada para gerar os JWTs utilizados para autenticar suas chamadas às APIs da Vonage. A chave pública é usada pela Vonage para autenticar o JWT em suas solicitações à API da Vonage.

Recursos

Um aplicativo da Vonage pode utilizar várias APIs, incluindo Voice API, Messages API e Dispatch API, além da Conversion API e do Client SDK.

Ao criar uma aplicação, você pode especificar os recursos que deseja que ela ofereça. Para cada recurso, é possível configurar webhooks de acordo com as funcionalidades desejadas; por exemplo, para uma aplicação com um rtc com essa funcionalidade, você poderia especificar uma URL de evento para receber eventos RTC. Se seu aplicativo também precisasse usar voice Além disso, você também pode definir uma URL de resposta para receber um webhook de chamada atendida, uma URL alternativa caso a URL de resposta falhe e outra URL de evento para receber eventos relacionados a chamadas de voz.

A tabela a seguir apresenta um resumo dos recursos:

Capacidade	Descrição
`voice`	Utilizado para oferecer suporte a recursos de voz.
`messages`	Utilizado para oferecer suporte aos recursos da Messages API e da Dispatch API.
`rtc`	Utilizado para oferecer suporte aos recursos do WebRTC. Normalmente, é usado com o Client SDK.
`vbc`	Era usado para determinar preços, mas atualmente não possui outras funcionalidades.

Webhooks

As URLs dos webhooks que você fornece ao criar uma aplicação dependem dos recursos necessários para a aplicação. A tabela a seguir resume os webhooks:

Capacidade	API utilizada	Webhooks disponíveis
`voice`	Voz	`answer_url`, `fallback_answer_url`, `event_url`
`messages`	Mensagens e Despacho	`inbound_url`, `status_url`
`rtc`	Client SDK	`event_url`
`vbc`	VBC	Nenhum

Tipos de webhooks

A tabela a seguir descreve os webhooks disponíveis por recurso:

Capacidade	Webhook	API	Exemplo	Descrição
`voice`	`answer_url`	Voz	https://example.com/webhooks/answer	A URL para a qual a Vonage envia uma solicitação quando uma chamada é feita ou recebida. Deve retornar um NCCO.
`voice`	`fallback_answer_url`	Voz	https://example.com/webhooks/fallback	Se o `fallback_answer_url` estiver configurado, a Vonage envia uma solicitação para ele se o `answer_url` está offline ou retorna um código de erro HTTP ou o `event_url` está offline ou retorna um código de erro, e espera-se que um evento retorne um NCCO. O `fallback_answer_url` deve retornar um NCCO. Se o seu `fallback_answer_url` Se a tentativa inicial de NCCO falhar após duas tentativas, a chamada é encerrada. Se o seu `fallback_answer_url` Se a chamada falhar após duas tentativas enquanto estiver em andamento, o fluxo da chamada é continuado.
`voice`	`event_url`	Voz	https://example.com/webhooks/event	A Vonage enviará eventos de chamadas (por exemplo, toque, atendimento) para esta URL.
`messages`	`inbound_url`	Mensagens, Despacho	https://example.com/webhooks/inbound	A Vonage encaminhará as mensagens recebidas para esta URL.
`messages`	`status_url`	Mensagens, Despacho	https://example.com/webhooks/status	A Vonage enviará atualizações sobre o status das mensagens (por exemplo, `delivered`, `seen`) para esta URL.
`rtc`	`event_url`	Client SDK, Conversa	https://example.com/webhooks/rtcevent	A Vonage enviará eventos RTC para esta URL.
`vbc`	Nenhum	Terminal de voz	Nenhum	Não utilizado

Tempos limite dos webhooks

Para o voice Apenas como recurso, é possível definir tempos limite para os webhooks. Existem dois tempos limite que podem ser especificados: connection_timeout e socket_timeout. Esses parâmetros se aplicam ao answer, event, e fallback webhooks e são especificados em milissegundos. A tabela a seguir fornece mais informações:

Parâmetro	Exemplo	Descrição
`connection_timeout`	`1000`	Se a Vonage não conseguir se conectar à URL do webhook durante esse período especificado, ela fará mais uma tentativa de se conectar ao endpoint do webhook. Trata-se de um valor inteiro especificado em milissegundos.
`socket_timeout`	`3000`	Se não for possível ler uma resposta da URL do webhook durante esse período de tempo especificado, a Vonage fará mais uma tentativa de ler o endpoint do webhook. Trata-se de um valor inteiro especificado em milissegundos.

Ao criar ou atualizar uma aplicação, esses parâmetros podem ser definidos diretamente ou atualizados conforme necessário, por exemplo:

...
  "capabilities": {
    "voice": {
      "webhooks": {
        "answer_url": {
          "address": "https://example.com/webhooks/answer",
          "http_method": "POST",
          "connection_timeout": 500,
          "socket_timeout": 3000
        },
        "fallback_answer_url": {
          "address": "https://fallback.example.com/webhooks/answer",
          "http_method": "POST",
          "connection_timeout": 500,
          "socket_timeout": 3000
        },
        "event_url": {
          "address": "https://example.com/webhooks/event",
          "http_method": "POST",
          "connection_timeout": 500,
          "socket_timeout": 3000
        }
      }
    }
...

Se esses valores não forem especificados ao criar ou atualizar o aplicativo, serão aplicados os valores padrão. Os valores padrão para esses tempos limite dependem do webhook em questão, conforme mostrado na tabela a seguir:

Webhook	Padrão `connection_timeout`	Padrão `socket_timeout`
`answer`	1000	5000
`event`	1000	10000
`fallback`	1000	5000

NOTA: Os tempos limite são especificados em milissegundos.

Há mais explicações sobre os tempos limite dos webhooks no documentação sobre webhooks.

Criação de aplicativos

Existem quatro maneiras principais de criar uma aplicação:

Na Vonage Painel de controle. Applications are, then, listed in the suas inscrições seção do Painel.
Usando o CLI da Vonage.
Usando o API do aplicativo.
Usando um dos serviços da Vonage SDKs de servidor.