Configurar una integración
Para quién es: quien administra la cuenta
Para qué sirve
Este es el camino completo, desde pedir la funcionalidad hasta que tu sistema lance la primera campaña. Todo lo que hace quien administra está en Configuración > Integraciones. Si todavía no leíste los conceptos, empezá por Integraciones: API y webhooks.
Paso a paso
➡️
Paso:Pedí que se habilite. Las integraciones vienen con el plan o con una habilitación del equipo de TalkAI; la prueba gratis no las incluye. Mientras no estén habilitadas, la pestaña muestra Integraciones no incluidas en tu plan: podés ver lo configurado, pero no crear keys ni cambiar el webhook.
➡️
Paso:Creá una API key. En API keys tocá Nueva key, ponele un nombre que identifique al sistema que la va a usar y marcá solo los permisos que necesita. Copiala en ese momento: no se vuelve a mostrar.
➡️
Paso:Registrá el webhook. En Webhook cargá la URL pública (con
https) donde tu sistema recibe los avisos, opcionalmente un token Bearer, elegí los eventos, activá Webhook activo y tocá Guardar.➡️
Paso:Guardá el secreto de firma. Al guardar el webhook por primera vez se genera el secreto y aparece una sola vez: guardalo en tu sistema para verificar la firma.
➡️
Paso:Probá el webhook. Tocá Probar webhook: TalkAI envía un evento
integration.ping firmado. Comprobá que tu sistema lo recibe, verifica la firma y responde con un código 2xx.➡️
Paso:Armá el flujo. En Flujos tocá Nuevo flujo y completá la plantilla de WhatsApp aprobada, de dónde sale cada variable, el agente de IA con la herramienta Informar ítems de integraciones activada, el tipo de ítem, el esquema del resultado y la política de envío. Al guardarlo aparece en la lista con su slug, que es lo que usa tu sistema.
➡️
Paso:Tu sistema lanza campañas y recibe avisos. Con la key y el slug, tu sistema crea campañas en
POST /v1/campaigns y recibe cada cambio en el webhook. Los detalles para quien desarrolla están en Referencia de la API y Webhooks.Qué tenés que definir para el flujo
Para armar el flujo te vamos a pedir:
- Qué hay que resolver con el contacto (confirmar un turno, una entrega, una reserva) y qué respuestas esperás.
- El texto de la plantilla y qué datos de cada ítem completan sus variables. La plantilla tiene que estar aprobada por Meta y conviene que sea de categoría Utilidad: Meta puede rechazar o frenar las que parezcan marketing.
- Qué datos manda tu sistema en
datapor cada ítem (por ejemplo producto, fecha y dirección). - Qué resultado querés recibir en
result(por ejemplorespuestay unanueva_fecha). Con eso armamos el esquema que valida lo que carga el agente. - La política de envío: reintentos si el contacto no responde, cada cuánto, a las cuántas horas vence y en qué horario se puede enviar.
ℹ️
Nota:El flujo también guarda una plantilla de re-pedido y una política de recordatorios, pero los recordatorios automáticos y el aviso al contacto cuando reabrís un ítem todavía no están disponibles.
Buenas prácticas
- Una key por sistema, con los permisos justos. Si un sistema solo consulta, dale solo Consultar ítems.
- Guardá el secreto y la key fuera del código, en la configuración segura de tu sistema.
- Rotá el secreto si creés que se filtró: durante 24 h el anterior sigue firmando, así cambiás tu sistema sin perder avisos.
- No dependas solo del webhook. Si tu sistema estuvo caído o el webhook estaba desactivado, consultá
GET /v1/items?updated_since=para ponerte al día.
⚠️
Atención:Revocar una key corta de inmediato a cualquier sistema que la use. Antes de revocarla, cargá la nueva en tu sistema.