Saltar al contenido principal
Los endpoints de WhatsApp te permiten leer las cuentas remitentes conectadas de la organización y enviar un mensaje puntual a un lead — de inmediato, fuera del motor de secuencias. Los mensajes enviados se hilan en la conversación del inbox del lead. Cada endpoint en esta página opera dentro del tenant de la organización que llama — no puedes leer ni escribir cuentas ni mensajes de WhatsApp de otra organización con la misma key.

​
Listar cuentas de WhatsApp

GET /whatsapp/accounts
Scope: whatsapp:read. Lista las cuentas remitentes de WhatsApp conectadas de la organización. Usa el id devuelto como whatsappAccountId al crear una secuencia de WhatsApp o al enviar un mensaje.

​
Request

curl https://panel.flowestate.app/api/v1/whatsapp/accounts \
  -H "Authorization: Bearer fe_k_your_key_here"

​
Response 200

{
  "data": [
    {
      "id": "uuid",
      "accountType": "organization",
      "phoneNumber": "+18095551234",
      "status": "connected",
      "memberId": null
    },
    {
      "id": "uuid",
      "accountType": "member",
      "phoneNumber": "+18095555678",
      "status": "connected",
      "memberId": "uuid"
    }
  ]
}
CampoTipoNotas
idstring (uuid)El id de la cuenta. Pásalo como whatsappAccountId.
accountTypeenumorganization (la cuenta global de la organización) o member (la cuenta de un miembro).
phoneNumberstring | nullEl número remitente conectado, o null si aún no está aprovisionado.
statusstringSiempre connected — solo se devuelven cuentas conectadas.
memberIdstring (uuid) | nullEl miembro dueño para cuentas member; null para la cuenta global de la organización.

​
Enviar un mensaje de WhatsApp

POST /whatsapp/send
Scope: whatsapp:write. Envía un mensaje puntual de WhatsApp a un único lead de inmediato — fuera del motor de secuencias. El mensaje se envía desde la cuenta indicada y se hila en la conversación del inbox del lead.
Esto cuesta 1 unidad mensual de tu cuota, como cualquier request ordinario. Ver Rate limits.

​
Request body

CampoTipoNotas
leadIdstring (uuid)Requerido. El lead al que mensajear. Debe pertenecer a tu organización y tener un número de teléfono válido.
whatsappAccountIdstring (uuid)Requerido. El id de la cuenta remitente, de GET /whatsapp/accounts.
messagestringRequerido, 1..4096 caracteres. Cuando media está presente, se usa como caption de la media.
mediaobjectOpcional. { url (https string), type, mimetype? (string), fileName? (string) }, donde type es uno de WhatsappMediaType: image, video, document.

​
Request

curl -X POST https://panel.flowestate.app/api/v1/whatsapp/send \
  -H "Authorization: Bearer fe_k_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "leadId": "uuid",
    "whatsappAccountId": "uuid",
    "message": "¡Hola! Aquí está el brochure que pediste.",
    "media": {
      "url": "https://cdn.example.com/brochure.pdf",
      "type": "document",
      "mimetype": "application/pdf",
      "fileName": "brochure.pdf"
    }
  }'

​
Response 200

{ "messageId": "..." }

​
Errores comunes

  • 404 NOT_FOUND — el lead no existe o pertenece a otra organización.
  • 400 OPTED_OUT — el lead se dio de baja de WhatsApp y no se le puede mensajear.
  • 400 ACCOUNT_UNAVAILABLE — la cuenta de WhatsApp no se encontró o no está conectada.
  • 400 BAD_REQUEST — el lead no tiene un número de teléfono válido.
  • 400 VALIDATION_ERROR — body inválido (p. ej. message vacío, leadId no es un UUID, media.type inválido).