Herramientas del asistente

En medio de una conversación, el asistente de IA de DoneTalk puede consultar o cambiar datos en su sistema: el estado de un pedido, la cuenta de un cliente, un e-mail que cambiar. Llama a una dirección suya, recibe un texto corto y le responde al contacto con ese dato.

La empresa arma la herramienta en Configuración › Herramientas: la conexión (dirección y secreto), la ruta, los campos que la IA debe averiguar y si la herramienta solo consulta o cambia datos. Esta página es para quien hace la dirección que recibe la llamada.

Lo que llega

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

{
  "tool": "estado_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 es el número de la conversación, puesto por DoneTalk y cubierto por la firma. Use solo él para encontrar la cuenta. La IA nunca elige de quién es la cuenta; lo que ella envía va en input.
input trae los campos que declara la herramienta, ya con su tipo (texto, número, sí/no, lista, fecha).
contact.fields trae solo los campos del contacto que la empresa marcó en la herramienta.
confirmed aparece en las herramientas que cambian datos y piden confirmación: false pide solo la descripción del cambio; true lo hace.
test: true viene de las pruebas ("Probar ahora" y el "Probar" del asistente): no cambie nada.

La firma

La misma de los avisos: t es la hora en segundos y v1 es el HMAC-SHA256, en hexadecimal, de t + "." + cuerpo, con el secreto de la conexión. Rechace llamadas de más 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 ?? ""));
}

La conexión también acepta un token (Authorization: Bearer), una clave en un encabezado suyo, o la firma en el formato de Copiloto (X-Copiloto-Timestamp y X-Copiloto-Signature), para sistemas hechos para su consulta externa.

Qué responder

200 con JSON:

{
  "ok": true,
  "text": "Pedido 77: salió para entrega hoy a las 14 h.",
  "data": { "status": "shipped" }
}

text es lo único que lee la IA: lenguaje natural, sin markdown, hasta 1.500 caracteres. Diga el dato y el siguiente paso del contacto.
ok: false con text también llega a la IA como un hecho ("No encontré pedido con este teléfono").
data es opcional y solo queda en el historial de llamadas.
Cualquier otra respuesta (otro estado, sin text, más de 64 KB, más de 8 segundos por defecto) se vuelve "no disponible ahora": la IA sigue la conversación sin el dato.

Herramientas que cambian datos

La empresa elige, por herramienta, cómo confirmar:

Elección	Lo que recibe su sistema
Confirmar con el contacto	Con "el sistema describe el cambio antes": primero `confirmed: false` (responda qué cambiaría, sin cambiarlo), después `confirmed: true`, con los mismos datos, solo después de que el contacto aceptó. Sin ella, solo la llamada con `confirmed: true`.
Una persona aprueba	Una llamada con `confirmed: true`, cuando alguien del equipo aprueba.
Sin confirmación	La llamada en cuanto la IA lo decide.

Límites

Hasta 5 llamadas de la misma herramienta por conversación por hora.
Solo direcciones https públicas; las redirecciones no se siguen.
Una herramienta con el método GET envía la llamada en el parámetro call de la dirección, en lugar del cuerpo; la firma cubre el valor de ese parámetro.

Cualquier API

Si su sistema ya tiene una API, la herramienta puede llamarla sin este formato: la empresa arma la ruta, los encabezados y el cuerpo con {{contact.phone}}, {{contact.name}}, {{input.campo}} y {{conversation.id}}, y elige lo que lee la IA: la respuesta entera, un campo (data.status) o una frase armada con ella.

Esta página en Markdown