Ações: respostas do seu próprio sistema

Uma ação permite que seu bot consulte algo no seu próprio sistema no meio de uma conversa — onde está um pedido, quando será entregue, se uma reserva está confirmada. O cliente pergunta, o bot coleta o que precisa, chama sua API e responde a partir do que recebe, no idioma do cliente.

Funciona em todos os lugares onde seu bot funciona: o widget do site, o link e código QR do seu bot, e os aplicativos Android, iOS, React Native, Flutter e Ionic. Nada é instalado ou atualizado — a chamada é feita a partir dos nossos servidores, então as credenciais da sua API nunca chegam a um navegador ou celular.

Antes de começar: qualquer pessoa pode conversar com seu bot

Seu bot é uma conversa pública. Se um número de pedido sozinho basta para ver um pedido, qualquer pessoa pode digitar números até um funcionar.

O bot ajuda de três formas, mas nenhuma delas substitui essa verificação: ele só envia valores que o cliente realmente digitou, limita quantas consultas uma conversa ou um endereço pode fazer, e você pode escolher quais campos da resposta ele tem permissão para ver.

Configurar uma

Abra Ações no painel e escolha Nova ação. Proprietários e administradores podem ver esta tela.

• Nome — para você, como "Status do pedido".
• Quando o bot deve usá-la? — uma frase, como você diria a um novo colega: "O cliente pergunta onde está o pedido dele ou quando vai chegar."
• Endereço da sua API — GET ou POST, e um endereço https://. Escreva {{order_id}} onde entra um valor.
• O que o bot pede ao cliente — até seis valores. Cada um tem um rótulo com suas palavras ("Número do pedido"), o nome que sua API usa (order_id) e um tipo: qualquer texto, um número, um endereço de e-mail ou um número de telefone.
• Cabeçalhos — sua chave de API ou token. Armazenado criptografado e nunca mais exibido.
• Compartilhar apenas estes campos com o bot — opcional. Liste as partes da resposta que o bot pode usar, como status, eta, items[].name. Todo o resto é descartado antes que a IA veja.

Pressione Testar, digite valores de exemplo e você verá a requisição enviada e exatamente o que o bot receberia. Depois, experimente de verdade na tela Teste: "Onde está meu pedido 48213? Meu e-mail é asha@example.com".

O que sua API recebe

Com GET, os valores que você colocou no endereço são preenchidos e o restante é adicionado à query string:

GET https://api.yourshop.com/orders/48213?email=asha%40example.com

Com POST, os valores são o corpo JSON:

POST https://api.yourshop.com/lookup
Content-Type: application/json

{"order_id":"48213","email":"asha@example.com"}

Toda requisição também leva seus próprios cabeçalhos e estes:

O que devolver

Responda em até 8 segundos com JSON, ou uma linha curta de texto simples.

• 200 com os dados — o bot responde a partir deles. Mantenha a resposta pequena e use nomes de campos claros: {"status":"shipped","eta":"2 October"} funciona melhor do que códigos internos.
• 404 quando nada corresponde — o bot avisa o cliente e pede que ele confira o que digitou.
• Qualquer outra coisa, ou nenhuma resposta a tempo — o bot pede desculpas, oferece seus dados de contato e a conversa é sinalizada para você. O motivo aparece na tela Ações.

Redirecionamentos não são seguidos, e uma resposta acima de 256 KB não é lida.

Verificar a assinatura

As requisições são assinadas no padrão Standard Webhooks, então você pode usar uma biblioteca existente. Seu segredo de assinatura está na tela Ações.

Manualmente: junte o id, o timestamp e o corpo exato com pontos, assine isso com HMAC-SHA256 usando o segredo (a parte depois de whsec_, decodificada de base64) e compare.

const crypto = require('crypto');

function isFromKeyda(req, rawBody, secret) {
  const id = req.headers['webhook-id'];
  const ts = req.headers['webhook-timestamp'];
  const given = String(req.headers['webhook-signature'] || '').replace(/^v1,/, '');
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // older than 5 minutes
  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const want = crypto.createHmac('sha256', key).update(`${id}.${ts}.${rawBody}`).digest('base64');
  return given.length === want.length
    && crypto.timingSafeEqual(Buffer.from(given), Buffer.from(want));
}

Em uma requisição GET o corpo fica vazio, então o texto assinado termina com um ponto. Use POST se quiser que os próprios valores sejam cobertos pela assinatura.

Como o bot a usa

• Ele pergunta tudo o que estiver faltando, uma pergunta curta por vez, e lembra o que o cliente disse antes na conversa.
• Ele nunca adivinha um valor. Se o cliente não digitou, o bot pergunta.
• Uma consulta por mensagem. Suas respostas salvas continuam tendo prioridade, então uma pergunta que você respondeu manualmente nunca chama sua API.
• Respostas de uma consulta nunca são reutilizadas para outro cliente.
• Uma consulta conta como uma resposta, como qualquer outra resposta que a IA escreve.

Em Conversas, uma resposta que veio de uma consulta indica isso logo abaixo: qual ação rodou e como terminou. Os valores que o cliente digitou ficam na transcrição e em nenhum outro lugar.

Limites

Ações leem informações. Não aponte uma para um endereço que altera algo — cancelar um pedido ou emitir um reembolso precisa de uma etapa de confirmação que o bot ainda não tem.