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:

Cómo funciona, en pocas palabras

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:

PermisoEn el panelQué deja hacer
campaigns:writeLanzar campañasCrear campañas
items:readConsultar ítemsConsultar campañas e ítems
items:writeCambiar estado de ítemsResolver, 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:

EstadoQué significa
openPendiente: se envió (o se va a enviar) y espera respuesta
in_progressEl contacto respondió y el agente lo está atendiendo, o quedó algo para aclarar
resolvedResuelto
cancelledCancelado: el contacto no puede o tu sistema lo canceló
expiredVencido sin respuesta (todavía no se usa)

Quién cambia cada estado:

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

Quién puede usarlas

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.

ℹ️
Nota:Todavía no están disponibles: el aviso automático al contacto cuando reabrís un ítem, los recordatorios automáticos, el estado expired y el registro de entregas en el panel.

Para seguir: Configurar una integración, Referencia de la API y Webhooks.