Centro de Ayuda Conversa Labs
es
Idioma
pt_BR Portuguese (Brazil) en English es Spanish

API REST, tokens y webhooks

Abrir en
Ver como Markdown Abrir en ChatGPT Abrir en Claude
Conversa Labs

Conversa Labs

Última actualización el Aug 23, 2026

Visión general

La API REST permite leer y escribir datos de la plataforma (contactos, conversaciones, mensajes y más). La autenticación usa un token de acceso, y los webhooks entregan eventos a tu sistema en tiempo real.

Requisitos previos

  • Un token de acceso válido.
  • Un endpoint HTTPS para recibir webhooks.

Paso a paso

  1. Genera un token de acceso en la configuración.
  2. Incluye el token en el encabezado de autenticación de tus llamadas a la API.
  3. Realiza solicitudes a los recursos de la API (ej.: listar contactos, crear conversación).
  4. Configura un webhook indicando la URL y los eventos deseados.
  5. Valida la firma/secreto del webhook antes de procesar el payload.

Configuración y opciones

  • Alcance del token: limita el acceso a lo necesario.
  • Eventos del webhook: suscríbete solo a los eventos que usas.
  • Secreto de firma: se muestra una sola vez, justo después de crear el webhook. Cópialo y guárdalo de forma segura; las respuestas de listado y edición solo confirman que hay un secreto configurado y nunca lo revelan. Si se pierde, crea un webhook de reemplazo y retira el destino anterior.
  • Entrega duradera: cada entrega de webhook de cuenta se registra antes de entrar en la cola. Los errores de red y respuestas 5xx usan reintentos con backoff y siguen visibles en el historial.
  • Historial y reenvío: en Configuración → Integraciones → Webhooks, abre el historial del destino para buscar, filtrar y ordenar intentos. Un administrador puede reenviar una o varias filas; el resultado masivo mantiene separados los IDs procesados y fallidos.
  • Payload de Commerce: por defecto solo se envían identificadores canónicos. Activa Incluir datos comerciales en un destino únicamente cuando el receptor necesite comprador, producto/variante e ítems normalizados. El opt-in nunca agrega credenciales ni el payload bruto de la pasarela.
  • Idempotencia del receptor: usa el encabezado X-Chatwoot-Delivery como clave de idempotencia; un reenvío manual reutiliza el mismo identificador.

Catálogo de eventos (grupos de módulos)

Todos los eventos siguientes son suscripciones a nivel de cuenta (configuradas por cuenta, en la pantalla de Webhooks). Para que un módulo entregue sus eventos, la función del módulo debe estar habilitada en la cuenta — la suscripción se acepta aunque la función esté apagada, pero no se entrega nada hasta activarla.

  • Conversaciones, mensajes, contactos, bandeja y escritura — el ciclo de vida de la atención.
  • CRM (negocios) — creación, etapa, ganado/perdido, prioridad, valor, salud, lista de tareas, SLA y fechas de cierre.
  • Catálogo y Commerce — productos, variantes/stock y el ciclo de pago de Commerce.
  • Pedidos e ingresos — registro de pedido, estado, pagado, reembolsado, ingresos y afiliados.
  • Tareas, Calendario y reservas, Pagos y Follow-ups — el ciclo de vida de cada módulo.
  • Contratos y firma electrónica, Gestión de Ventas y Engagement/Lead Score.
  • Account Brain — riesgo, insights, ejecución de departamento y mejoras propuestas.
  • Distribución (Grupos de Lanzamiento) — inscripción, invitación, ingreso de miembros y finalización de unidades.
  • Growth Social y Ads — comentarios, leads de anuncio, estado de campaña y ventana del Clic-a-WhatsApp.
  • WhatsApp Hub — difusiones, eventos de participantes y bienvenidas/despedidas de grupo (Cloud y WazMeow).
  • Llamadas y respuestas de Flow de WhatsApp — ciclo de vida de llamadas y respuestas de WhatsApp Flows.
  • Gestión de Equipo — cambio de estado, pausas y turnos de los agentes.
  • FlowBuilder — ciclo de vida de las sesiones de flujo.
  • Enrutamiento Inteligente — asignación de agente.

Los campos reales de cada payload están en Eventos por módulo.

Casos de uso

  • Replicar conversaciones en un data warehouse.
  • Notificar a un sistema externo cuando una conversación se crea o se resuelve.

Consejos, límites y buenas prácticas

  • Verifica siempre la firma del webhook antes de actuar.
  • Garantiza idempotencia con X-Chatwoot-Delivery, también en reintentos y reenvíos manuales.
  • Respeta los límites de tasa y usa backoff en errores 429/5xx.

Solución de problemas

  • 401/403: token inválido o sin permiso.
  • Webhook duplicado: confirma que el receptor deduplica X-Chatwoot-Delivery.
  • Entrega fallida: abre el historial del destino y revisa su estado HTTP/error y el próximo intento. Después de corregir el receptor, selecciona la fila y confirma el reenvío.

Ver también