Compartilhar:
){kind=small}
Liz Acosta é Developer Advocate na Vonage. Embora sua trajetória profissional — de estudante de cinema a profissional de marketing, de engenheira a Developer Advocate — possa parecer pouco convencional, ela é bastante comum na área de Relações com Desenvolvedores! Liz adora pizza, plantas, pugs e Python.
Como atender uma chamada telefônica recebida com Python
Tempo de leitura: 14 minutos
Neste tutorial, você aprenderá a usar o Python FastAPI para desenvolver um aplicativo de voz que receba chamadas telefônicas usando a Voice API da Vonage. Softwares que recebem e encaminham chamadas telefônicas ajudam as empresas a melhorar a experiência do cliente. Eles permitem um atendimento mais personalizado e eficiente. Este tutorial irá guiá-lo por três cenários comuns de fluxo de chamadas de atendimento ao cliente:
Ao final deste tutorial, você saberá como atender chamadas recebidas de forma eficaz com o Vonage usando um aplicativo FastAPI em Python e ngrok. Este guia permitirá que você amplie os recursos do seu aplicativo para se conectar com os usuários em tempo real, tornando-o mais interativo e envolvente. Seja na criação de uma solução de atendimento ao cliente ou de uma ferramenta de comunicação, o domínio dessas habilidades aprimorará a funcionalidade do seu projeto e a experiência do usuário.
Os aplicativos de voz da Vonage utilizam Objetos de Controle de Chamadas da Vonage (NCCO) para construir fluxos de chamadas com ações NCCO. Em outras palavras, um NCCO é um array JSON de ações capazes de controlar chamadas recebidas. Um NCCO típico tem a seguinte aparência:
[
{"action": "talk",
"text": "Hello, one moment please, your call is being forwarded to our agent."},
{"action": "connect",
"from": VONAGE_NUMBER,
"endpoint": [{"type": 'phone',
"number": YOUR_SECOND_NUMBER}]}
]
Neste exemplo específico, há duas ações: talk e connect. Uma ação geralmente vem acompanhada de um conjunto de opções configuráveis do tipo chave-valor:
Para a
talkação, atextopção fornece o script de conversão de texto em fala. Saiba mais na documentação da ação NCCO Talk.A
connectação é configurada com duas opções:from, eendpoint. Consulte a referência da ação NCCO Connect para obter detalhes sobre a configuração.
O talk e connect ações são executadas de forma síncrona, na ordem em que estão listadas. Algumas ações podem ser configuradas para serem assíncronas. Isso pode ser útil ao criar um fluxo de chamadas no qual o chamador pode selecionar uma opção de um menu, como a escolha de um idioma. Nesse cenário, você não gostaria que o chamador tivesse que esperar até o fim de todo o menu de idiomas para prosseguir com a chamada. Isso é algo que você gostaria de fazer de forma assíncrona. Para entender como isso funciona, consulte o guia de ações assíncronas do NCCO.
Em resumo, os NCCOs fornecem os elementos básicos para a criação de fluxos de chamadas sofisticados, adaptados às suas necessidades específicas.
Para concluir este tutorial, vamos recorrer a Concepts técnicos e ferramentas externas à Vonage que podem ser úteis em outras áreas do desenvolvimento de software.
Um webhook é a forma pela qual uma aplicação baseada na web envia dados ou notificações de eventos para outra aplicação semelhante, permitindo a comunicação automática, em vez de uma aplicação ter que consultar constantemente a outra em busca de atualizações. Em geral, isso significa interagir pela web por meio de uma API, utilizando uma solicitação HTTP. Neste tutorial específico, usaremos um webhook para notificar seu aplicativo web de que alguém ligou para o seu número virtual e para retornar um NCCO com as ações do fluxo de chamada.
FastAPI é uma estrutura web de alto desempenho para a criação de APIs de serviços baseadas em HTTP em Python. O que diferencia o FastAPI de outras estruturas web em Python é sua estreita integração com Pydantic, uma biblioteca de validação de dados para Python. Esse acoplamento permite que o FastAPI valide, serialize e deserialize dados. Isso oferece um método mais declarativo para especificar a estrutura e os tipos de dados para solicitações recebidas, como corpos HTTP, e respostas enviadas. O FastAPI também gera automaticamente especificações OpenAPI . Todas essas características combinadas tornam a FastAPI especialmente adequada para APIs REST modernas, desenvolvimento de microsserviços e Applications que exigem funcionalidade em tempo real.
Neste tutorial, vamos criar um aplicativo web e executá-lo localmente no seu computador. Como ele estará sendo executado localmente, não poderá ser acessado pela internet pública; e, se o seu aplicativo web não puder ser acessado, a Vonage não poderá enviar uma solicitação ao webhook. É aí que entra o tunelamento. O tunelamento expõe servidores locais à internet pública por meio de URLs públicas temporárias ou estáticas. O ngrok é uma plataforma de software que oferece esse serviço.
Em resumo, vamos criar um aplicativo web em Python com o FastAPI e um webhook, e usar o ngrok para tornar seu aplicativo local acessível por meio de um túnel para uma URL pública, de modo que a Vonage possa efetivamente enviar uma solicitação para o webhook e processar uma chamada recebida, conforme definido no código.
Neste tutorial, usaremos o FastAPI para definir um webhook ao qual a Voice API poderá enviar uma solicitação quando alguém ligar para o seu número virtual. Usaremos o ngrok para expor o webhook à internet pública. E usaremos a Vonage para adquirir um número virtual, bem como a Voice API para realizar o tratamento das chamadas recebidas.
Se preferir, você pode baixar o código para atender uma chamada recebida da Comunidade Vonage no GitHub.
Para concluir este tutorial, você precisará do seguinte:
Python 3.8 ou superior
Uma Account no ngrok e instalação
Um número de telefone adicional para atuar como “agente” de conexão
Antes de começarmos a construir, vamos colocar tudo em ordem.
A Voice API precisa ter acesso ao seu webhook para poder enviar solicitações a ele; portanto, a URL do endpoint deve estar acessível pela internet pública.
Para fazer isso neste tutorial, vamos usar o ngrok. Confira nosso tutorial sobre o ngrok para saber como instalá-lo e usá-lo.
Em uma janela do terminal, crie um diretório para este projeto e, em seguida, acesse-o:
mkdir vonage-inbound-call && cd vonage-inbound-call
Agora que você já tem tudo configurado, é hora de começar a construir.
Este tutorial irá guiá-lo por três fluxos de chamadas diferentes:
Antes de abordarmos cada cenário, vamos primeiro criar um aplicativo da Vonage e preparar nosso ambiente de desenvolvimento, realizando as seguintes etapas:
A Voice API precisa ter acesso ao seu webhook para poder enviar solicitações a ele. Para isso, a URL do endpoint deve estar disponível na internet pública. É para isso que serve o ngrok.
Em uma janela separada do terminal, execute:
ngrok http 3000Este comando irá gerar as URLs públicas para as quais seu servidor local se conectará via túnel na porta 3000. Anote a URL pública — ela deve ter um formato semelhante a este:
Forwarding https://0a6ec0a950eb.ngrok-free.app -> http://localhost:3000
Primeiro, você precisa criar um aplicativo da Voice API. O “aplicativo” ao qual nos referimos aqui é um contêiner para as informações de configuração e segurança necessárias para a Voice API. Não é a mesma coisa que o aplicativo web FastAPI que também iremos criar.
Crie seu aplicativo da Voice API no painel do desenvolvedor acessando a Applications no menu à esquerda e clicando no botão “Criar novo aplicativo”. Isso abrirá o menu de criação de aplicativos. Dê ao seu aplicativo o nome inbound-call.
No âmbito das seção “Recursos” , ative a opção Voice, o que exibirá uma lista de campos de texto. No campo de texto intitulado URL de resposta, insira a URL pública do ngrok complementada com o webhook que você definiu no seu aplicativo FastAPI. Ficará mais ou menos assim: https://96b34a48a639.ngrok-free.app/webhooks/answer.
Clique no botão “Gerar novo pedido”.
A screenshot of the Create an application menu in the Vonage developer dashboard.Agora que seu aplicativo foi criado, você pode vincular seu número a ele clicando no botão “Vincular” na tabela de números disponíveis. Seu aplicativo agora está pronto para atender chamadas recebidas. Os cenários que vamos programar informam ao aplicativo o que fazer quando o /answer webhook for acionado.
Os ambientes virtuais do Python permitem que você instale pacotes em um local isolado do restante do seu sistema. Isso ajuda a evitar a desorganização em todo o sistema e conflitos entre diferentes versões do Python e pacotes. Confira nossa postagem no blog sobre ambientes virtuais para saber mais.
No diretório do seu projeto, execute os seguintes comandos para criar um ambiente virtual e ativá-lo:
python3 -m venv venv && source venv/bin/activateAgora você deve ver o prompt do terminal precedido por (venv). Para desativar seu ambiente virtual, execute o deactivate comando.
Para instalar as dependências necessárias para este tutorial, execute o seguinte:
pip install vonage python-dotenv 'fastapi[standard]'Agora temos tudo o que precisamos para começar a programar.
Nesse cenário específico, responderemos a uma chamada recebida em um número virtual reproduzindo uma mensagem gerada por conversão de texto em fala.
Crie um arquivo chamado scenario-1.py que inclua o seguinte código:
from fastapi import FastAPI, Query
from vonage_voice import Talk
app = FastAPI()
@app.get('/webhooks/answer')
async def answer_call(from_: str = Query(..., alias='from')):
from_ = '-'.join(from_)
return [Talk(text=f'Thank you for calling from {from_}').model_dump(by_alias=True, exclude_none=True)]
Este código cria o /webhooks/answer ponto de extremidade. Quando esse ponto de extremidade recebe uma solicitação da Voice API, ele cria e percorre um lista de NCCOs com uma Talk ação. É isso que é responsável pela conversão de texto em fala que o chamador ouve ao discar o número. Para saber mais sobre como responder a chamadas com conversão de texto em fala, confira nossos exemplos de código.
Agora é hora de testar seu aplicativo.
Na janela do terminal, execute:
fastapi dev --port 3000 scenario-1.pyIsso iniciará um servidor local com o endpoint do seu webhook na porta 3000. Seu aplicativo está pronto para receber chamadas!
Ligue para o número virtual que você vinculou ao aplicativo no painel de controle. Se tudo estiver funcionando corretamente, você deverá ouvir a mensagem de conversão de texto em fala que definiu no seu código Python.
Após os testes, encerre o servidor para que você possa programar o próximo cenário.
Nesse cenário, incluiremos a ação NCCO Connect que conectará o chamador a um agente após a conclusão da Talk ação.
Crie um novo arquivo chamado scenario-2.py e adicione o seguinte código:
from fastapi import FastAPI, Query
from vonage_voice import Talk, Connect, NccoAction, PhoneEndpoint
VONAGE_VIRTUAL_NUMBER = 'Replace-this-text-with-your-Vonage-virtual-number'
AGENT_NUMBER = 'Replace-this-text-with-your-agent-number'
app = FastAPI()
@app.get('/webhooks/answer')
async def answer_call():
ncco: list[NccoAction] = [
Talk(text="Hello, one moment please while your call is being forwarded to our agent."),
Connect(from_=VONAGE_VIRTUAL_NUMBER,
endpoint=[PhoneEndpoint(number=AGENT_NUMBER)]),]
return [action.model_dump(by_alias=True, exclude_none=True) for action in ncco]Este código cria o /webhooks/answer ponto de extremidade. Quando esse ponto de extremidade recebe uma solicitação da Voice API, ele cria e percorre um lista de NCCOs com uma Talk ação e, em seguida, uma Connect ação. A Connect ação exige que você forneça tanto o seu número virtual da Vonage quanto um número de agente adicional para as variáveis VONAGE_VIRTUAL_NUMBER e AGENT_NUMBER, respectivamente. Você pode ler mais sobre como conectar chamadas com a Voice API aqui.
Encerre todas as applications que estejam em execução em qualquer outro cenário deste tutorial e execute:
fastapi dev --port 3000 scenario-2.pyPara testar esse cenário específico, você precisará de dois números de telefone: um para ligar para o número virtual e outro para o qual a ligação será encaminhada. Disque para o seu número virtual da Vonage e, se tudo tiver sido configurado corretamente, você deverá ouvir a mensagem de conversão de texto em fala e, em seguida, o seu segundo número (o número do agente) deverá tocar.
Nesse cenário, atendemos uma chamada recebida colocando o chamador em espera e reproduzindo música até que um agente esteja disponível. Em seguida, a chamada é transferida para o agente.
Este é o fluxo de chamadas que vamos implementar:
Quando a chamada for atendida, a pessoa que ligou ouvirá uma mensagem gerada por conversão de texto em fala
O chamador será colocado em espera e ouvirá música
Após um atraso simulado de 30 segundos, a chamada será encaminhada para um segundo NCCO
O segundo NCCO reproduz uma mensagem de conversão de texto em fala e conecta o chamador a um agente
Como esse cenário específico utiliza a Voice API para atualizar uma chamada em andamento, precisamos do ID do aplicativo da Vonage e de uma chave privada para criar um cliente. Isso garante que o usuário que está fazendo a atualização esteja autorizado e seja o proprietário da chamada – seria bem perturbador se, de repente, você ouvisse música de espera durante uma ligação com um amigo! O ID do aplicativo e a chave privada podem ser obtidos por meio do painel de desenvolvedores da Vonage.
No menu “Applications” do painel do desenvolvedor, clique no aplicativo que você criou para este tutorial e, em seguida, clique em “Editar”. Assim que a janela de edição for aberta, clique no botão que diz “Gerar chave pública e privada”. Isso iniciará o download da sua chave privada como um arquivo com a extensão .key. Mantenha esse arquivo em sigilo e não o compartilhe em nenhum lugar onde possa ser comprometido. Clique no botão “Salvar alterações” e anote também seu ID do aplicativo.
A screenshot of the application Edit menu in the Vonage developer dashboard showing where to generate a public and private key.
A screenshot of the inbound-call application in the Vonage developer dashboard showing where you can find the application ID.Mova o arquivo da sua chave privada para o mesmo diretório em que está localizado o seu código Python. Nesse mesmo diretório, crie um arquivo chamado .env e adicione o seguinte:
APPLICATION_ID=Replace-this-with-your-application-ID
PRIVATE_KEY=Replace-this-with-the-name-of-your-private-key-file
Crie um novo arquivo chamado scenario-3.py e adicione o seguinte código:
import os
from dotenv import load_dotenv
from threading import Timer
from fastapi import FastAPI, Query
from vonage import Auth, Vonage
from vonage_voice import Talk, Connect, NccoAction, PhoneEndpoint, Stream
load_dotenv()
APPLICATION_ID = os.getenv("APPLICATION_ID")
PRIVATE_KEY = os.getenv("PRIVATE_KEY")
VONAGE_VIRTUAL_NUMBER = '**********' # Replace with your Vonage virtual number
AGENT_NUMBER = '**********' # Replace with your "agent" number
AUDIO_URL = "https://download.samplelib.com/mp3/sample-12s.mp3"
app = FastAPI()
def transfer_call(call_id):
print("Transferring the call ... ")
ncco: list[NccoAction] = [
Talk(text="Hello, one moment please while your call is being forwarded to our agent."),
Connect(from_=VONAGE_VIRTUAL_NUMBER,
endpoint=[PhoneEndpoint(number=AGENT_NUMBER)]),]
client = Vonage(Auth(application_id=APPLICATION_ID, private_key=PRIVATE_KEY,))
client.voice.transfer_call_ncco(uuid=call_id, ncco=ncco)
@app.get('/webhooks/answer')
async def answer_call(call_id: str = Query(..., alias='uuid')):
print(f"The UUID for this call is:====> {call_id}")
Timer(30, transfer_call, [call_id]).start()
ncco: list[NccoAction] = [
Talk(text="Hello, our agents are assisting other customers. Please hold and we will connect you as soon as possible."),
Stream(streamUrl=[AUDIO_URL],loop=0),]
return [action.model_dump(by_alias=True, exclude_none=True) for action in ncco]Há muitas coisas acontecendo nesse código, então vamos analisá-lo passo a passo.
Primeiro, você precisará atualizar as seguintes variáveis:
VONAGE_VIRTUAL_NUMBER: Substitua o texto do espaço reservado pelo seu número virtual da Vonage
NÚMERO_DO_AGENTE: Substitua o texto do espaço reservado pelo número de telefone do “agente” para o qual a chamada será transferida
Neste código, definimos o /webhooks/answer endpoint. Quando esse endpoint recebe uma solicitação da Voice API, ele cria e percorre um lista NCCO com uma Talk ação e, em seguida, uma Stream ação para reproduzir a música de espera.
A função transfer_call é responsável por criar um cliente Vonage e, em seguida, transferir a chamada usando seu número identificador exclusivo.
Como estamos simulando como seria ficar em espera, o código usa um Timer objeto para chamar a transfer_call função após 30 segundos.
Agora que você entendeu o código, vamos colocá-lo em execução. Certifique-se de que não haja nenhum outro aplicativo em execução e, em seguida, execute:
fastapi dev --port 3000 scenario-3.pyPara testar esse cenário específico, você precisará de dois números de telefone: um para ligar para o número virtual e outro para o qual a ligação será transferida. Disque para o seu número virtual da Vonage e, se tudo tiver sido configurado corretamente, você deverá ouvir uma mensagem de conversão de texto em fala, seguida de música de espera. Após 30 segundos, a chamada será transferida para o número do agente que você forneceu.
Neste tutorial, você aprendeu a lidar com chamadas telefônicas recebidas usando a Voice API da Vonage e um aplicativo FastAPI em Python. Você explorou como os Objetos de Controle de Chamadas da Vonage (NCCOs) definem os fluxos de chamadas e como os webhooks permitem que seu aplicativo responda às chamadas recebidas em tempo real. Por meio de três cenários práticos, você implementou fluxos de trabalho comuns de atendimento ao cliente: reproduzir uma mensagem de conversão de texto em fala, conectar um chamador a um agente e colocar um chamador em espera com música antes de transferir a chamada.
Além disso, você configurou um aplicativo da Voice API, expôs um servidor FastAPI local usando o ngrok e utilizou a Voice API para atualizar uma chamada em andamento. Esses elementos fundamentais podem aprimorar significativamente as interações com os clientes, melhorar os tempos de resposta e otimizar as operações das empresas. Por exemplo, você pode criar um sistema de teleconferência, criar fluxos de chamadas personalizadosou acompanhar o desempenho de campanhas.
Para quem estiver interessado em aprofundar ainda mais seus conhecimentos, sugerimos explorar artigos relacionados sobre Aplicações de Voice em Python ou Integração de APIs para descobrir técnicas mais avançadas. A implementação desses Concepts pode abrir oportunidades para experiências personalizadas para os clientes e automação, o que pode impulsionar o crescimento e a eficiência dos negócios.
Confira a referência da Voice API para obter uma lista completa de recursos que você pode incorporar aos seus aplicativos de Voice
Você também pode ler mais sobre as ações da NCCO no guia oficial
Conecte seu servidor de desenvolvimento local à API da Vonage usando um túnel Ngrok
Tem alguma dúvida ou quer compartilhar o que está criando?
Inscreva-se no Boletim Informativo para Desenvolvedores
Siga-nos no X (antigo Twitter) para ficar por dentro das novidades
Assista aos tutoriais no nosso canal do YouTube
Conecte-se conosco na página de desenvolvedores da Vonage no LinkedIn
Fique conectado e acompanhe as últimas notícias, dicas e eventos para desenvolvedores.
Compartilhar:
Liz Acosta é Developer Advocate na Vonage. Embora sua trajetória profissional — de estudante de cinema a profissional de marketing, de engenheira a Developer Advocate — possa parecer pouco convencional, ela é bastante comum na área de Relações com Desenvolvedores! Liz adora pizza, plantas, pugs e Python.