# 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

```http
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…
```

```json
{
  "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.

```js
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:

```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:

| Escolha                 | O que o seu sistema recebe                                                                                                                                                                                                                |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Confirmar com o contato | Com "o sistema descreve a mudança antes": primeiro `confirmed: false` (responda o que mudaria, sem mudar), depois `confirmed: true`, com os mesmos dados, só depois que o contato concordou. Sem ela, só a chamada com `confirmed: true`. |
| Uma pessoa aprova       | Uma chamada com `confirmed: true`, quando alguém da equipe aprova.                                                                                                                                                                        |
| Sem confirmação         | A chamada assim que a IA decide.                                                                                                                                                                                                          |

## 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.