Las API keys permiten que otro sistema tuyo se conecte a FlujosChat sin entrar al panel: una web, un ERP, una tienda online o un proceso interno pueden enviar mensajes, leer conversaciones o consultar consumo según los permisos de la clave.
Para qué sirve
La API pública es una superficie separada de la API interna del dashboard. Está pensada para integraciones estables, donde un sistema externo necesita hablar con FlujosChat de forma programática. Por ejemplo, tu ERP puede enviar un WhatsApp cuando cambia el estado de un pedido, o tu web puede consultar conversaciones asociadas a un cliente.
Los endpoints viven bajo /api/public/v1. Con ella puedes probar la clave con GET /me, consultar el consumo con GET /usage, leer conversaciones y mensajes, cerrar o reabrir una conversación y pausar su bot, leer y escribir los campos personalizados del cliente, listar tus plantillas y enviar mensajes con POST /messages: texto libre, o una plantilla aprobada de WhatsApp para escribirle primero a un cliente. Para el contrato técnico completo, usa la documentación de desarrollo de la API pública.
Crear una key
Solo propietario y administradores
Abre la pantalla de API Keys
Entra en Configuración → API Keys. Si aún no tienes claves, verás la opción Crear mi primera key. Si ya hay claves, usa Nueva key.
Ponle un nombre claro
Usa un nombre que identifique la integración, por ejemplo Integración ERP o Tienda online. Así podrás reconocerla después por su nombre y prefijo visible.
Elige permisos
Marca qué puede hacer esa clave. Vienen marcados tres permisos básicos: leer conversaciones, enviar mensajes y consultar consumo. Los que escriben datos o tienen costo llevan un punto naranja y nunca vienen marcados. Selecciona solo lo que la integración necesita: después no se pueden cambiar.
Copia la clave ahora
Al crearla, FlujosChat muestra la key completa una sola vez. Cópiala y guárdala en un lugar seguro, como las variables de entorno del sistema que la va a usar.
Permisos y límites
Cada API key tiene permisos, también llamados scopes. En la pantalla se muestran con etiquetas legibles:
- Leer conversaciones: listar conversaciones y leer historiales.
- Modificar conversaciones: cerrar o reabrir, pausar el bot y corregir el nombre del cliente.
- Enviar mensajes: enviar mensajes de texto a tus clientes. En WhatsApp, solo dentro de las 24 horas desde su último mensaje.
- Leer plantillas: listar tus plantillas y sus variables.
- Enviar plantillas: enviar plantillas aprobadas de WhatsApp. Cada envío tiene costo y puede iniciar la conversación.
- Leer campos personalizados y Escribir campos personalizados: consultar o rellenar los datos de la ficha del cliente.
- Consultar consumo: leer el consumo del mes frente a la cuota del plan.
La disponibilidad depende de tu plan: la API pública viene en los planes IA de Ventas y Agentes IA, y cada plan fija cuántas keys activas puedes tener, cuántas llamadas al mes y cuántas por minuto con cada key. Si la cuota mensual se agota, la API responde con límite de cuota; si haces demasiadas llamadas en un minuto, responde con límite temporal.
Uso y revocación
Una integración envía la clave en cada request. El formato recomendado es:
Authorization: Bearer fjc_live_...También se acepta el header X-API-Key. Para envíos de mensajes, la API soporta idempotencia con Idempotency-Key: si tu sistema reintenta el mismo envío con la misma clave de idempotencia, FlujosChat devuelve la respuesta original en vez de mandar el mensaje dos veces.
En la lista de API keys verás las claves activas, su prefijo visible, permisos, fecha de creación y último uso. Si una integración deja de existir o sospechas que la clave se compartió mal, pulsa Revocar. Las integraciones que usen esa key dejan de funcionar de inmediato y la acción no se puede deshacer. Las claves revocadas quedan abajo, en Revocadas.
No pegues la key en el navegador
Webhooks: que FlujosChat avise a tu sistema
La API responde cuando tu sistema pregunta. Un webhook funciona al revés: FlujosChat envía un aviso a tu servidor en el momento en que pasa algo, así no tienes que consultar la API cada minuto. Se configuran en Configuración → Webhooks, también solo el propietario y los administradores, y vienen en los mismos planes que la API (el plan fija cuántos webhooks puedes tener).
Registra la dirección de tu servidor
Pulsa Crear mi primer webhook (o Nuevo webhook) y pega la URL que recibirá los avisos. Tiene que ser https y accesible desde internet: no se aceptan direcciones internas ni localhost.
Elige los eventos
Marca solo lo que necesitas: un mensaje recibido, un mensaje enviado, un cambio de estado de un mensaje, una conversación nueva, una conversación que cambió o un campo personalizado escrito. No hay opción de «todos»: un evento nuevo nunca empieza a llegarte sin que lo pidas.
Guarda el secreto de firma
Al crearlo, FlujosChat te muestra una sola vez un secreto que empieza por whsec_. Con él tu servidor comprueba la firma de cada aviso (cabecera X-FlujosChat-Signature) y sabe que viene de FlujosChat. Si lo pierdes, usa Rotar secreto: durante la transición se firma con el nuevo y con el anterior, y cuando tu servidor ya use el nuevo pulsas Terminar rotación.
Con Entregas ves los últimos avisos enviados, la respuesta de tu servidor y el número de intento. Si tu servidor falla, FlujosChat lo reintenta solo varias veces durante unas horas, y también puedes pulsar Reintentar ahora. Con Pausar dejas de recibir avisos sin borrar el webhook. Si falla muchas veces seguidas, se desactiva solo y lo vuelves a activar cuando tu servidor esté listo. Cómo verificar la firma paso a paso está en la documentación de webhooks.
API o MCP
Usa API pública para sistemas externos
La API pública es para integraciones servidor a servidor: tu web, ERP, tienda online o automatización propia. Se autentica con una API key, aplica permisos y cuotas por plan, y expone endpoints estables.
Usa MCP para trabajar con un asistente
MCP es distinto: conecta asistentes como Claude para que tú puedas crear o editar flujos, agentes e informes conversando. La conexión se autoriza con tu usuario y se gestiona desde Configuración → Integraciones → Conexiones MCP. Lo tienes explicado en Conectar Claude y otros asistentes.