Integraciones: conectá tu sistema con TalkAI
Para quién es: quien administra la cuenta y quien desarrolla el sistema que se conecta
Para qué sirve
Con las integraciones, tu sistema (de pedidos, turnos, reservas o entregas) le pide a TalkAI que contacte a tus clientes por WhatsApp y recibe el resultado, sin que nadie de tu equipo tenga que escribir uno por uno.
Por ejemplo: tu sistema pide "confirmar el pedido P-1001 con este cliente". TalkAI le envía la plantilla de WhatsApp, el agente de IA conversa con el cliente, registra que confirmó y tu sistema recibe un aviso firmado con el resultado.
Algunos usos:
- Confirmar un turno el día anterior y avisarle a tu agenda si el cliente viene o no.
- Confirmar una entrega: avisar que el pedido sale y preguntar si va a haber alguien para recibirlo.
- Confirmar una reserva y registrar los cambios que pida el cliente.
Cómo funciona, en pocas palabras
- Tu sistema lanza una campaña por la API, con los contactos y los ítems de cada uno.
- TalkAI le envía a cada contacto la plantilla de WhatsApp del flujo que elegiste.
- Cuando el contacto responde, la conversación pasa al agente de IA del flujo, que sabe qué ítems tiene que resolver.
- El agente registra el estado y el resultado de cada ítem.
- Cada cambio le llega a tu sistema por webhook. También lo podés consultar por la API en cualquier momento.
Conceptos
API key y permisos
Es la credencial con la que tu sistema llama a la API de TalkAI. Se crea en Configuración > Integraciones, empieza con tk_live_ y se muestra una sola vez: TalkAI guarda solo una huella, así que si la perdés, creás otra y revocás la vieja.
Cada key tiene sus propios permisos:
| Permiso | En el panel | Qué deja hacer |
|---|---|---|
campaigns:write | Lanzar campañas | Crear campañas |
items:read | Consultar ítems | Consultar campañas e ítems |
items:write | Cambiar estado de ítems | Resolver, cancelar o reabrir un ítem |
Revocar una key la deja sin efecto de inmediato. El panel muestra cuándo se usó por última vez.
Webhook y firma
El webhook es la URL de tu sistema a la que TalkAI le avisa cada cambio. Es una sola por organización y se registra en el panel: nunca viaja en los pedidos a la API.
Cada aviso va firmado con un secreto que empieza con whsec_ (HMAC-SHA256), para que tu sistema compruebe que lo mandó TalkAI y que nadie lo modificó. Si querés, además mandamos un token tuyo en el header Authorization: Bearer. Cuando rotás el secreto, el anterior sigue firmando durante 24 h para que puedas cambiarlo sin cortar nada. El detalle está en Webhooks.
Flujo
El flujo es la receta de cada tipo de contacto: qué plantilla de WhatsApp se envía, con qué datos se completan sus variables, qué agente de IA atiende, qué tipo de ítem maneja (por ejemplo pedido o turno), qué resultado se espera y cuántas veces se reintenta el envío. Tu sistema solo conoce su identificador, el slug (por ejemplo confirmar_pedidos).
Los flujos los crea y edita quien administra la organización, en la sección Flujos de la pestaña Integraciones. Si tu plan todavía no incluye integraciones, los ves en modo de solo lectura.
Ítem y sus estados
Un ítem es cada cosa que hay que resolver con un contacto: un pedido, un turno, una reserva. Se identifica con su tipo (lo define el flujo) y tu propio id, el external_id (por ejemplo P-1001). Lleva dos bloques de datos:
data: lo que manda tu sistema (producto, fecha, dirección...). Lo usa la plantilla y lo ve el agente.result: lo que registra el agente (por ejemplo{ "respuesta": "confirma" }). Si el flujo tiene un esquema de resultado, lo que no lo cumple se rechaza antes de llegar a tu sistema.
| Estado | Qué significa |
|---|---|
open | Pendiente: se envió (o se va a enviar) y espera respuesta |
in_progress | El contacto respondió y el agente lo está atendiendo, o quedó algo para aclarar |
resolved | Resuelto |
cancelled | Cancelado: el contacto no puede o tu sistema lo canceló |
expired | Vencido sin respuesta (todavía no se usa) |
Quién cambia cada estado:
- TalkAI pasa el ítem a
in_progresscuando el contacto responde. - El agente de IA lo pasa a
in_progress,resolvedocancelled, y carga el resultado. - Tu sistema, por la API, lo pasa a
resolvedocancelled, o lo reabre (open) indicando un motivo.
Campaña por API
Una campaña es un pedido a la API con el slug del flujo, tu propio id de campaña (external_id) y la lista de contactos, cada uno con su teléfono y sus ítems. Si mandás dos veces la misma campaña, la segunda no envía nada de nuevo: devuelve la que ya existe. Si un mismo teléfono aparece varias veces, sus ítems se juntan en un solo contacto. Los envíos respetan la ventana horaria, los reintentos y el vencimiento del flujo.
Si el contacto ya está conversando
- Si tiene una conversación abierta con el agente de IA del mismo flujo, el pedido nuevo se suma a esa conversación: el agente ve todos los ítems abiertos y, ante la duda, le pregunta al contacto a cuál se refiere.
- Si la conversación la atiende una persona u otro agente, o está en la cola, el envío espera y sale cuando esa conversación se cierra. Mientras tanto, en la campaña el contacto figura como diferido (
deferred).
Quién puede usarlas
- Las integraciones dependen del plan, o de una habilitación del equipo de TalkAI para tu organización. La prueba gratis no las incluye.
- Quien administra la organización maneja las API keys y el webhook.
- Quien administra la organización también crea y edita los flujos.
Si la organización deja de tener integraciones, la API responde INTEGRATION_NOT_ENABLED, las campañas creadas por API no envían mensajes nuevos y los avisos quedan en pausa hasta que se reactiven. No se borra nada: keys, flujos, ítems y avisos pendientes se conservan, y las conversaciones en curso siguen normalmente.
expired y el registro de entregas en el panel.Para seguir: Configurar una integración, Referencia de la API y Webhooks.