Saltar al contenido principal

Documentation Index

Fetch the complete documentation index at: https://knowledge.flowella.io/llms.txt

Use this file to discover all available pages before exploring further.

La API REST de Flowella te permite enviar mensajes de WhatsApp, gestionar contactos y bajas, listar y enviar plantillas en masa, y obtener analítica de forma programática. Esta página cubre todo lo que necesitas saber antes de llamar a un endpoint. La referencia completa de endpoints vive en la barra lateral API reference (autogenerada a partir del esquema OpenAPI).

​
URL base

https://app.flowella.io
Todos los endpoints v1 están bajo /api/v1.

​
Autenticación

Cada solicitud necesita una clave de API en la cabecera Authorization: 
Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx
Las claves están acotadas por organización: actúan sobre una sola organización de Flowella y heredan los permisos de un Admin en esa organización.

​
Crear una clave

Necesitas el rol Owner o Admin para gestionar claves de API.
  1. Ve a Settings → API keys en la aplicación de Flowella.
  2. Haz clic en Create key y ponle un nombre memorable.
  3. Copia la clave una sola vez: se muestra solo en el momento de la creación.
Trata las claves como contraseñas: nunca las subas al control de versiones, nunca las pegues en un chat y rótalas cuando los compañeros dejen la organización.

​
Verificar una clave

Llama al endpoint de ping para confirmar que una clave es válida: 
curl https://app.flowella.io/api/v1/ping \
  -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx"
Un 200 OK con { "ok": true, "organizationId": "…" } significa que estás autenticado.

​
Errores

Todos los errores se devuelven en un envoltorio consistente: 
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}
Estado HTTPCuándo lo verás
400Falló la validación, cuerpo mal formado o rechazo aguas arriba de Meta
401Falta la clave de API o no es válida
402Pago requerido: tu suscripción no cubre la acción
403Prohibido; por ejemplo, envío a un contacto dado de baja, o Meta no está conectado
404El canal o recurso solicitado no existe
429Limitado por tasa: baja el ritmo
El campo error.code es estable y se puede usar de forma programática. El campo error.message es legible por humanos y puede cambiar.

​
Límites de tasa

Las claves de API están limitadas por tasa por organización. Si superas el límite, recibirás un 429 con el código RATE_LIMITED y el mensaje Too many requests. Espera y reintenta con retraso exponencial. Si estás ejecutando envíos masivos grandes, prefiere POST /api/v1/templates/send con el parámetro throttlePerHour: Flowella aplica el throttling en el servidor, por lo que no necesitas espaciar las solicitudes tú mismo.

​
Paginación

Los endpoints de listado (/conversations, /contacts, /templates) usan paginación por cursor:
  • Pasa limit (de 1 a 100, predeterminado 25) y un cursor opcional.
  • La respuesta contiene items y, cuando hay más resultados, un nextCursor.
  • Pasa nextCursor como parámetro cursor para obtener la siguiente página.
  • Cuando falta nextCursor, has llegado al final.
curl "https://app.flowella.io/api/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). Donde la API acepta fechas, tanto las de solo fecha (2025-01-15) como las ISO 8601 completas se convierten en el servidor.

​
Números de teléfono

Pasa los números de teléfono en formato E.164 (+15551234567) cuando sea posible. Flowella normalizará las variaciones habituales 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 predeterminado. 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 Multicanal.

​
Esquema OpenAPI

El esquema legible por máquina vive en: 
/api-reference/openapi.json
Cárgalo en Postman, Insomnia o tu generador de código preferido.
¿Estás construyendo una integración? Combina esta página con Webhooks para reaccionar a eventos en lugar de hacer polling.