){kind=small}
Crie uma canção de Natal com o Nexmo e o Python
Tempo de leitura: 4 minutos
O Natal está chegando e mais um ano já está quase acabando!
Pensei em encerrar o ano com um trecho de código em Python divertido e fácil, que permite que você reproduza uma canção de Natal para te fazer sorrir — ou te deixar constrangido...
A ideia principal é a seguinte:
Você liga para um número da Nexmo
Você ouve um menu de opções
A escolha é sua
Você ouve uma canção de Natal de dar vergonha alheia!
Que legal!
Se você ainda não experimentou o Nexmo, recomendo que consulte nossa documentação como primeiro passo.
Também vou partir do princípio de que você sabe como configurar seus webhooks. Além disso, você pode hospedar seu servidor de webhooks em uma plataforma de sua escolha ou testar localmente usando o Ngrok. Se você ainda não usou o Ngrok, recomendo que dê uma olhada no nosso tutorial do Ngrok e também a nossa documentação sobre o assunto.
Então, agora você está pronto para configurar seus webhooks. Vou partir do princípio de que você está testando localmente com o Ngrok e que os configurou mais ou menos assim:
Webhook | URL
---- | ----
resposta | https://abcdef1.ngrok.io:3000/webhooks/answer
evento | https://abcdef1.ngrok.io:3000/webhooks/event
NOTA: Isso pressupõe que seu servidor de webhook esteja rodando na porta 3000, mas pode ser qualquer porta adequada.
Há outro webhook de interesse neste tutorial, mas você não o configura da mesma forma que configura as URLs do webhook de resposta ou do webhook de evento. Trata-se do webhook DTMF, que você verá na próxima seção.
Ao ligar para o seu número Nexmo, você ouvirá um menu de opções. Em seguida, poderá selecionar sua música de Natal pressionando uma tecla no teclado do seu telefone. Essa informação é enviada ao seu aplicativo por meio de um POST webhook DTMF, que tem o formato https://abcdef1.ngrok.io:3000/webhooks/dtmf.
Então, como a Nexmo sabe como retornar a chamada por meio dessa URL? Você precisa configurar o webhook DTMF no código do seu webhook de resposta.
Ao analisar o webhook “Answer”, você vê o seguinte:
@app.route("/webhooks/answer")
def answer_call():
params = request.args
input_webhook_url = request.url_root + "webhooks/dtmf"
ncco = [
{
"action": "talk",
"bargeIn": "true",
"text": menu
},
{
"action": "input",
"maxDigits": 1,
"timeOut": 5,
"eventUrl": [input_webhook_url]
}
]
return jsonify(ncco)Ao analisar esse código, você pode ver que, quando sua chamada recebida é atendida, o NCCO que controla a chamada envia o menu de opções por meio dos recursos de conversão de texto em fala da Nexmo e também configura o webhook DTMF. É assim que a Nexmo sabe para onde redirecionar a chamada com base nas entradas do teclado do telefone.
Há também alguns parâmetros especificados. O timeOut parâmetro, neste caso, está definido para um tempo um pouco maior do que o padrão de três segundos. Nesse caso, você tem um intervalo de cinco segundos para responder pressionando uma tecla antes que o sistema entre em tempo limite ao aguardar uma entrada. maxDigits Isso garantirá que apenas um dígito seja aceito como entrada.
O outro parâmetro que vale a pena mencionar é bargeIn que, neste caso, está definido como true neste caso. Isso permite que você interrompa o menu de opções para aqueles momentos em que você simplesmente não consegue esperar para ouvir sua canção de Natal favorita!
Há também documentação mais detalhada sobre DTMF que você pode ler quando quiser. Aqui, abordei apenas o básico.
Você acabou de ver como funciona o webhook do Answer. Agora você vai ver como funciona o webhook do DTMF.
Primeiro, aqui está o código:
@app.route("/webhooks/dtmf", methods=['POST'])
def dtmf_webhook():
data = request.get_json()
selection = data['dtmf']
if selection == "":
selection = "1"
index = int(selection)-1
if index < 0 or index > len(tunes)-1:
index = 0
carol_url = base_url + tunes[index][1]
print(tunes[index][1])
msg = "Playing Christmas carol " + str(index+1)
ncco = [
{
"action": "talk",
"text": msg
},
{
"action": "stream",
"streamUrl": [carol_url]
}
]
return jsonify(ncco)
Você pode ver que estamos interessados apenas em uma POST chamada de retorno nessa URL. Basicamente, esse código serve para garantir que lidemos com o caso em que o usuário não insira nenhuma opção ou selecione uma opção que esteja fora do intervalo apresentado no menu de opções. A ação propriamente dita ocorre novamente no NCCO.
No NCCO, há uma pequena mensagem que anuncia qual canção de Natal será reproduzida. Em seguida, a stream ação é usada para reproduzir um arquivo MP3 durante a chamada. Esse recurso é bastante útil para coisas como música de espera e assim por diante, mas podemos usá-lo neste caso para entrar no clima festivo. Basta especificar a URL e a música, por meio da incrível magia da Nexmo, é reproduzida durante sua chamada.
Já abordei as partes mais importantes do código. Aqui está o código completo, para sua conveniência:
#!/usr/bin/env python3
from flask import Flask, request, jsonify
from pprint import pprint
app = Flask(__name__)
base_url = 'https://raw.githubusercontent.com/tbedford/git-testing-repo/master/tunes/xmas/'
# Tunes courtesy http://www.freexmasmp3.com/
tunes = [
["Little Town of Bethlehem", "bethlem-jazz.mp3"],
["Ding Dong Merrily", "ding-dong-merrily.mp3"],
["First Noel", "first-noel-r-and-b.mp3"],
["Jingle Bells", "jingle-bells-country.mp3"],
["Silent Night", "silent-night-piano.mp3"],
["Twelve Days of Christmas", "twelve-days-funk.mp3"]
]
# Build options menu
menu = "Welcome to dial a Christmas carol. You can choose from the following cheesy carols."
i = 1
for t in tunes:
menu = menu + " Option " + str(i) + " is " + t[0] +"."
i = i + 1
menu = menu + " Please make your selection now."
@app.route("/webhooks/answer")
def answer_call():
params = request.args
input_webhook_url = request.url_root + "webhooks/dtmf"
ncco = [
{
"action": "talk",
"bargeIn": "true",
"text": menu
},
{
"action": "input",
"maxDigits": 1,
"timeOut": 5,
"eventUrl": [input_webhook_url]
}
]
return jsonify(ncco)
@app.route("/webhooks/dtmf", methods=['POST'])
def dtmf_webhook():
data = request.get_json()
selection = data['dtmf']
if selection == "":
selection = "1"
index = int(selection)-1
if index < 0 or index > len(tunes)-1:
index = 0
carol_url = base_url + tunes[index][1]
print(tunes[index][1])
msg = "Playing Christmas carol " + str(index+1)
ncco = [
{
"action": "talk",
"text": msg
},
{
"action": "stream",
"streamUrl": [carol_url]
}
]
return jsonify(ncco)
@app.route("/webhooks/event", methods=['POST'])
def events():
data = request.get_json()
pprint(data)
return ("OK")
if __name__ == '__main__':
app.run(port=3000)
Assim que seu aplicativo estiver funcionando, basta ligar para a Nexmo usando seu número da Nexmo, fazer sua escolha entre as opções oferecidas pelo teclado do celular e curtir um pouco de diversão festiva.
Então, espero que tenham gostado desse código de Natal.
Gostaria de aproveitar esta oportunidade para desejar a todos um Feliz Natal e um Feliz Ano Novo!
O código-fonte está disponível no GitHub:
Aqui estão alguns recursos que serão úteis caso você queira se aprofundar no assunto:
Referência NCCO - descreve a
inputação em detalhes.Tutorial do Ngrok - um guia útil para testar seu aplicativo localmente.
Webhooks - tudo o que você sempre quis saber sobre Webhooks, mas tinha medo de perguntar.