Início rápido do Programmable Voice para Python

Com apenas algumas linhas de código, seu aplicativo Python pode fazer e receber chamadas telefônicas com o Programmable Voice da Twilio.

Este início rá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 início rápido, você aprende a:

Inscrever‐se na Twilio e obter o primeiro número de telefone Twilio habilitado para voz
Configurar o ambiente de desenvolvimento para fazer e receber chamadas telefônicas
Fazer uma chamada telefônica de saída que reproduza um MP3
Receber e responder a uma chamada telefônica de entrada que leia uma mensagem para o autor da chamada usando conversão de texto em voz

Prefere começar assistindo a um vídeo? Confira nosso vídeo no YouTube sobre como fazer e receber chamadas telefônicas com Python.

Mostre‑me como se faz!

Inscreva‐se na Twilio e obtenha um número de telefone

Se já tiver uma conta e um número de telefone da Twilio habilitado para voz, tudo está em ordem! Faça login e fique à vontade para ir para a próxima etapa.

Para fazer uma chamada telefônica do Python, é necessário uma conta Twilio. Inscreva‐se aqui para obter sua conta de avaliação gratuita ou faça login em uma conta que você já possui.

A próxima coisa que você precisa é um número de telefone da Twilio com capacidade de voz. Se você não possui atualmente um número de telefone da Twilio com funcionalidade de chamada de voz, precisará adquirir um. Após navegar até a página Comprar um número, marque a caixa "Voice" (Voz) e clique em "Search" (Pesquisar).

Você verá uma lista de números de telefone disponíveis e seus recursos. Encontre um número que se adapte às suas necessidades e clique em "Buy" (Comprar) para adicioná‐lo à sua conta.

Purchase a voice-enabled phone number from Twilio

Com uma conta Twilio e um número de telefone programável, você tem as ferramentas básicas necessárias para fazer uma chamada telefônica.

Você pode usar a API HTTP do Twilio para fazer chamadas telefônicas, mas vamos simplificar ainda mais com a biblioteca auxiliar Python oficial da Twilio. Vamos instalar em seguida.

Leve‑me até a configuração.

Instale o Python e a biblioteca auxiliar da Twilio

Se você já passou por outro de nossos inícios rápidos do Python e já tem o Python e a biblioteca auxiliar da Twilio Python instalada, você pode pular esta etapa e ir direto para fazer sua primeira ligação telefônica.

Para fazer sua primeira chamada telefônica com a Twilio, você precisa instalar o Python e a biblioteca auxiliar do Twilio Python.

Instale o Python

Se você estiver usando uma máquina Mac ou Linux, provavelmente já tem o Python instalado. Você pode verificar isso abrindo um terminal e executando o seguinte comando:

python --version

Você deve ver algo como:

$ python --version
Python 3.9  # Python 3.6+ is okay, too

Os usuários do Windows podem seguir este excelente tutorial para instalar o Python no Windows.

O SDK Python Twilio só suporta Python 3.6 ou superior.

Instalar a biblioteca auxiliar Python Twilio

A maneira mais fácil de instalar a biblioteca é usando o PIP. Basta executá‐lo no terminal:

pip install twilio

Se o erro pip: command not found for exibido, você poderá usar oeasy_install para instalar a biblioteca auxiliar do Twilio executando‐a no terminal:

easy_install twilio

Para uma instalação manual, você pode baixar o código‐fonte (ZIP) para twilio-python e instalar a biblioteca executando:

python setup.py install

na pasta que contém a biblioteca twilio-python.

Com isso, é hora de escrever um pouco de código.

Tudo pronto! Vamos fazer uma chamada telefônica.

Fazer uma chamada telefônica com Python

Agora que temos o Python e o twilio-python instalado, podemos fazer uma chamada telefônica com uma única solicitação de API do número de telefone Twilio que acabamos de comprar. Crie um novo arquivo chamado make_call.py e digite ou cole nesta amostra de código.

Loading Code Sample...

Show sample response

Example JSON response

Show code

Fazer uma chamada telefônica com a Twilio

Esse código inicia uma chamada telefônica entre os dois números de telefone que passamos como argumentos. O número "from" (de) é o nosso número Twilio, e o número "to" (para) é o número para o qual desejamos ligar.

O argumento de URL aponta para alguns TwiML, que informam à Twilio o que fazer a seguir quando o destinatário atender o telefone. Este TwiML diz ao Twilio para ler uma mensagem usando conversão de texto em voz e depois reproduzir um MP3.

No entanto, antes que esse código funcione, precisamos editá‐lo um pouco para trabalhar com sua conta do Twilio.

Substitua os valores de credencial do espaço reservado

Troque os valores de espaço reservado para account_sid e auth_token com suas credenciais pessoais do Twilio.

Faça login em https://www.twilio.com/console. Nesta página, você encontrará seu Account SID (SID da conta) e o Auth Token (token de autenticação) exclusivos, que serão necessários sempre que enviar mensagens por meio do Twilio Client como essa. Você pode revelar seu Auth Token (token de autenticação) clicando no ícone de olho:

Abra make_call.py e substitua os valores de account_sid e auth_token por seus valores exclusivos.

Observe: não há problema em codificar suas credenciais ao começar, mas você deve usar variáveis de ambiente para mantê‐las secretas antes de implantar na produção. Confira como definir variáveis de ambiente para obter mais informações.

Substituir os números de telefone to (para) e from_ (de)

Lembra daquele número de telefone habilitado para voz que você acabou de comprar? Use‐o para substituir o número from_ (de) existente, use a formatação E.164:

[+][código do país][número de telefone incluindo código de área]

Em seguida, substitua o número de telefone to (para) pelo seu número de telefone celular. Pode ser qualquer número de telefone que possa receber chamadas, mas é uma recomendável com o seu telefone para ver a magia em ação! Como acima, você deve usar a formatação E.164 para esse valor.

Salve as alterações e execute o script no terminal:

python make_call.py

É isso! Seu telefone deve tocar com uma chamada do seu número Twilio e você ouvirá uma breve mensagem nossa. 😉

Se você estiver usando uma conta de avaliação da Twilio, as chamadas telefônicas de saída serão limitadas aos números de telefone verificados com o Twilio. Os números de telefone podem ser verificados por meio dos IDs de autor de chamada verificados do console Twilio. Para outras restrições e limitações da conta de avaliação, consulte nosso guia sobre como trabalhar com sua conta de avaliação gratuita da Twilio.

Em seguida, aprenderemos a responder a uma chamada feita para o número de telefone Twilio. Primeiro, precisaremos colocar um servidor Flask em funcionamento.

Vamos lá!

Instale o Flask e configure o ambiente de desenvolvimento

Para lidar com chamadas telefônicas recebidas, precisaremos de um aplicativo da Web leve para aceitar solicitações HTTP recebidas da Twilio. Usaremos o Flask para esse início rápido, mas você pode usar sua estrutura da Web de escolha para fazer e receber chamadas telefônicas de seus aplicativos.

Para obter instruçõ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 você já tiver essas ferramentas instaladas, poderá ir para a próxima seção.

O pip vem pré‐empacotado com Python 3.4 ou superior, portanto, se você estiver em uma versão recente do Python, não precisará instalar nada novo. Se você estiver em uma versão anterior, não tenha medo: o pip está incluído no virtualenv. Então, vamos instalar o virtualenv!

Se você estiver usando o Python 2.4, execute o seguinte comando no terminal:

easy_install virtualenv

Se você estiver usando Python 2.5-2.7, execute o seguinte comando no terminal, especificando o número da versão:

easy_install-2.7 virtualenv

Substitua o 2.7 pelo 2.5 ou 2.6 se você tiver essa versão instalada.

Para instalar o virtualenv com Python 3.4 ou superior:

# Se você receber erros de "permission denied" (permissão negada) tente executar "sudo python" em vez de "python"
pip install virtualenv

Se você receber erros nesta etapa, confira estas dicas para depuração.

Criar e ativar o ambiente virtual

Depois de instalar o virtualenv, use seu terminal para navegar até o diretório que você está usando para este início rápido e crie um ambiente virtual:

cd Documents/my_quickstart_folder
virtualenv --no-site-packages .

Agora, ative o ambiente virtual:

source bin/activate

É possível verificar se o virtualenv está em execução olhando para o terminal: você deve ver o nome do seu diretório anexo. O aplicativo terá a seguinte aparência:

(my_quickstart_folder)USER:~ user$

Para saber mais sobre virtualenv ou criar um caminho de ambiente personalizado, consulte este guia completo.

Instalar dependê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 está 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:

Loading Code Sample...

Show sample response

Example JSON response

Show code

Teste sua configuração com este simples aplicativo Flask "Hello, World"

"Hello, World" Flask application

Teste sua configuração com este simples aplicativo Flask "Hello, World"

Agora é hora de tentar executá‐lo. No terminal, digite:

python answer_phone.py

Você deve ver:

$ python answer_phone.py
* Running on http://127.0.0.1:5000/

Navegue até http://localhost:5000 no navegador. Você verá a mensagem "Hello World!" (Olá, mundo!). Você está pronto para criar seu primeiro aplicativo Programmable Voice da Twilio!

Se você encontrou algum problema ou quer instruções sobre como configurar seu ambiente com uma versão mais antiga do Python (<3.4), confira nosso guia completo para configurar um ambiente de desenvolvimento Python local.

Tudo pronto. Como a Twilio se comunica com o novo aplicativo?

Permitir que a Twilio se comunique com o aplicativo Flask

Estamos prestes a aprimorar nosso pequeno aplicativo Flask para aceitar chamadas telefônicas. Mas antes disso, precisamos garantir que a Twilio possa se comunicar com o ambiente de desenvolvimento local.

A maioria dos serviços Twilio usa webhooks para se comunicar com seu aplicativo. Quando a Twilio recebe uma chamada telefônica, por exemplo, ela acessa uma URL em seu aplicativo para obter instruções sobre como lidar com a chamada.

Quando você está trabalhando no aplicativo Flask em seu ambiente de desenvolvimento, seu aplicativo só pode ser acessado por outros programas em seu computador e a Twilio não poderá se comunicar com ele. Precisamos resolver esse problema tornando seu aplicativo acessível pela Internet.

Embora existam muitas maneiras de fazer isso, como implantar seu aplicativo no Heroku ou AWS, você provavelmente desejará 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 domínio ngrok.io que encaminha as solicitações recebidas para o ambiente de desenvolvimento local.

How ngrok helps Twilio reach your local server

Se você ainda não usa o ngrok, acesse a página de download e pegue o binário apropriado para o seu sistema operacional. Após o download, descompacte o pacote.

Se você estiver trabalhando em um Mac ou Linux, está tudo pronto. Se você estiver no Windows, siga nosso guia sobre como instalar e configurar o ngrok no Windows. Para obter mais informações sobre o ngrok, incluindo ótimas dicas e truques, confira esta postagem detalhada no blog.

Apó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 número de porta correto.

A saída deve ser semelhante a esta:

Copie o URL público desta saída e cole‐o no navegador. Você deve ver a mensagem "Hello World!" (Olá, mundo!) no aplicativo Flask.

Meu servidor está acessível publicamente. Me ensine a receber chamadas telefônicas!

Atender chamadas recebidas com a Twilio

Quando seu número Twilio recebe uma chamada telefônica, ele envia uma solicitação HTTP ao seu servidor para obter instruções sobre o que fazer a seguir. Depois de receber a solicitação, você pode dizer à Twilio como atender a chamada.

Para este início rápido, nosso aplicativo Flask atenderá a chamada e enviará uma mensagem curta ao autor da chamada. Abra o answer_phone.py novamente e atualize o código para que ele se pareça com este exemplo de código:

Loading Code Sample...

Show sample response

Example JSON response

Show code

Respond to an incoming request from Twilio with instructions on how to handle the call

Respond to an incoming call with a brief message

Respond to an incoming request from Twilio with instructions on how to handle the call

Salve o arquivo e reinicie seu aplicativo com

python answer_phone.py

Agora, abra um navegador da Web em http://localhost:5000/answer. Se você visualizar o código-fonte da página, verá 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 código‐fonte é um XML do TwiML gerado pelo seu código com a ajuda da biblioteca auxiliar do Twilio.

Verifique novamente se o ngrok ainda está em execução no host local com a mesma porta de antes. Agora, a Twilio poderá encontrar seu aplicativo. Há apenas uma última coisa que precisamos antes de estarmos prontos para chamar seu aplicativo: precisamos informar a Twilio para onde enviar sua solicitação.

Configurar o webhook do URL

Para que a Twilio saiba onde procurar, você precisa configurar seu número de telefone Twilio para ligar para o URL do seu webhook sempre que uma nova mensagem chegar.

Faça login em Twilio.com e vá para a página Números do console.
Clique em seu número de telefone habilitado para voz.
Localize a seção "Voice & Fax" (Voz e fax). Verifique se a seleção "Accept Incoming" (Aceitar entrada) está definida como "Voice Calls" (Chamadas de voz). A seleção padrão "Configure With" (Configurar com) é o que você precisa: "Webhooks/TwiML...".
Na seção "A Call Comes In" (Uma chamada é recebida), selecione "Webhook" e cole o URL que deseja usar, anexando sua rota "/answer":

Configure your Voice webhook with your ngrok URL

Salve as alteraçõ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!

Faça uma chamada telefônica do celular para o número de telefone Twilio. Você deve ver uma solicitação HTTP no console do ngrok. Seu aplicativo Flask processará a solicitação recebida e responderá com seu TwiML. Em seguida, você ouvirá sua mensagem assim que a chamada for conectada.

Funcionou! Tudo pronto. O que vem a seguir?

Para onde ir em seguida?

Agora você conhece o básico sobre como fazer e responder a chamadas telefônicas com o Python.

Nosso aplicativo Flask usou apenas o verbo TwiML <Say> para ler uma mensagem para o autor da chamada usando conversão de voz, mas você pode fazer muito mais com diferentes verbos TwiML, como <Record>, <Gather> e <Conference>.

Confira estas páginas para saber mais:

Reunir a entrada do usuário por meio do teclado (tons DTMF) no Python
Saiba como gravar chamadas telefônicas recebidas e efetuadas do Twilio Voice usando Python
Criar chamadas de conferência no Python
Consulte a documentação de referê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 móvel? Use o Twilio Client para integrar chamadas VoIP de alta qualidade.
Recupere informações sobre chamadas em andamento e chamadas concluí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 você 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.

Fazer uma chamada telefônica com a Twilio

"Hello, World" Flask application

Respond to an incoming call with a brief message

Precisa de ajuda?

Obrigado pelo seu feedback!

Obrigado pelo seu feedback!