Introducción a la API

La API REST de Flowella te permite enviar mensajes de WhatsApp, gestionar contactos y exclusiones, listar y enviar plantillas en masa, y obtener analíticas — todo programáticamente. Esta página cubre todo lo que necesitas saber antes de llamar a un endpoint. La referencia completa de endpoints se encuentra en la barra lateral Referencia de la API (autogenerada a partir de la especificación OpenAPI).

URL base

https://api.flowella.io/v1

Todos los endpoints v1 se encuentran bajo esta base canónica — por ejemplo https://api.flowella.io/v1/messages.

La API antes vivía en el host de la aplicación en https://app.flowella.io/api/v1/.... Las solicitudes legadas a esa ruta se redirigen permanentemente (308) a la canónica https://api.flowella.io/v1/..., conservando el método y el cuerpo — por lo que las integraciones existentes siguen funcionando. Actualiza tu URL base cuando puedas para saltarte el salto adicional.

Autenticación

Cada solicitud necesita una clave de API en la cabecera Authorization:

Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx

Las claves están limitadas a una organización — actúan en una única organización de Flowella y heredan los permisos de un administrador en esa organización.

Trata las claves como contraseñas. Nunca las incluyas en el control de versiones, nunca las pegues en chats o documentos compartidos, y rótalas cuando algún compañero deje la organización. Consulta Configuración → Claves de API para los pasos de rotación.

Crear una clave

Necesitas el rol de Propietario o Administrador para gestionar las claves de API.

Ve a Configuración → Claves de API en la aplicación de Flowella.
Haz clic en Crear clave y asígnale un nombre memorable.
Copia la clave una vez — solo se muestra en el momento de la creación.

Trata las claves como contraseñas: nunca las incluyas en el control de versiones, nunca las pegues en chats y rótalas cuando algún compañero deje la organización.

Verificar una clave

Llama al endpoint de ping para confirmar que una clave es válida:

curl https://api.flowella.io/v1/ping \
  -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx"

await fetch("https://api.flowella.io/v1/ping", {
  headers: { Authorization: `Bearer ${process.env.FLOWELLA_API_KEY}` },
});

import os, requests

requests.get(
    "https://api.flowella.io/v1/ping",
    headers={"Authorization": f"Bearer {os.environ['FLOWELLA_API_KEY']}"},
)

Un 200 OK con { "ok": true, "organizationId": "…" } significa que estás autenticado.

Errores

Todos los errores devuelven una envoltura consistente:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

Estado HTTP	Cuándo lo verás
`400`	Falló la validación, cuerpo mal formado o rechazo de Meta upstream
`401`	Clave de API faltante o inválida
`402`	Pago requerido — tu suscripción no cubre la acción
`403`	Prohibido — por ejemplo, enviar a un contacto excluido o Meta no está conectado
`404`	El canal o recurso solicitado no existe
`429`	Limitación de velocidad — reduce el ritmo

El campo error.code es estable y seguro para hacer switch programáticamente. El error.message es legible por humanos y puede cambiar.

Límites de velocidad

Las claves de API tienen límites de velocidad por organización. Si superas el límite, recibirás un 429 con el código RATE_LIMITED y el mensaje Too many requests. Cuando esté presente, la cabecera de respuesta Retry-After te indica cuántos segundos esperar. Retrocede y reintenta con retraso exponencial. Si estás ejecutando grandes envíos masivos, prefiere POST /v1/templates/send con el parámetro throttlePerHour — Flowella aplica el límite en el servidor, por lo que no necesitas marcar el ritmo de las solicitudes tú mismo.

Claves de idempotencia

Los envíos masivos de plantillas son asíncronos. POST /v1/templates/send valida la solicitud, la pone en cola de forma duradera y devuelve 202 Accepted inmediatamente:

{
  "id": "v1ts-0123456789abcdef",
  "status": "accepted"
}

Flowella entrega el lote en segundo plano y reintenta automáticamente los errores temporales de WhatsApp. Los destinatarios se procesan individualmente, por lo que un número inválido no bloquea el resto del lote. Sigue el progreso de entrega en la pestaña Estadísticas de la plantilla en la aplicación. Como la entrega ocurre después de la respuesta, los reintentos deben ser seguros. Pasa una cabecera Idempotency-Key (hasta 200 caracteres) que identifique cada lote de forma única:

curl -X POST "https://api.flowella.io/v1/templates/send" \
  -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: campaign-2026-08-31-launch" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "whatsappChannelId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "recipients": [{ "phone": "+15551234567" }]
  }'

Las repeticiones de la misma clave dentro de siete días devuelven el id del trabajo original en lugar de crear un nuevo envío. Puedes reintentar una solicitud de forma segura después de un timeout o error de red sin enviar mensajes a nadie dos veces. Si omites la cabecera, Flowella deriva una clave del cuerpo de la solicitud. Un lote idéntico enviado dos veces en rápida sucesión no se envía por duplicado. Aun así, una clave explícita es más segura, porque cualquier cambio en el cuerpo (incluso reordenar los destinatarios) produce una clave derivada nueva.

Paginación

Los endpoints de listado (/conversations, /contacts, /templates) usan paginación por cursor:

Pasa limit (1–100, por defecto 25) y un cursor opcional.
La respuesta contiene items y, cuando hay más resultados, un nextCursor.
Pasa nextCursor como el parámetro cursor para obtener la siguiente página.
Cuando falta nextCursor, has llegado al final.

curl "https://api.flowella.io/v1/conversations?limit=50" \
  -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx"

Fecha y hora

Todas las marcas de tiempo son cadenas ISO 8601 en UTC (por ejemplo 2025-01-15T14:30:00.000Z). Cuando la API acepta fechas, tanto solo fecha (2025-01-15) como ISO 8601 completo se coercionan en el servidor.

Números de teléfono

Pasa los números de teléfono en formato E.164 (+15551234567) siempre que sea posible. Flowella normaliza variaciones comunes en el servidor, pero E.164 es lo más seguro.

Canales

Muchos endpoints aceptan un whatsappChannelId. Si tu organización tiene un solo canal y lo omites, Flowella usa tu canal por defecto. Si tienes varios canales, pasa el ID explícitamente para evitar enviar desde el remitente equivocado. Para el patrón de URL completo y el cambio de canal, consulta Multi-canal.

Especificación OpenAPI

La especificación legible por máquinas se encuentra en:

/api-reference/openapi.json

Súbela a Postman, Insomnia o tu generador de código preferido.

¿Construyendo una integración? Combina esta página con Webhooks para reaccionar a eventos en lugar de sondear el estado.

Primeros pasos

Registro de cambios

Esenciales

Uso de la aplicación

Configuración

Configuración de Meta y WhatsApp

Integración con HubSpot

Flujos y campañas

Cuenta e inicio de sesión

Seguridad y privacidad

Referencia de API

Solución de problemas

Introducción a la API

URL base

Autenticación

Crear una clave

Verificar una clave

Errores

Límites de velocidad

Claves de idempotencia

Paginación

Fecha y hora

Números de teléfono

Canales

Especificación OpenAPI

​URL base

​Autenticación

​Crear una clave

​Verificar una clave

​Errores

​Límites de velocidad

​Claves de idempotencia

​Paginación

​Fecha y hora

​Números de teléfono

​Canales

​Especificación OpenAPI

URL base

Autenticación

Crear una clave

Verificar una clave

Errores

Límites de velocidad

Claves de idempotencia

Paginación

Fecha y hora

Números de teléfono

Canales

Especificación OpenAPI