Introducción a la API

La API REST de Flowella te permite enviar mensajes de WhatsApp, gestionar contactos y exclusiones, crear listas y plantillas de envío masivo y obtener análisis mediante programación. Esta página cubre todo lo que necesitas saber antes de llamar a un punto final. La referencia completa del punto final se encuentra en la barra lateral Referencia API (generada automáticamente a partir de la especificación OpenAPI).

URL base

https://api.flowella.io/v1

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

Anteriormente la API estaba en el host de la app en https://app.flowella.io/api/v1/.... Las solicitudes a esa ruta heredada se redirigen permanentemente (308) a https://api.flowella.io/v1/..., conservando el método y el cuerpo — por lo que las integraciones existentes siguen funcionando. Actualice su URL base cuando pueda para evitar el salto adicional.

Autenticación

Cada petición necesita una clave API en la cabecera Authorization:

Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx

Las claves son de ámbito organizativo: actúan sobre una única organización Flowella y heredan los permisos de un administrador de esa organización.

Trata las claves como contraseñas. Nunca las confirmes en el control de código fuente, nunca las pegues en el chat o en documentos compartidos, y rótalas cuando los compañeros de equipo dejen la organización. Ver Settings → API keys para los pasos de rotación.

Creación de una clave

Necesitas el rol Owner o Admin para gestionar las claves API.

Vaya a Configuración → Claves API en la aplicación Flowella.
Haz clic en Crear clave y dale un nombre memorable.
Copia la clave una vez - sólo se muestra en el momento de la creación.

Trata las claves como contraseñas: nunca las envíes al control de código fuente, nunca las pegues en el chat y rótalas cuando tus compañeros de equipo dejen la organización.

Verificación de una clave

Pulsa el punto final 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á autentificado.

Errores

Todos los errores vuelven en un sobre consistente:

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

Estado HTTP	Cuándo lo verás
`400`	Validación fallida, cuerpo malformado, o rechazo de Meta upstream
`401` Falta la clave API o no es válida.
`402`	Pago requerido - su suscripción no cubre la acción	`403`
`403`	Prohibido - por ejemplo, envío a un contacto excluido, o Meta no está conectado	`404`	Falta la clave API inválida
`404`	El canal o recurso solicitado no existe	`429`
`429` Velocidad limitada: reduzca la velocidad.

El campo error.code es estable y seguro de activar mediante programación. El campo error.message es legible y puede cambiar.

Límites de velocidad

Las claves API están limitadas por organización. Si supera el límite, recibirá un 429 con el código RATE_LIMITED y el mensaje Too many requests. Cuando está presente, la cabecera de respuesta Retry-After le indica cuántos segundos debe esperar. Retroceda y vuelva a intentarlo con un retardo exponencial. Si está realizando envíos masivos de gran volumen, prefiera POST /v1/templates/send con el parámetro throttlePerHour - Flowella aplica el estrangulamiento en el servidor, por lo que no tendrá que controlar el ritmo de las solicitudes.

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 no válido no bloquea el resto del lote. Sigue el progreso de la entrega en la pestaña Estadísticas de la plantilla en la aplicación. Como la entrega se produce después de la respuesta, los reintentos deben ser seguros. Pasa una cabecera Idempotency-Key (hasta 200 caracteres) que identifique de forma única cada lote:

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 en un plazo de siete días devuelven el id del trabajo original en lugar de crear un nuevo envío. Puedes reintentar con seguridad una solicitud tras un tiempo de espera agotado o un error de red sin enviar mensajes a nadie dos veces. Si omites la cabecera, Flowella deriva una clave a partir del cuerpo de la solicitud. Por tanto, 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 nueva clave derivada.

Paginación

Los puntos finales de lista (/conversations, /contacts, /templates) utilizan paginación por cursor:

Pasar limit (1-100, por defecto 25) y un cursor opcional.
La respuesta contiene items y, cuando hay más resultados, un nextCursor.
Devuelva nextCursor como parámetro cursor para obtener la página siguiente.
Cuando falte nextCursor, habrá 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 la fecha (2025-01-15) como la ISO 8601 completa son forzadas por el servidor.

Números de teléfono

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

Canales

Muchos endpoints aceptan un whatsappChannelId. Si tu org tiene un único canal y lo omites, Flowella utilizará tu canal por defecto. Si tienes varios canales, pasa el ID explícitamente para evitar enviar desde el remitente equivocado. Para conocer el patrón de URL completo y el cambio de canal, consulte Multicanal.

OpenAPI spec

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

/api-reference/openapi.json

Introdúcela en Postman, Insomnia o el generador de código que prefieras.

¿Estás construyendo una integración? Empareja 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

Creación de una clave

Verificación de una clave

Errores

Límites de velocidad

Claves de idempotencia

Paginación

Fecha y hora

Números de teléfono

Canales

OpenAPI spec

​URL base

​Autenticación

​Creación de una clave

​Verificación de una clave

​Errores

​Límites de velocidad

​Claves de idempotencia

​Paginación

​Fecha y hora

​Números de teléfono

​Canales

​OpenAPI spec

URL base

Autenticación

Creación de una clave

Verificación de una clave

Errores

Límites de velocidad

Claves de idempotencia

Paginación

Fecha y hora

Números de teléfono

Canales

OpenAPI spec