Saltar para o conteúdo
REST API

SMS e chamadas diretamente a partir do seu fluxo n8n

O n8n chama a API REST da volai através do nó HTTP Request - sem escrever código, envia um SMS, inicia uma chamada com um agente de voz e recebe o resultado de volta por webhook.

1Guardar a chave como credencial

No n8n, crie uma nova credencial do tipo HTTP Header Auth: nome do header Authorization, valor Bearer vk_A_SUA_CHAVE (encontra a chave no portal, na secção Assistente de IA). Associe-a a cada nó HTTP Request que chame volai.cz/v1/* - a mesma chave serve para SMS, chamadas e webhook.

2Enviar um SMS a partir do fluxo

Adicione um nó HTTP Request: método POST, URL https://volai.cz/v1/messages, corpo JSON com os campos to e body. A resposta inclui priceHal (o preço em cêntimos de coroa checa, 1/100 CZK, por todos os segmentos) e segments - uma mensagem com caracteres fora de ASCII ocupa mais segmentos do que uma mensagem em ASCII simples. O exemplo abaixo deixa propositadamente o texto da mensagem sem acentos, para caber num único segmento - com acentos funciona exatamente da mesma forma, apenas à custa de um segmento adicional.

bash
curl -X POST https://volai.cz/v1/messages \
  -H "Authorization: Bearer vk_A_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"to": "+420777123456", "body": "A sua encomenda esta pronta para levantamento."}'

3Ligar a um cliente através do seu agente

Um segundo nó HTTP Request: POST https://volai.cz/v1/calls com to e o agentId de um agente de voz existente (crie-o no portal ou através de POST /v1/agents) - o agente tem de ter um número atribuído, caso contrário o pedido falha com agent_no_number. O pedido apenas inicia a chamada e devolve o respetivo id - o resultado real (concluída, sem resposta, falhada) chega através do webhook no passo seguinte.

bash
curl -X POST https://volai.cz/v1/calls \
  -H "Authorization: Bearer vk_A_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"to": "+420777123456", "agentId": "ag_kx91fa2b"}'

4Configurar um webhook para que o fluxo receba resposta

Adicione um trigger Webhook (o n8n gera-lhe o URL) e guarde exatamente esse endereço com PUT /v1/webhook, juntamente com a lista de eventos que lhe interessam. Atenção: um array events vazio não significa nenhum evento, mas todos - indique sempre os que pretende. A resposta devolve também um secret - guarde-o de imediato, o GET /v1/webhook nunca o devolve.

bash
curl -X PUT https://volai.cz/v1/webhook \
  -H "Authorization: Bearer vk_A_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://o-seu-n8n.app.n8n.cloud/webhook/volai", "events": ["call.completed", "message.sent"]}'

5Verificar a assinatura antes de processar o corpo

Cada pedido traz um header Volai-Signature no formato t=<unix>,v1=<hex>. Num nó Code, calcule o HMAC-SHA256 sobre {t}.{rawBody} com o seu secret e compare-o com v1 - só processe o corpo quando coincidirem. No nó Webhook, ative a opção Raw Body em Add Options - sem ela, o n8n analisa o corpo por si e os bytes exatos sobre os quais a assinatura foi calculada perdem-se. Com a opção ativa, o corpo chega antes como dados binários (propriedade data), e não em json.body - o código abaixo lê-o através de getBinaryDataBuffer, o que funciona quer o n8n guarde os dados binários em memória, em disco ou em S3. O módulo crypto integrado só funciona no nó Code em n8n self-hosted com NODE_FUNCTION_ALLOW_BUILTIN=crypto ativado - o n8n Cloud não suporta importação de módulos, pelo que a verificação aí não cabe num único nó. No Cloud, alargue a cadeia com um nó Extract From File (operação Extract From Text File) - converte o binário em texto num campo à sua escolha (por exemplo, rawBody) - e só depois um nó Crypto (ação Hmac, tipo SHA256, codificação HEX, valor uma expressão que junte o carimbo temporal do header ao campo rawBody, com o secret introduzido através de uma credencial Crypto e não de um campo de texto simples) calcula o resumo sem código; um nó IF conclui a comparação com v1.

javascript
// Entrada do nó Webhook com a opção Raw Body ativada: o header é o valor
// "Volai-Signature", p. ex. "t=1756111640,v1=8f2ac1d4..."; o corpo em bruto
// chega como dados binários (nome predefinido da propriedade "data"), não em json.body.
const header = $input.first().json.headers['volai-signature'];

// getBinaryDataBuffer funciona em todos os modos de armazenamento binário do n8n
// (predefinido em memória e também filesystem/S3) - a leitura direta de
// $input.first().binary.data.data só funcionaria no modo em memória.
const rawBody = (await this.helpers.getBinaryDataBuffer(0, 'data')).toString('utf8');

// secret é o valor do passo 4 (PUT /v1/webhook) - em produção leia-o
// de uma credencial do n8n ou de uma variável de ambiente, nunca o escreva diretamente no código
const secret = 'whsec_substitua_pelo_seu';

const crypto = require('crypto'); // apenas n8n self-hosted, ver o texto do passo

const [tPart, v1Part] = header.split(',');
const t = tPart.replace('t=', '');
const v1 = v1Part.replace('v1=', '');

const expected = crypto
  .createHmac('sha256', secret)
  .update(`${t}.${rawBody}`)
  .digest('hex');

if (expected !== v1) {
  throw new Error('Assinatura Volai-Signature inválida');
}

O que pode fazer com isto

SMS de confirmação após uma encomenda

A sua loja online ou sistema de reservas envia um webhook ao n8n quando há uma nova encomenda - o fluxo envia de imediato um SMS de confirmação com a hora estimada de levantamento.

Chamadas efetuadas a partir de um agendador ou folha de cálculo

Uma linha no Google Sheets, no Airtable ou no seu CRM aciona um nó HTTP Request que liga ao cliente através do seu agente de voz - um lembrete de marcação, um aviso de encomenda por concluir, um breve inquérito.

Registar o resultado da chamada no seu sistema

O webhook call.completed traz a transcrição, o resumo e os dados recolhidos durante a chamada (data) - o fluxo regista-os no CRM, numa folha de cálculo ou no Slack, sem ninguém ouvir a gravação manualmente.

Perguntas frequentes

Existe um nó n8n oficial para a volai?
Ainda não - hoje bastam os nós genéricos HTTP Request e Webhook, que o n8n inclui sempre. Um nó comunitário verificado teria de passar pela revisão do n8n Creator Portal - por agora não estamos a preparar nenhum.
Como sei que o webhook vem mesmo da volai e não de outra pessoa?
Pelo header Volai-Signature - uma assinatura HMAC-SHA256 com o secret que cada PUT /v1/webhook lhe devolve (guarde-o de imediato, o GET nunca o devolve). A fórmula completa, com exemplos em Python e TypeScript, encontra-se em /docs/webhooky.
E se o nó HTTP Request exceder o tempo limite e o n8n o repetir?
Adicione um header Idempotency-Key com um valor estável à sua escolha, como o ID da encomenda. Nas 24 horas seguintes, um pedido repetido com a mesma chave devolve exatamente a mesma resposta - sem segundo SMS nem segunda chamada.
A automatização através do n8n custa algo a mais do que chamar a API manualmente?
Não - não há qualquer suplemento pelo n8n. Aplicam-se os mesmos preços da página de preços: SMS 1.36 CZK (~EUR 0.06), chamada efetuada 0.92 CZK/min (~EUR 0.04), o agente de voz acresce 2.50 CZK/min (~EUR 0.10). Os preços completos estão em /cenik.

Experimente já

Registe-se e os primeiros 50 kr são por nossa conta.