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

Uma ação permite ao seu bot consultar algo no seu próprio sistema a meio de uma conversa — onde está uma encomenda, quando será entregue, se uma reserva está confirmada. O cliente pergunta, o bot recolhe o que precisa, chama a sua API e responde a partir do que recebe, na língua do cliente.

Funciona em todo o lado onde o seu bot funciona: o widget do site, o link e código QR do seu bot, e as aplicações Android, iOS, React Native, Flutter e Ionic. Nada é instalado ou atualizado — a chamada é feita a partir dos nossos servidores, por isso as credenciais da sua API nunca chegam a um browser ou a um telemóvel.

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

O seu bot é uma conversa pública. Se um número de encomenda bastar para ver uma encomenda, qualquer pessoa pode escrever números até um funcionar.

O bot ajuda de três formas, mas nenhuma delas substitui essa verificação: envia apenas valores que o cliente realmente escreveu, limita quantas consultas uma conversa ou um endereço podem fazer, e pode escolher que campos da resposta ele está autorizado a ver.

Configurar uma

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

• Nome — para si, como «Estado da encomenda».
• Quando deve o bot usá-la? — uma frase, como diria a um novo colega: «O cliente pergunta onde está a sua encomenda ou quando vai chegar.»
• O 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 uma etiqueta nas suas palavras («Número da encomenda»), o nome que a sua API usa (order_id) e um tipo: qualquer texto, um número, um endereço de email ou um número de telefone.
• Cabeçalhos — a sua chave de API ou token. Guardado encriptado e nunca mais mostrado.
• Partilhar apenas estes campos com o bot — opcional. Liste as partes da resposta que o bot pode usar, como status, eta, items[].name. Tudo o resto é descartado antes de a IA o ver.

Prima Testar, escreva valores de exemplo e verá o pedido que foi enviado e exatamente o que o bot receberia. Depois experimente a sério no ecrã Teste: «Onde está a minha encomenda 48213? O meu email é asha@example.com».

O que a sua API recebe

Com GET, os valores que colocou no endereço são preenchidos e os restantes são adicionados à 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"}

Cada pedido leva também os seus próprios cabeçalhos e estes:

O que devolver

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

• 200 com os dados — o bot responde a partir deles. Mantenha-os pequenos e use nomes de campos claros: {"status":"shipped","eta":"2 October"} funciona melhor do que códigos internos.
• 404 quando nada corresponde — o bot informa o cliente e pede-lhe que verifique o que escreveu.
• Qualquer outra coisa, ou nenhuma resposta a tempo — o bot pede desculpa, oferece os seus contactos e a conversa é sinalizada para si. O motivo é mostrado no ecrã Ações.

Os redirecionamentos não são seguidos, e uma resposta com mais de 256 KB não é lida.

Verificar a assinatura

Os pedidos são assinados à maneira dos Standard Webhooks, por isso pode usar uma biblioteca existente. O seu segredo de assinatura está no ecrã Ações.

À mão: junte o id, o timestamp e o corpo exato com pontos finais, assine isso com HMAC-SHA256 usando o segredo (a parte depois de whsec_, descodificada 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));
}

Num pedido GET o corpo está vazio, por isso o texto assinado termina com um ponto final. Use POST se quiser que os próprios valores fiquem cobertos pela assinatura.

Como o bot a usa

• Pergunta tudo o que falta, uma pergunta curta de cada vez, e lembra-se do que o cliente disse antes na conversa.
• Nunca adivinha um valor. Se o cliente não o escreveu, o bot pergunta.
• Uma consulta por mensagem. As suas respostas guardadas continuam a ter prioridade, por isso uma pergunta que respondeu à mão nunca chama a sua API.
• As 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-o por baixo: que ação correu e como terminou. Os valores que o cliente escreveu ficam na transcrição e em mais lado nenhum.

Limites

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