Chamadas com marca PSTN usando a Voice API da Vonage e a First Orion

Crie chamadas de saída com identidade da marca usando a Voice API da Vonage e a First Orion. Exiba o nome da sua empresa, o logotipo e o motivo da chamada nas chamadas PSTN.

Introdução

Example of a branded incoming call displaying the company name, logo, and phone number on a mobile deviceSe você estiver fazendo chamadas de saída a partir de uma aplicação, é bem provável que algumas delas estejam sendo ignoradas ou marcadas como spam. Quando o destinatário não reconhece o número, muitas vezes ele não atende, mesmo que a chamada seja legítima.

Chamadas com identificação da marca PSTN resolve essa questão ao anexar informações de identidade verificadas às suas chamadas. Em vez de exibir apenas um número de telefone, o destinatário vê o nome da sua empresa, o logotipo e um breve motivo da chamada diretamente no seu aparelho. Na prática, isso torna suas chamadas mais fáceis de serem reconhecidas e aumenta as chances de serem atendidas.

Neste tutorial, você configurará as chamadas com marca própria na PSTN usando Voice API da Vonage e First Orion. Você configurará um programa de chamadas com marca, vinculá-lo-á a um número virtual da Vonage e, em seguida, fará uma chamada de saída a partir de um aplicativo simples em Node.js.

Ao final, você terá uma configuração funcional em que suas chamadas de saída exibam informações da marca em tempo real, juntamente com um aplicativo básico que poderá servir como ponto de partida para sua própria integração.

>> Resumo: Pule esta parte e veja o código de exemplo do aplicativo no GitHub.

Pré-requisitos

• Uma conta da API da Vonage com o recurso de voz ativado

• Um Account First Orion com um registro comercial aprovado

• Um número virtual da Vonage já foi provisionado para chamadas com marca PSTN

Chamadas com marca no First Orion

A First Orion oferece um conjunto de APIs e ferramentas de plataforma para gerenciar chamadas com identificação da marca em redes de operadoras. Eles chamam isso de plataforma INFORM, que controla como a identidade da sua empresa é apresentada nos dispositivos compatíveis. É na INFORM que você define elementos como o nome exibido, o logotipo e o motivo da chamada que aparecem quando uma chamada é recebida. A plataforma também oferece acesso a análises e controles no nível do programa, para que você possa acompanhar a entrega e fazer ajustes conforme necessário.

Para ativar o serviço de Chamadas com Identidade da Marca para um número de telefone, você precisará criar um programa. Você pode pensar em um programa como uma campanha. Um programa pertence a uma unidade de negócios, que, por sua vez, faz parte de uma empresa.

Hierarchy of branded calling in First Orion, showing how a business contains business units, which contain programsPara começar, você precisará registrar sua empresa na First Orion. Assim que sua empresa for aprovada e você tiver criado sua unidade de negócios, poderá criar seu primeiro programa:

First Orion Business Unit dashboard where you can create programs and manage phone numbers for branded callingA configuração de um programa envolve três etapas:

1. Detalhes: informações gerais sobre o programa

2. Exibição: o nome e a hora a serem exibidos aos usuários

3. Números de telefone: quais números serão atribuídos a este programa

Você pode criar um novo programa de uma das seguintes maneiras:

• por meio de a API

• por meio de o Portal do Cliente

Adding phone numbers and defining call purpose during branded calling program setup in First Orion

Depois que seu programa estiver criado, você poderá atribuir uma imagem a ele. Clique no programa para editá-lo. Em seguida, vá para a etapa 3, “Imagem”, onde você poderá adicionar uma imagem e o motivo da ligação:

Uploading a logo and defining the call reason for a branded calling program, with a real-time mobile preview

Como configurar chamadas com marca no Painel de Controle da Vonage

Depois de configurar o programa First Orion, você precisará configurar o link no Painel de Controle da Vonage. No Painel de Controle da Vonage, acesse Voice → Chamadas Confiáveis → Chamadas com marca PSTN.

Primeiro, você precisará seguir as instruções para integrar sua conta do First Orion. O ID de usuário é sua chave de API do First Orion, e a senha é a chave secreta associada. Você pode ver como gerar uma chave de API do First Orion na documentação.

Configuring the First Orion integration in the Vonage Dashboard using API credentialsCom a integração configurada, agora você poderá configurá-la. Abra a integração que você criou clicando na opção “editar”.

First Orion integration successfully configured in the Vonage Dashboard with an enabled virtual numberEm seguida, selecione “Ativar” no número virtual da Vonage que você adicionou anteriormente no painel do First Orion.

Managing and enabling virtual numbers for PSTN Branded Calling in the Vonage Dashboard

Como executar o aplicativo Vonage Test Voice

Agora que seu número virtual da Vonage está vinculado ao seu programa First Orion Branded Calling, você pode fazer uma chamada de saída com marca a partir de um aplicativo de teste simples em Node.js. O aplicativo de exemplo expõe uma interface local /call e usa o ngrok para tornar seus endpoints de webhook acessíveis ao público.

1. Clone o aplicativo de exemplo e instale as dependências

git clone git@github.com:Vonage-Community/blog-voice-node-branded_calling.git
cd branded-calling
npm install

2. Configure seu arquivo ENV

Copie o arquivo de ambiente de exemplo e, em seguida, edite-o:

cp .env.example .env

Você configurará três categorias de configurações:

A) Autenticação da Vonage (JWT / Applications)

• VONAGE_APPLICATION_ID
  O ID do aplicativo no Painel de Controle da Vonage 

• VONAGE_PRIVATE_KEY_PATH
  Caminho para o arquivo da sua chave privada (PEM). Neste tutorial, usaremos ./private.key.

B) Chamadas padrão

• FROM_NUMBER
  Seu número virtual da Vonage que você registrou/ativou para chamadas com marca (formato E.164, como +1408...).

• TO_NUMBER
  O número de destino padrão para sua chamada de teste (seu celular, etc.). Você pode substituir esse valor posteriormente na solicitação do curl.

C) Identidade visual

1. NOME_DA_EMPRESA

2. SAUDAÇÃO
   A mensagem de conversão de texto em fala reproduzida quando a chamada é atendida.

3. Inicie um túnel ngrok

A Vonage precisa conseguir acessar seus endpoints de webhook pela internet pública. A maneira mais fácil para o desenvolvimento local é usar o ngrok.

Em uma nova janela do terminal:

ngrok http 3000

Copie o URL de redirecionamento HTTPS (ela terá o formato https://xxxx.ngrok-free.app).

Agora defina isso no seu arquivo .env:

• PUBLIC_BASE_URL = sua URL HTTPS do ngrok

PUBLIC_BASE_URL=https://xxxx.ngrok-free.app

>> Importante: Se você reiniciar o ngrok, receberá uma nova URL e precisará atualizar PUBLIC_BASE_URL novamente.

4. Criar um aplicativo de Voice da Vonage

No Painel de Controle da Vonage:

• Criar um novo aplicativo

• Ativar recursos de voz

• Gere/baixe a chave privada (private.key) e coloque-a na raiz do seu projeto

• Copie o ID do aplicativo no seu arquivo .env como VONAGE_APPLICATION_ID

• No webhook de eventos do painel, adicione seu ngrok HTTPS seguido de /event (por exemplo, https://xxxx.ngrok-free.app/event)

5. Inicie o servidor local

De volta ao terminal do projeto, inicie seu aplicativo:

npm run start

6. Inicie a chamada de saída com o curl

Opção A: chamar o TO_NUMBER padrão do arquivo .env

curl -X POST http://localhost:3000/call \
  -H 'Content-Type: application/json' \
  -d '{}'

Opção B: substituir o número de destino a cada solicitação

curl -X POST http://localhost:3000/call \
  -H 'Content-Type: application/json' \
  -d '{"to":"+14155550100"}'

Agora você deve receber uma ligação exibindo sua identidade visual configurada (nome, logotipo e motivo da ligação).

Full-screen view of an incoming branded call displaying the company name, logo, and standard call controls on a mobile device

Observação: A exibição da marca depende da operadora e do comportamento do aparelho. Você pode verificar o “status por operadora” nos detalhes do seu programa.

Screenshot of the First Orion program details page displaying call metrics, answer rate, and carrier approval status for AT&T, Verizon, and T-Mobile.

Conclusão

Nesta fase, você já configurou o serviço de chamadas com marca própria na PSTN de ponta a ponta usando a Vonage e a First Orion. Você criou um programa de chamadas com marca própria, vinculou-o a um número virtual da Vonage e acionou uma chamada de saída a partir de um aplicativo Node.js que exibe sua marca configurada em tempo real.

Com essa base estabelecida, você pode começar a integrar as chamadas com a marca aos seus fluxos de trabalho existentes. Por exemplo, acionar chamadas a partir de eventos de Applications, personalizar dinamicamente os motivos das chamadas ou separar diferentes casos de uso em programas distintos.

Se você quiser ir um pouco além, a First Orion também oferece uma API de Autenticação de Chamadas que pode ser chamada logo antes de efetuar uma ligação. Isso permite que você registre explicitamente a intenção da ligação (quem está ligando e para quem) em tempo real, o que pode aumentar ainda mais a confiança e a verificação da ligação nas redes compatíveis. 

Esse padrão se encaixa naturalmente na configuração deste tutorial, já que é executado logo antes da sua solicitação de chamada de saída existente.

Em um ambiente de produção, você também deve substituir ferramentas locais, como o ngrok, por um endpoint estável e acessível ao público, além de garantir que suas credenciais e a configuração dos webhooks sejam gerenciadas de maneira consistente em todos os ambientes.

O modelo geral é simples: seu aplicativo controla o início da chamada, a Vonage cuida da entrega e a First Orion fornece a camada de identidade. Uma vez conectadas, as chamadas com marca própria tornam-se uma extensão direta dos fluxos de chamadas de saída que você já possui.