API y Desarrolladores
Por Conversa Labs
Por Conversa Labs
API REST, tokens, webhooks, SDK de Custom Scripts y eventos por módulo.
Visión general de API y Desarrolladores
Visión general ConversaLabs ofrece capacidades para que los desarrolladores integren sistemas externos: una API REST para leer y escribir datos, webhooks para recibir eventos en tiempo real, un SDK de Custom Scripts para extender las interfaces y eventos por módulo para reaccionar a cambios. Requisitos previos - Una cuenta con permiso para generar tokens de API. - Conocimientos básicos de HTTP/JSON. Paso a paso 1. Genera un token de acceso en la configuración de tu perfil/cuenta. 2. Llama a la API REST autenticando con el token. 3. Configura webhooks para recibir eventos en tu endpoint. 4. Usa Custom Scripts para personalizar el dashboard, el portal y el widget. Configuración y opciones - Tokens: por usuario/cuenta, con alcance de acceso. - Webhooks: suscripción a eventos por bandeja/cuenta. - Custom Scripts: JS/CSS inyectados en las superficies compatibles. Casos de uso - Sincronizar contactos y conversaciones con un CRM externo. - Disparar automatizaciones en tu sistema cuando algo cambia en la plataforma. Consejos, límites y buenas prácticas - Trata los tokens como secretos; nunca los expongas en el front-end. - Respeta los límites de tasa y maneja errores/reintentos. Solución de problemas - 401/403: verifica el token y los permisos. - El webhook no llega: revisa la URL, el estado del endpoint y la firma. Ver también - API REST, tokens y webhooks - SDK de Custom Scripts
API REST, tokens y webhooks
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. - Reentrega: maneja reintentos e idempotencia en tu endpoint. 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 (dedup por identificador del evento). - 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: implementa dedup por ID del evento. Ver también - Visión general de API y Desarrolladores - Eventos por módulo
SDK de Custom Scripts
Visión general Los Custom Scripts permiten inyectar JavaScript/CSS en superficies específicas de la plataforma — el dashboard, el portal del Centro de Ayuda y el widget de chat. Son útiles para pequeñas personalizaciones de comportamiento y estilo sin cambiar el código base. Requisitos previos - Permiso de administrador para gestionar Custom Scripts. - Conocimientos de JavaScript/CSS. Paso a paso 1. Abre el módulo de Custom Scripts. 2. Crea un script y elige la superficie (dashboard, portal o widget). 3. Define el tipo (JS o CSS) y cuándo debe ejecutarse. 4. Usa el contexto ctx que provee el runtime para interactuar con la superficie de forma segura. 5. Implementa el teardown para limpiar lo que el script creó, cuando aplique. Configuración y opciones - Superficie: dashboard / portal / widget. - Tipo: JS o CSS. - Ejecución: reglas de cuándo se ejecuta el script. Casos de uso - Añadir un botón o aviso en una pantalla específica. - Ajustar estilos puntuales de una superficie. - Registrar eventos de uso para análisis interno. Consejos, límites y buenas prácticas - Escribe scripts idempotentes y con teardown para evitar duplicación. - Evita dependencias pesadas; prefiere código ligero. - Prueba en un entorno controlado antes de publicar. Solución de problemas - El script no se ejecuta: confirma la superficie y las reglas de ejecución. - Comportamiento duplicado: revisa el teardown y la idempotencia. Ver también - Visión general de API y Desarrolladores - Custom Scripts (Administración)
Eventos por módulo
Visión general Varios módulos de la plataforma emiten eventos cuando algo cambia — se crea una conversación, se confirma un pago, un negocio cambia de etapa, etc. Puedes reaccionar a estos eventos vía webhooks o mediante las reglas de automatización internas. Requisitos previos - Webhooks configurados (para consumo externo) o acceso a Automatización (para reacciones internas). Paso a paso 1. Identifica el evento del módulo que quieres consumir (ej.: conversación creada, pago pagado). 2. Para consumo externo: suscríbete al evento en el webhook y maneja el payload en tu endpoint. 3. Para reacciones internas: crea una regla de automatización con el disparador correspondiente. 4. Valida y procesa el payload de forma idempotente. Configuración y opciones - Webhooks: suscripción por bandeja/cuenta. - Automatización: disparadores por evento, con condiciones y acciones. - Payload: contiene el contexto del evento (ids y datos relevantes). Casos de uso - Actualizar un sistema externo cuando se confirma un pago. - Disparar una cadencia de follow-up cuando un negocio cambia de etapa. Consejos, límites y buenas prácticas - Consulta siempre la fuente real del payload antes de mapear campos (no inventes el formato). - Garantiza idempotencia por identificador del evento. Solución de problemas - El evento no llega: confirma la suscripción y el estado del endpoint. - Campos inesperados: revisa el payload real recibido y ajusta el mapeo. Ver también - API REST, tokens y webhooks - Reglas de automatización