Para desarrolladores

API pública

Conecta tu ERP, tu tienda online o Zapier con FlujosChat: envía WhatsApp y lee tus conversaciones desde cualquier sistema. Contrato REST estable, autenticado por API key.

Empezar en 2 minutos

La URL base de todos los endpoints es https://api.flujoschat.foo/api/public/v1.

1. Crea tu API key

En tu dashboard: Configuración → API Keys → Nueva key. Elegí sus permisos y guardala: se muestra una sola vez (en nuestra base solo queda su hash, no podemos recuperarla).

2. Envía la key en cada request con el header Authorization:

bash
curl https://api.flujoschat.foo/api/public/v1/me \
  -H "Authorization: Bearer fjc_live_xxxxxxxxxxxxxxxx"

Si responde con los datos de tu empresa, ya estás dentro. La key identifica a tu empresa: todo lo que devuelve la API queda automáticamente acotado a tus datos.

Enviar un WhatsApp

El caso de uso más común — por ejemplo, avisar que un pedido salió:

bash
curl -X POST https://api.flujoschat.foo/api/public/v1/messages \
  -H "Authorization: Bearer fjc_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4512-confirmacion" \
  -d '{"to": "+51987654321", "type": "text", "text": "Tu pedido #4512 fue enviado 🚚"}'

Usá siempre Idempotency-Key

Si tu sistema reintenta el request (timeout, reinicio, cola), la misma Idempotency-Key devuelve la respuesta original en vez de enviar el WhatsApp dos veces. Vale 24 horas. Usá un valor único por acción de negocio, como el ID del pedido.

La ventana de 24 horas de Meta

Solo podés enviar texto libre a alguien que te escribió en las últimas 24 horas. Fuera de esa ventana la API responde 422 WHATSAPP_24H_WINDOW_EXPIRED y tenés que usar una plantilla aprobada. Más sobre la ventana de 24 h →

Endpoints

EndpointScopeQué hace
GET/me—Identidad del caller (empresa, plan, scopes). Útil para probar la key.
GET/usageusage:readConsumo del mes: usado, límite y restante.
GET/conversationsconversations:readLista conversaciones. Filtros: status, phone, limit; paginación por cursor.
GET/conversations/:idconversations:readDetalle de una conversación.
GET/conversations/:id/messagesconversations:readHistorial de mensajes, del más reciente al más antiguo.
POST/messagesmessages:sendEnvía un WhatsApp. Crea o reutiliza la conversación con ese número.

Las respuestas usan siempre el mismo envoltorio: { success, message, data }. Los listados paginan por cursor: la respuesta trae nextCursor, que pasás como ?cursor= para la página siguiente (null = no hay más).

Permisos (scopes)

Al crear la key elegís qué puede hacer. Pedí solo lo mínimo necesario: si tu tienda online únicamente envía avisos, dale messages:send y nada más.

conversations:read

Listar conversaciones y leer sus historiales

messages:send

Enviar mensajes de WhatsApp

usage:read

Consultar el consumo del mes

Cuotas y límites

El acceso a la API y sus cuotas dependen de tu plan. Los planes iniciales no incluyen API; si necesitás integrarla, escribinos y vemos el plan que te sirve.

Cada respuesta trae headers con tu consumo (X-Monthly-Quota-Remaining) y el rate limit por minuto (RateLimit-*). Consultá tu consumo cuando quieras con GET /usage.

Errores

Los errores devuelven { success: false, message, error: { code } }. Los que vas a ver más seguido:

  • 403 API_ACCESS_NOT_INCLUDED — Tu plan no incluye acceso a la API.
  • 403 INSUFFICIENT_SCOPE — La key no tiene el permiso requerido por ese endpoint.
  • 422 WHATSAPP_24H_WINDOW_EXPIRED — El cliente no te escribe hace más de 24 h: usá una plantilla.
  • 429 RATE_LIMITED — Superaste el límite de requests por minuto.
  • 429 MONTHLY_QUOTA_EXCEEDED — Agotaste la cuota mensual de tu plan.

Buenas prácticas

  • Nunca pongas la key en el frontend ni la subas a un repositorio: viaja solo servidor a servidor.
  • Usá una key distinta por sistema (ERP, tienda, Zapier) para poder revocar una sin romper las demás.
  • Si sospechás que se filtró, revocala desde el dashboard: deja de funcionar al instante.

¿Todavía no conectaste tu número de WhatsApp?

Guía: conectar WhatsApp Business API →