Início rápido do Programmable Voice para Python
Com apenas algumas linhas de código, seu aplicativo Python pode fazer e receber chamadas telefônicas com o Programmable Voice da Twilio.
Este início rápido do Python ensina como fazer isso usando nossa API REST, a biblioteca auxiliar Twilio Python e a microestrutura do Flask do Python para facilitar o desenvolvimento.
Neste início rápido, você aprende a:
- Inscrever‐se na Twilio e obter o primeiro número de telefone Twilio habilitado para voz
- Configurar o ambiente de desenvolvimento para fazer e receber chamadas telefônicas
- Fazer uma chamada telefônica de saída que reproduza um MP3
- Receber e responder a uma chamada telefônica de entrada que leia uma mensagem para o autor da chamada usando conversão de texto em voz
Prefere começar assistindo a um vídeo? Confira nosso vídeo no YouTube sobre como fazer e receber chamadas telefônicas com Python.
Inscreva‐se na Twilio e obtenha um número de telefone
Se já tiver uma conta e um número de telefone da Twilio habilitado para voz, tudo está em ordem! Faça login e fique à vontade para ir para a próxima etapa.
Para fazer uma chamada telefônica do Python, é necessário uma conta Twilio. Inscreva‐se aqui para obter sua conta de avaliação gratuita ou faça login em uma conta que você já possui.
A próxima coisa que você precisa é um número de telefone da Twilio com capacidade de voz. Se você não possui atualmente um número de telefone da Twilio com funcionalidade de chamada de voz, precisará adquirir um. Após navegar até a página Comprar um número, marque a caixa "Voice" (Voz) e clique em "Search" (Pesquisar).
Você verá uma lista de números de telefone disponíveis e seus recursos. Encontre um número que se adapte às suas necessidades e clique em "Buy" (Comprar) para adicioná‐lo à sua conta.
Com uma conta Twilio e um número de telefone programável, você tem as ferramentas básicas necessárias para fazer uma chamada telefônica.
Você pode usar a API HTTP do Twilio para fazer chamadas telefônicas, mas vamos simplificar ainda mais com a biblioteca auxiliar Python oficial da Twilio. Vamos instalar em seguida.
Instale o Python e a biblioteca auxiliar da Twilio
Se você já passou por outro de nossos inícios rápidos do Python e já tem o Python e a biblioteca auxiliar da Twilio Python instalada, você pode pular esta etapa e ir direto para fazer sua primeira ligação telefônica.
Para fazer sua primeira chamada telefônica com a Twilio, você precisa instalar o Python e a biblioteca auxiliar do Twilio Python.
Instale o Python
Se você estiver usando uma máquina Mac ou Linux, provavelmente já tem o Python instalado. Você pode verificar isso abrindo um terminal e executando o seguinte comando:
python --version
Você deve ver algo como:
$ python --version
Python 3.9 # Python 3.6+ is okay, too
Os usuários do Windows podem seguir este excelente tutorial para instalar o Python no Windows.
O SDK Python Twilio só suporta Python 3.6 ou superior.
Instalar a biblioteca auxiliar Python Twilio
A maneira mais fácil de instalar a biblioteca é usando o PIP. Basta executá‐lo no terminal:
pip install twilio
Se o erro pip: command not found
for exibido, você poderá usar oeasy_install
para instalar a biblioteca auxiliar do Twilio executando‐a no terminal:
easy_install twilio
Para uma instalação manual, você pode baixar o código‐fonte (ZIP) para twilio-python e instalar a biblioteca executando:
python setup.py install
na pasta que contém a biblioteca twilio-python.
Com isso, é hora de escrever um pouco de código.
Fazer uma chamada telefônica com Python
Agora que temos o Python e o twilio-python
instalado, podemos fazer uma chamada telefônica com uma única solicitação de API do número de telefone Twilio que acabamos de comprar. Crie um novo arquivo chamado make_call.py
e digite ou cole nesta amostra de código.
Esse código inicia uma chamada telefônica entre os dois números de telefone que passamos como argumentos. O número "from" (de) é o nosso número Twilio, e o número "to" (para) é o número para o qual desejamos ligar.
O argumento de URL aponta para alguns TwiML, que informam à Twilio o que fazer a seguir quando o destinatário atender o telefone. Este TwiML diz ao Twilio para ler uma mensagem usando conversão de texto em voz e depois reproduzir um MP3.
No entanto, antes que esse código funcione, precisamos editá‐lo um pouco para trabalhar com sua conta do Twilio.
Substitua os valores de credencial do espaço reservado
Troque os valores de espaço reservado para account_sid
e auth_token
com suas credenciais pessoais do Twilio.
Faça login em https://www.twilio.com/console. Nesta página, você encontrará seu Account SID (SID da conta) e o Auth Token (token de autenticação) exclusivos, que serão necessários sempre que enviar mensagens por meio do Twilio Client como essa. Você pode revelar seu Auth Token (token de autenticação) clicando no ícone de olho:
Abra make_call.py
e substitua os valores de account_sid
e auth_token
por seus valores exclusivos.
Observe: não há problema em codificar suas credenciais ao começar, mas você deve usar variáveis de ambiente para mantê‐las secretas antes de implantar na produção. Confira como definir variáveis de ambiente para obter mais informações.
Substituir os números de telefone to (para) e from_ (de)
Lembra daquele número de telefone habilitado para voz que você acabou de comprar? Use‐o para substituir o número from_
(de) existente, use a formatação E.164:
[+][código do país][número de telefone incluindo código de área]
Em seguida, substitua o número de telefone to
(para) pelo seu número de telefone celular. Pode ser qualquer número de telefone que possa receber chamadas, mas é uma recomendável com o seu telefone para ver a magia em ação! Como acima, você deve usar a formatação E.164 para esse valor.
Salve as alterações e execute o script no terminal:
python make_call.py
É isso! Seu telefone deve tocar com uma chamada do seu número Twilio e você ouvirá uma breve mensagem nossa. 😉
Se você estiver usando uma conta de avaliação da Twilio, as chamadas telefônicas de saída serão limitadas aos números de telefone verificados com o Twilio. Os números de telefone podem ser verificados por meio dos IDs de autor de chamada verificados do console Twilio. Para outras restrições e limitações da conta de avaliação, consulte nosso guia sobre como trabalhar com sua conta de avaliação gratuita da Twilio.
Em seguida, aprenderemos a responder a uma chamada feita para o número de telefone Twilio. Primeiro, precisaremos colocar um servidor Flask em funcionamento.
Instale o Flask e configure o ambiente de desenvolvimento
Para lidar com chamadas telefônicas recebidas, precisaremos de um aplicativo da Web leve para aceitar solicitações HTTP recebidas da Twilio. Usaremos o Flask para esse início rápido, mas você pode usar sua estrutura da Web de escolha para fazer e receber chamadas telefônicas de seus aplicativos.
Para obter instruções sobre como configurar o Flask no Windows, consulte este guia.
Instalar o PIP e o virtualenv
Para instalar o Flask e configurar nosso ambiente de desenvolvimento, precisaremos de duas ferramentas: o pip para instalar o Flask e o virtualenv para criar um sandbox exclusivo para esse projeto. Se você já tiver essas ferramentas instaladas, poderá ir para a próxima seção.
O pip vem pré‐empacotado com Python 3.4 ou superior, portanto, se você estiver em uma versão recente do Python, não precisará instalar nada novo. Se você estiver em uma versão anterior, não tenha medo: o pip está incluído no virtualenv. Então, vamos instalar o virtualenv!
Se você estiver usando o Python 2.4, execute o seguinte comando no terminal:
easy_install virtualenv
Se você estiver usando Python 2.5-2.7, execute o seguinte comando no terminal, especificando o número da versão:
easy_install-2.7 virtualenv
Substitua o 2.7 pelo 2.5 ou 2.6 se você tiver essa versão instalada.
Para instalar o virtualenv com Python 3.4 ou superior:
# Se você receber erros de "permission denied" (permissão negada) tente executar "sudo python" em vez de "python"
pip install virtualenv
Se você receber erros nesta etapa, confira estas dicas para depuração.
Criar e ativar o ambiente virtual
Depois de instalar o virtualenv, use seu terminal para navegar até o diretório que você está usando para este início rápido e crie um ambiente virtual:
cd Documents/my_quickstart_folder
virtualenv --no-site-packages .
Agora, ative o ambiente virtual:
source bin/activate
É possível verificar se o virtualenv está em execução olhando para o terminal: você deve ver o nome do seu diretório anexo. O aplicativo terá a seguinte aparência:
(my_quickstart_folder)USER:~ user$
Para saber mais sobre virtualenv ou criar um caminho de ambiente personalizado, consulte este guia completo.
Instalar dependências
Agora estamos prontos para instalar o Flask. Crie um arquivo chamado requirements.txt
e adicione as seguintes linhas a ele:
Flask>=0.12
twilio~=6.0.0
Em seguida, instale esses dois pacotes com pip no terminal:
pip install -r requirements.txt
Teste tudo do zero
Primeiro, verifique se o virtualenv está ativado:
cd Documents/my_quickstart_folder
source bin/activate # On Windows, use .\bin\activate.bat
Em seguida, crie e abra um arquivo chamado answer_phone.py
e adicione estas linhas:
Agora é hora de tentar executá‐lo. No terminal, digite:
python answer_phone.py
Você deve ver:
$ python answer_phone.py
* Running on http://127.0.0.1:5000/
Navegue até http://localhost:5000 no navegador. Você verá a mensagem "Hello World!" (Olá, mundo!). Você está pronto para criar seu primeiro aplicativo Programmable Voice da Twilio!
Se você encontrou algum problema ou quer instruções sobre como configurar seu ambiente com uma versão mais antiga do Python (<3.4), confira nosso guia completo para configurar um ambiente de desenvolvimento Python local.
Permitir que a Twilio se comunique com o aplicativo Flask
Estamos prestes a aprimorar nosso pequeno aplicativo Flask para aceitar chamadas telefônicas. Mas antes disso, precisamos garantir que a Twilio possa se comunicar com o ambiente de desenvolvimento local.
A maioria dos serviços Twilio usa webhooks para se comunicar com seu aplicativo. Quando a Twilio recebe uma chamada telefônica, por exemplo, ela acessa uma URL em seu aplicativo para obter instruções sobre como lidar com a chamada.
Quando você está trabalhando no aplicativo Flask em seu ambiente de desenvolvimento, seu aplicativo só pode ser acessado por outros programas em seu computador e a Twilio não poderá se comunicar com ele. Precisamos resolver esse problema tornando seu aplicativo acessível pela Internet.
Embora existam muitas maneiras de fazer isso, como implantar seu aplicativo no Heroku ou AWS, você provavelmente desejará uma maneira menos trabalhosa de testar seu aplicativo Twilio. Para uma maneira leve de disponibilizar seu aplicativo na internet, recomendamos uma ferramenta chamada ngrok. Uma vez iniciado, o ngrok fornece um URL exclusivo no domínio ngrok.io que encaminha as solicitações recebidas para o ambiente de desenvolvimento local.
Se você ainda não usa o ngrok, acesse a página de download e pegue o binário apropriado para o seu sistema operacional. Após o download, descompacte o pacote.
Se você estiver trabalhando em um Mac ou Linux, está tudo pronto. Se você estiver no Windows, siga nosso guia sobre como instalar e configurar o ngrok no Windows. Para obter mais informações sobre o ngrok, incluindo ótimas dicas e truques, confira esta postagem detalhada no blog.
Após o download, inicie o aplicativo Hello World que fizemos anteriormente:
python answer_phone.py
O aplicativo local deve ser executado localmente para que o ngrok cumpra seu papel.
Em seguida, abra uma nova guia ou janela de terminal e inicie o ngrok com este comando:
./ngrok http 5000
Se o seu servidor local for executado em uma porta diferente, substitua 5000 pelo número de porta correto.
A saída deve ser semelhante a esta:
Copie o URL público desta saída e cole‐o no navegador. Você deve ver a mensagem "Hello World!" (Olá, mundo!) no aplicativo Flask.
Atender chamadas recebidas com a Twilio
Quando seu número Twilio recebe uma chamada telefônica, ele envia uma solicitação HTTP ao seu servidor para obter instruções sobre o que fazer a seguir. Depois de receber a solicitação, você pode dizer à Twilio como atender a chamada.
Para este início rápido, nosso aplicativo Flask atenderá a chamada e enviará uma mensagem curta ao autor da chamada. Abra o answer_phone.py
novamente e atualize o código para que ele se pareça com este exemplo de código:
Salve o arquivo e reinicie seu aplicativo com
python answer_phone.py
Agora, abra um navegador da Web em http://localhost:5000/answer. Se você visualizar o código-fonte da página, verá o seguinte texto:
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Say voice="alice">Thank you for calling! Have a great day.</Say>
</Response>
Esse código‐fonte é um XML do TwiML gerado pelo seu código com a ajuda da biblioteca auxiliar do Twilio.
Verifique novamente se o ngrok ainda está em execução no host local com a mesma porta de antes. Agora, a Twilio poderá encontrar seu aplicativo. Há apenas uma última coisa que precisamos antes de estarmos prontos para chamar seu aplicativo: precisamos informar a Twilio para onde enviar sua solicitação.
Configurar o webhook do URL
Para que a Twilio saiba onde procurar, você precisa configurar seu número de telefone Twilio para ligar para o URL do seu webhook sempre que uma nova mensagem chegar.
- Faça login em Twilio.com e vá para a página Números do console.
- Clique em seu número de telefone habilitado para voz.
- Localize a seção "Voice & Fax" (Voz e fax). Verifique se a seleção "Accept Incoming" (Aceitar entrada) está definida como "Voice Calls" (Chamadas de voz). A seleção padrão "Configure With" (Configurar com) é o que você precisa: "Webhooks/TwiML...".
- Na seção "A Call Comes In" (Uma chamada é recebida), selecione "Webhook" e cole o URL que deseja usar, anexando sua rota "/answer":
Salve as alterações e pronto!
Teste seu aplicativo
Enquanto o host local e os servidores ngrok estiverem funcionando, estamos prontos para a parte divertida: testar nosso novo aplicativo Flask!
Faça uma chamada telefônica do celular para o número de telefone Twilio. Você deve ver uma solicitação HTTP no console do ngrok. Seu aplicativo Flask processará a solicitação recebida e responderá com seu TwiML. Em seguida, você ouvirá sua mensagem assim que a chamada for conectada.
Para onde ir em seguida?
Agora você conhece o básico sobre como fazer e responder a chamadas telefônicas com o Python.
Nosso aplicativo Flask usou apenas o verbo TwiML <Say> para ler uma mensagem para o autor da chamada usando conversão de voz, mas você pode fazer muito mais com diferentes verbos TwiML, como <Record>, <Gather> e <Conference>.
Confira estas páginas para saber mais:
- Reunir a entrada do usuário por meio do teclado (tons DTMF) no Python
- Saiba como gravar chamadas telefônicas recebidas e efetuadas do Twilio Voice usando Python
- Criar chamadas de conferência no Python
- Consulte a documentação de referência da API Programmable Voice da Twilio
- Saiba como modificar chamadas em andamento com Python
- Deseja fazer uma chamada a partir do seu navegador ou aplicativo móvel? Use o Twilio Client para integrar chamadas VoIP de alta qualidade.
- Recupere informações sobre chamadas em andamento e chamadas concluídas de sua conta Twilio usando Python.
- Confira nosso tutorial completo sobre como transferir chamadas entre agentes de suporte com Python e Flask
Estamos ansiosos para ver o que você vai criar!
Precisa de ajuda?
Às vezes, todos nós precisamos; a programação é difícil. Receba ajuda agora da nossa equipe de suporte, ou confie na sabedoria da multidão navegando pelo Stack Overflow Collective da Twilio ou buscando a tag Twilio no Stack Overflow.