Ferramentas do assistente

No meio de uma conversa, o assistente de IA do DoneTalk pode consultar ou alterar dados no seu sistema: o status de um pedido, o cadastro de um cliente, um e-mail para trocar. Ele chama um endereço seu, recebe um texto curto e responde ao contato com esse fato.

A empresa monta a ferramenta em Configurações › Ferramentas: a conexão (endereço e segredo), o caminho, os campos que a IA precisa descobrir e se a ferramenta só consulta ou altera dados. Esta página é para quem faz o endereço que recebe a chamada.

O que chega

POST /seu-caminho HTTP/1.1
Content-Type: application/json
User-Agent: DoneTalk-Tools/1.0 (+https://donetalk.com/desenvolvedores)
DoneTalk-Signature: t=1792756800,v1=5f0c…

{
  "tool": "consultar_pedido",
  "contact": { "phone": "+5511999990000", "name": "Camila", "fields": {} },
  "conversation": { "id": "01a3e4f5-…", "test": false },
  "assistant": { "id": "01a0c0de-…", "name": "Amanda" },
  "input": { "numero": "77" },
  "test": false,
  "sentAt": "2026-10-24T12:00:00.000Z"
}

• contact.phone é o número da conversa, posto pelo DoneTalk e coberto pela assinatura. Use só ele para achar a conta. A IA nunca escolhe de quem é a conta; o que ela manda fica em input.
• input traz os campos que a ferramenta declara, já no tipo certo (texto, número, sim/não, lista, data).
• contact.fields traz só os campos do contato que a empresa marcou na ferramenta.
• confirmed aparece nas ferramentas que alteram dados e pedem confirmação: false pede só a descrição do que mudaria; true faz a mudança.
• test: true vem dos testes (o "Testar agora" e o "Testar" do assistente): não altere nada.

A assinatura

A mesma dos avisos: t é o horário em segundos e v1 é o HMAC-SHA256, em hexadecimal, de t + "." + corpo, com o segredo da conexão. Recuse chamadas com mais de 5 minutos.

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(header, rawBody, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const age = Math.abs(Date.now() / 1000 - Number(parts.t));
  const expected = createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  return age < 300 && timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 ?? ""));
}

A conexão também aceita um token (Authorization: Bearer), uma chave num cabeçalho seu, ou a assinatura no formato do Copiloto (X-Copiloto-Timestamp e X-Copiloto-Signature), para sistemas feitos para a consulta externa dele.

O que responder

200 com JSON:

{
  "ok": true,
  "text": "Pedido 77: saiu para entrega hoje às 14h.",
  "data": { "status": "shipped" }
}

• text é a única coisa que a IA lê: linguagem natural, sem markdown, até 1.500 caracteres. Diga o fato e o próximo passo do contato.
• ok: false com text também chega à IA como fato ("Não encontrei pedido com este telefone").
• data é opcional e fica só no histórico de chamadas.
• Qualquer outra resposta (outro status, sem text, mais de 64 KB, mais de 8 segundos por padrão) vira "indisponível agora": a IA segue a conversa sem o dado.

Ferramentas que alteram dados

A empresa escolhe, por ferramenta, como confirmar:

Limites

• Até 5 chamadas da mesma ferramenta por conversa por hora.
• Só endereços https públicos; redirecionamentos não são seguidos.
• Uma ferramenta com método GET manda a chamada no parâmetro call do endereço, em vez do corpo; a assinatura cobre o valor desse parâmetro.

Qualquer API

Se o seu sistema já tem uma API, a ferramenta pode chamá-la sem este formato: a empresa monta o caminho, os cabeçalhos e o corpo com {{contact.phone}}, {{contact.name}}, {{input.campo}} e {{conversation.id}}, e escolhe o que a IA lê: a resposta inteira, um campo (data.status) ou uma frase montada com ela.

Esta página em Markdown