Conversão de texto em fala com chamadas de prompt, usando Python no AWS Lambda

A Nexmo Voice API oferece grande flexibilidade nos cenários de chamada que você pode ativar; no entanto, para fazer isso, muitas vezes é necessário realizar várias interações com a API. Em alguns cenários, talvez você queira fazer uma única chamada à API a partir da sua lógica de negócios que acione uma série de interações com a Voice API. Esse é o cenário ideal para criar um aplicativo sem servidor que você possa chamar e deixar que ele lide com as interações da Voice API.

Neste exemplo, mostraremos como fazer uma chamada de conversão de texto em fala (TTS), na qual será reproduzida uma mensagem para o destinatário e, em seguida, ele será solicitado a digitar alguns dígitos no teclado, talvez para confirmar um número PIN. Depois que a interação for concluída, você receberá uma resposta em uma URL que você especificar. Isso é muito semelhante à API TTS Prompt, que já foi descontinuada pela Nexmo, mas oferece maior flexibilidade.

Atualmente, o aplicativo liga para um número, reproduz uma mensagem inicial e, em seguida, aguarda que o usuário digite o PIN que você especificar; caso o PIN esteja incorreto, é reproduzida uma mensagem de erro e o usuário pode tentar novamente; são permitidas até 3 tentativas, embora isso possa ser alterado no seu código.

Se não digitarem o PIN correto na terceira tentativa, a chamada será encerrada sem nenhuma mensagem.

Se digitarem o PIN corretamente, será reproduzida outra mensagem e, em seguida, a chamada será encerrada. Assim que a chamada terminar, você receberá uma resposta no seu webhook com o ID da transação da chamada e o resultado das tentativas de digitação do PIN.

Veja o código-fonte no GitHub

Pré-requisitos

Neste tutorial, você vai:

• É necessário ter um Account na AWS (você pode executar isso no plano gratuito do Lambda)

• Tenha a ferramenta AWS CLI e Chalice instalados e configurados em seu computador

• Crie uma aplicação de voz do Nexmo e salve a chave privada em um arquivo local chamado private.key, juntamente com uma anotação do ID do aplicativo

Implantação

Para implantar a função na sua própria conta da AWS:

Primeiro, clone o repositório Git para o seu computador:

git clone https://github.com/nexmo-community/voice-ttsprompt-lambda.git

Acesse a pasta:

cd voice-ttsprompt-lambda

Implantar a função na AWS:

chalice deploy

Você verá a seguinte mensagem quando sua função for implantada; confirme com “Y” que deseja adicionar a política de execução

Initial creation of lambda function.
Updating IAM policy.

The following actions will be added to the execution policy:

dynamodb:PutItem
logs:PutLogEvents
dynamodb:CreateTable
logs:CreateLogStream
dynamodb:GetItem
logs:CreateLogGroup

Would you like to continue? [Y/n]: y
Creating deployment package.
Initiating first time deployment...
Deploying to: api
https://910e9mcan2.execute-api.us-east-1.amazonaws.com/api/

A última linha é a URL base da sua função recém-implantada; anote-a, pois você poderá recuperá-la a qualquer momento com o comando chalice url

Configuração

Há muito pouco a ser configurado, já que o Chalice cuida da maior parte da configuração da AWS na primeira implantação. No entanto, você precisará criar a tabela do DynamoDB usada para armazenar o estado da chamada. Para isso, basta enviar uma solicitação HTTP GET para a /setup URL da sua função.

Invocando

Agora você pode chamar sua nova função com uma única solicitação HTTP POST para sua URL base, com /call no final. Você precisa passar os seguintes parâmetros

Autenticação

O aplicativo Lambda não armazena nenhuma de suas credenciais do Nexmo; em vez disso, elas são fornecidas no momento em que você chama a função e são utilizadas apenas para essa solicitação.

Existem duas maneiras de fazer isso: gerando um JWT da Nexmo com nossas bibliotecas e incluindo-o nos cabeçalhos da solicitação, ou simplesmente enviando a chave privada e o applicationID como parte de uma solicitação cURL. Recomenda-se que você utilize o método de autenticação por JWT.

cURL (autenticação por chave privada)

Edite a URL para que ela corresponda à que você recebeu ao implantar sua função

curl -X "POST" "https://910e9mcan2.execute-api.us-east-1.amazonaws.com/api/call" \
--data-urlencode "private_key=`cat private.key`" \
-d "app_id=684027bc-a2e7-48b1-b4bd-adc02324e09c" \
-d "to=447970513607" \
-d "from=447520616161" \
-d "text='Enter the PIN'" \
-d "pin_code=1234" \
-d "callback=https://2bwz8nkbmfgc.runscope.net/callback" \
-d "callback_method=post" \
-d "bye_text='Thank You'" \
-d "failed_text='Try again'"

Python (JWT)

Edite a URL para que ela corresponda à que você recebeu ao implantar sua função.

Você precisará da biblioteca Nexmo para Python: instale-a com o comando pip install nexmo

# you need the Nexmo client lib to generate your JWT
import nexmo
import requests

client = nexmo.Client(application_id=APP_ID, private_key=PRIVATE_KEY, key='dummy', secret='dummy')
headers = client._Client__headers()
data = {
'to': 'TO_NUMBER',
'from': 'CALLERID_NUMBER',
'text': 'Enter the pin',
'pin_code' : '1234',
'callback' : 'https://example.com/callback',
'callback_method' : 'post',
'bye_text' : 'thankyou',
'failed_text' : 'try again'
}
response = requests.post("https://910e9mcan2.execute-api.us-east-1.amazonaws.com/api/call", json=data, headers=headers)

Em qualquer um dos métodos, a resposta será um objeto JSON contendo um ID de transação (“tid”); essa é a referência da chamada e será usada na chamada de retorno com o resultado.

Exemplo de resposta: { "tid": "6a2827c9-4c68-46fc-b179-115f055dc0eb" }

Callbacks

Quando a chamada for concluída, a função Lambda enviará uma solicitação de retorno de chamada para um webhook que você especificou ao invocá-la — essa solicitação conterá detalhes da chamada e o resultado:

Os seguintes valores de status podem ser retornados:

• ok: a chamada foi concluída e o usuário digitou o PIN correto

• failed: a chamada foi concluída, mas o usuário não conseguiu digitar o PIN correto

• error: a ligação não foi concluída

Próximos passos

Você pode modificar o código para ajustar parâmetros como o número de tentativas que o usuário tem para digitar a senha ou, talvez, queira alterar o voiceName textos usados nas mensagens de aviso.

Os detalhes de cada uma das suas chamadas serão armazenados no AWS DynamoDB; talvez seja recomendável limpar essas entradas de tempos em tempos, dependendo das suas necessidades.