> ## Documentation Index
> Fetch the complete documentation index at: https://developers.flowestate.app/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp

> Lista las cuentas remitentes de WhatsApp conectadas de la organización y envía mensajes de WhatsApp puntuales a un lead.

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](https://developers.flowestate.app/es/api-reference/sequences.md). 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.

> [!NOTE]
>
> Una [credencial personal](https://developers.flowestate.app/es/member-access.md) lista y envía solo desde la **cuenta conectada propia** del member. Cuenta global u otra de member → `403 FORBIDDEN`. La auditoría no guarda el cuerpo del mensaje.

***

## Listar cuentas de WhatsApp

```http theme={null}
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](https://developers.flowestate.app/es/api-reference/sequences.md#channelconfig-requerido-para-whatsapp) de WhatsApp o al enviar un mensaje.

### Request

```bash theme={null}
curl https://panel.flowestate.app/api/v1/whatsapp/accounts \
  -H "Authorization: Bearer fe_k_your_key_here"
```

### Response 200

```json theme={null}
{
  "data": [
    {
      "id": "uuid",
      "accountType": "organization",
      "phoneNumber": "+18095551234",
      "status": "connected",
      "memberId": null
    },
    {
      "id": "uuid",
      "accountType": "member",
      "phoneNumber": "+18095555678",
      "status": "connected",
      "memberId": "uuid"
    }
  ]
}
```

| Campo | Tipo | Notas |
| - | - | - |
| `id` | string (uuid) | El id de la cuenta. Pásalo como `whatsappAccountId`. |
| `accountType` | enum | `organization` (la cuenta global de la organización) o `member` (la cuenta de un miembro). |
| `phoneNumber` | string \| null | El número remitente conectado, o `null` si aún no está aprovisionado. |
| `status` | string | Siempre `connected` — solo se devuelven cuentas conectadas. |
| `memberId` | string (uuid) \| null | El miembro dueño para cuentas `member`; `null` para la cuenta global de la organización. |

***

## Enviar un mensaje de WhatsApp

```http theme={null}
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.

> [!WARNING]
>
> **Esto cuesta 1 unidad mensual** de tu cuota, como cualquier request ordinario. Ver [Rate limits](https://developers.flowestate.app/es/rate-limits.md).

### Request body

| Campo | Tipo | Notas |
| - | - | - |
| `leadId` | string (uuid) | **Requerido.** El lead al que mensajear. Debe pertenecer a tu organización y tener un número de teléfono válido. |
| `whatsappAccountId` | string (uuid) | **Requerido.** El id de la cuenta remitente, de [`GET /whatsapp/accounts`](#listar-cuentas-de-whatsapp). |
| `message` | string | **Requerido**, 1..4096 caracteres. Cuando `media` está presente, se usa como caption de la media. |
| `media` | object | Opcional. `{ url (https string), type, mimetype? (string), fileName? (string) }`, donde `type` es uno de [`WhatsappMediaType`](https://developers.flowestate.app/es/enums#whatsappmediatype): `image`, `video`, `document`. |

### Request

```bash theme={null}
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

```json theme={null}
{ "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).
* `403 FORBIDDEN` — credencial personal usando una cuenta que no es del caller.
* `429 NUMBER_RATE_LIMITED` — el número está pausado o sin presupuesto.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.