Trabalhando com as APIs da Vonage

Bem-vindo à plataforma de APIs da Vonage! A Vonage oferece um conjunto de APIs que permitem que você se comunique com seus clientes por meio dos canais de sua preferência.

Este site oferece documentação completa sobre todas as nossas APIs, e você encontrará tudo o que precisa saber sobre como trabalhar com uma determinada API na seção correspondente.

No entanto, há alguns conceitos fundamentais que você precisa entender e ferramentas que podem ajudá-lo e que se aplicam a todas as nossas APIs:

Criação de um account

Para trabalhar com nossas APIs, você precisará criar um Account. Isso lhe fornecerá uma chave e um segredo de API que você poderá usar para acessar nossas APIs.

Acessando o Painel do Desenvolvedor

Depois de criar uma conta, você pode fazer login no Painel do desenvolvedor. O Painel do Desenvolvedor é uma interface gráfica para gerenciar seu Account, na qual você pode:

  • Visualize sua chave e seu segredo da API. Você precisará deles para autenticar suas solicitações às nossas APIs
  • Gerencie o saldo da sua conta. O acesso às nossas APIs é cobrado por solicitação. Ofereceremos a você um crédito gratuito quando você abrir seu Account pela primeira vez, e você poderá recarregar quando estiver acabando.
  • Alugue números virtuais. Você pode usar números virtuais oferecido pela Vonage para fazer e receber chamadas e mensagens. Consulte alugar um número virtual.
  • Gerenciar aplicativos. Algumas de nossas APIs (como a de Voz e a de Mensagens) exigem que você crie um Applications, que funciona como um repositório de informações de segurança e configuração. É possível criar e gerenciar essas Applications no Painel do Desenvolvedor.
  • Gerencie seu account. Você pode realizar outras tarefas administrativas aqui.

Como usar a CLI da Vonage

Opcionalmente, você pode executar muitas das tarefas do Painel de Controle a partir da linha de comando, usando a CLI da Vonage. Isso costuma ser mais rápido e também permite automatizar essas operações por meio de scripts.

A CLI da Vonage foi desenvolvida com oclif e pode ser instalado usando o Node Package Manager (npm). O README no Repositório do Vonage CLI no GitHub mostra como instalar e utilizar a CLI da Vonage.

Autenticação

Ao utilizar as APIs da Vonage, suas solicitações precisam ser autenticado. Normalmente, isso é feito usando Autenticação básica ou JWTs. Você pode gerar um JWT adequado usando a CLI da Vonage ou nosso ferramenta online. Embora Autenticação básica funcionará, mas não permitirá que você receba webhooks — esses só podem ser ativados usando JWTs.

Se for utilizada a Autenticação Silenciosa com o Verify, ela deve ser o primeiro canal na matriz de fluxos de trabalho.

Experimentando nossas APIs

No fim das contas, você vai querer criar um aplicativo no seu linguagem de programação escolhida. Mas, para começar, talvez seja uma boa ideia fazer algumas solicitações de teste às nossas APIs para verificar se você forneceu os parâmetros corretos e se está recebendo as respostas desejadas.

Se você estiver familiarizado com a ferramenta de linha de comando Curl, você encontrará trechos de código em Curl para cada uma de nossas APIs, que poderá copiar, colar e modificar.

Carteiro

Existem várias ferramentas com interface gráfica que são mais fáceis de usar do que o Curl. Uma delas, bastante popular, é Carteiro. Leia nosso guia sobre usando o Postman para trabalhar com nossas APIs. A Vonage também oferece um conjunto de Coleções do Postman, que oferece uma maneira de começar a usar as APIs imediatamente.

OpenAPI

Cada uma de nossas APIs tem sua própria Especificação OpenAPI. Você pode ler mais sobre o OpenAPI em nosso documentação. Nossas especificações estão em conformidade com a especificação OpenAPI versão 3, também conhecida como OAS3.

Como usar um SDK de servidor

Quando estiver pronto para começar a desenvolver seu aplicativo, é recomendável usar um dos nossos SDKs de servidor, em vez de programar cada solicitação manualmente. Você pode encontrar links para todos os nossos SDKs na Ferramentas página.

Trabalhando com Webhooks

Depois de aprender a fazer solicitações às nossas APIs para realizar chamadas, enviar mensagens e assim por diante, você vai querer aprender a receber comunicações no seu número virtual.

Quando nossas APIs precisam notificar seu aplicativo sobre algo — seja uma chamada recebida, uma mensagem ou uma atualização de status —, elas exigem que seu aplicativo disponibilize um endpoint de URL ao qual nossa plataforma possa enviar uma solicitação. Esses endpoints devem estar acessíveis pela Internet pública.

Esses endpoints são chamados de Webhooks. Saiba mais sobre webhooks. Depois de criar seu webhook, você deve configurar nossa plataforma de API para usá-lo. O processo para fazer isso depende da API que você estiver usando, e as instruções completas podem ser encontradas na documentação dessa API.

Tornar esses webhooks acessíveis ao público durante o desenvolvimento pode ser complicado; por isso, recomendamos uma ferramenta chamada Ngrok.

Acesse nosso guia sobre testando com o Ngrok para aprender a usá-lo.

Formato numérico

Nas APIs da Vonage, todos os números de telefone estão em formato E.164. Isso significa que os números:

  • Omita tanto o + e o código de acesso internacional, como, por exemplo, 00 ou 001.
  • Não conter caracteres especiais, como espaço, () ou -

Por exemplo, um número dos EUA teria o formato 14155550101. Um número do Reino Unido teria o formato 447700900123.

Se você não souber como formatar o número, o Number Insight API pode ser usado para encontrar informações corretas sobre um número.

Veja também Formato numérico na documentação da Voice API.

Concepts

Existem vários conceitos em comum entre as APIs da Vonage: o uso de JSON Web Tokens (JWTs), solicitações assinadas e webhooks. Os guias a seguir explicam em detalhes como utilizar esses elementos.

  • Applications - Informações de segurança e configuração necessárias para se conectar aos terminais da Vonage.
  • Autenticação – Chaves de API e tokens JSON da Web (JWTs).
  • Assinatura de mensagens – como assinar criptograficamente mensagens e verificar as assinaturas das mensagens.
  • Webhooks – A API da Vonage pode enviar dados de volta para o seu servidor web por meio de um webhook.
  • OpenAPI – Todas as APIs da Vonage possuem descrições no OpenAPI que você pode utilizar em seu próprio processo de desenvolvimento.
  • Glossário – Um glossário de termos comuns utilizados em toda a plataforma da Vonage.

O que fazer a seguir

Este guia apresentou a você alguns dos Concepts e ferramentas fundamentais que você deve conhecer ao trabalhar com nossas APIs.

Depois de compreender esses conceitos fundamentais e instalar as ferramentas que pretende usar, você estará pronto para começar a criar! Acesse o documentação da API que você escolheu para começar.

Se você tiver alguma dificuldade, consulte nosso Slack da comunidade, ou consulte nossa base de conhecimento e entre em contato para obter ajuda, se necessário, pelo nosso site de suporte.