SMS e chamadas diretamente de um cenário do Make
O Make chama a API REST da volai através do módulo HTTP genérico - num cenário pode enviar SMS, iniciar uma chamada com um agente de voz e receber o resultado por webhook.
1Prepare a chave como connection
No módulo HTTP > Make a request, adicione o cabeçalho Authorization com o valor Bearer vk_TVUJ_KLIC (a chave encontra-se no portal, na secção Assistente de IA). Guarde-a como ligação reutilizável, para não ter de a copiar para cada módulo em separado.
2Envie um SMS a partir do cenário
Adicione um módulo HTTP > Make a request: método POST, URL https://volai.cz/v1/messages, corpo do tipo Raw (JSON) com os campos to e body - os valores podem ser mapeados a partir do bundle do módulo anterior (uma linha de folha de cálculo, um webhook) em vez de os escrever à mão. Ative Parse response, para que priceHal (o preço em centésimos de CZK para todos os segmentos) e segments da resposta sejam logo decompostos no bundle para mapeamento posterior - sem isso, obtém apenas texto bruto e teria de adicionar à parte um módulo Parse JSON. Num texto com acentos, o número de segmentos é maior do que numa mensagem só com ASCII.
{
"to": "+420777123456",
"body": "A sua encomenda esta pronta para levantamento."
}3Inicie uma chamada com o agente de voz
Adicione um segundo módulo HTTP > Make a request: POST https://volai.cz/v1/calls, corpo Raw (JSON) com to e o agentId de um agente de voz existente - o agente tem de ter um número próprio atribuído, caso contrário o pedido termina com o erro agent_no_number. O campo to normalmente não se escreve à mão, mas mapeia-se a partir do bundle do módulo anterior (por exemplo, o número de telefone de uma linha do Google Sheets) - clique no campo e escolha a variável no menu. Também aqui convém Parse response: decompõe logo no bundle o id da chamada iniciada, para o poder mapear adiante sem um módulo Parse JSON à parte. O módulo apenas inicia a chamada - o resultado real (concluída, sem resposta, falhada) só o saberá pelo webhook do passo seguinte.
{
"to": "+420777123456",
"agentId": "ag_kx91fa2b"
}4Receba os eventos de volta através de um Custom webhook
Adicione um módulo Webhooks > Custom webhook - o Make gera um URL e confirma logo o pedido recebido (cumprindo a condição de resposta 200 rápida de /docs/webhooky). Guarde esse mesmo endereço com PUT /v1/webhook, juntamente com a lista de eventos que lhe interessam. Atenção: um campo events vazio não significa nenhum evento, mas absolutamente todos - é melhor enumerá-los sempre. A resposta devolve também secret - guarde-o de imediato, GET /v1/webhook já não o devolve.
curl -X PUT https://volai.cz/v1/webhook \
-H "Authorization: Bearer vk_TVUJ_KLIC" \
-H "Content-Type: application/json" \
-d '{"url": "https://hook.eu2.make.com/xxxxxxxx", "events": ["call.completed", "message.sent"]}'5Ramifique o cenário consoante o tipo de evento
Distinga o campo event no corpo do webhook (call.completed, call.failed, call.no_answer, call.missed, message.sent, message.received) com um módulo Router ou com um filtro à entrada do ramo. Complete a verificação da assinatura Volai-Signature (HMAC-SHA256 sobre {t}.{rawBody} com o seu secret) segundo a fórmula exata em /docs/webhooky - num cenário sensível (pagamentos, lançamentos na contabilidade), não a omita.
O que pode fazer com isto
O Iterator envia SMS a toda a lista de contactos
O módulo Iterator decompõe um array de contactos (por exemplo, do Google Sheets ou de um array JSON) em itens individuais e o módulo HTTP chama depois POST /v1/messages para cada um - tipicamente um aviso em massa ou um lembrete para todo um grupo de clientes de uma só vez.
Um filtro na ligação decide a quem se deve ligar
O Make permite colocar uma condição diretamente na ligação entre módulos - o filtro deixa passar apenas as linhas que cumprem a condição (por exemplo, a data é amanhã e o cliente ainda não confirmou) e só estas acionam o módulo HTTP para POST /v1/calls.
Um error handler apanha a chamada falhada
No módulo HTTP que chama /v1/calls, adicione uma rota de error handler com a diretiva Ignore - assim, a falha de uma chamada (por exemplo, um número inválido) fica registada numa tabela ou é enviada para o Slack para verificação manual, sem que todo o cenário falhe.
Perguntas frequentes
- Existe uma app própria da volai no marketplace do Make?
- Ainda não - bastam os módulos genéricos HTTP e Webhooks, que o Make tem sempre disponíveis. Uma app própria no Make depende do Make Technology Partner Program, que por agora não estamos a tratar.
- Quantas operações consome um cenário com dois módulos HTTP?
- Cada execução de um módulo conta como uma operação - um cenário que chama
/v1/messagese depois/v1/callsconsome da ordem de duas a três operações por execução, consoante o número de módulos entre eles. O limite de operações é determinado pelo seu plano do Make, não pela volai. - Como configuro um error handler no módulo HTTP para que a falha de uma chamada não pare todo o cenário?
- Clique com o botão direito no módulo HTTP e adicione uma rota de error handler. Lá dentro, escolha a diretiva Ignore - o cenário ignora o erro e continua, como se o módulo não tivesse devolvido nenhuma saída. Se os módulos seguintes precisarem de um valor de substituição em vez da saída em falta, use Resume com uma saída de recurso própria. Recorra a Break apenas se quiser parar logo a execução e repeti-la depois, manual ou automaticamente.
- Porque devolve o Custom webhook `Accepted` logo, antes de o cenário terminar?
- É assim que o módulo Custom webhook funciona por predefinição - confirma a receção com o estado 200 e o texto
Acceptedde imediato e o cenário termina depois em segundo plano. Quem chama (por exemplo, a volai) só precisa de receber 200 em poucos segundos - e isso fica cumprido. - Porque continua o módulo HTTP logo após POST /v1/calls, mesmo que a chamada ainda não tenha terminado?
POST /v1/callsapenas inicia a chamada e devolve o seuid- de forma síncrona, num instante. Se a chamada foi mesmo atendida, concluída ou falhou, só o saberá mais tarde, através do webhookcall.completed/call.failed/call.no_answer/call.missed. O cenário não tem, por isso, de esperar nem de fazer polling - basta ligar a esse resultado o módulo Custom webhook descrito acima.
Experimente já
Registe-se e os primeiros 50 kr são por nossa conta.