> ## 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

> List the organization's connected WhatsApp sender accounts and send one-off WhatsApp messages to a lead.

WhatsApp endpoints let you read the organization's connected sender accounts and send a single ad-hoc message to a lead — immediately, outside the [sequence](https://developers.flowestate.app/api-reference/sequences.md) engine. Sent messages thread into the lead's inbox conversation.

Every endpoint on this page operates inside the calling organization's tenant — you cannot read or write WhatsApp accounts or messages from another organization with the same key.

> [!NOTE]
>
> A [personal credential](https://developers.flowestate.app/member-access.md) lists and sends only from the member's **own connected account**. Org-global or another member's account → `403 FORBIDDEN`. Audit does not store the message body.

***

## List WhatsApp accounts

```http theme={null}
GET /whatsapp/accounts
```

**Scope:** `whatsapp:read`. Lists the organization's **connected** WhatsApp sender accounts. Use the returned `id` as the `whatsappAccountId` when creating a WhatsApp [sequence](https://developers.flowestate.app/api-reference/sequences.md#channelconfig-whatsapp-required) or sending a message.

### 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"
    }
  ]
}
```

| Field | Type | Notes |
| - | - | - |
| `id` | string (uuid) | The account id. Pass it as `whatsappAccountId`. |
| `accountType` | enum | `organization` (the org-global account) or `member` (a member's account). |
| `phoneNumber` | string \| null | The connected sender number, or `null` if not yet provisioned. |
| `status` | string | Always `connected` — only connected accounts are returned. |
| `memberId` | string (uuid) \| null | The owning member for `member` accounts; `null` for the org-global account. |

***

## Send a WhatsApp message

```http theme={null}
POST /whatsapp/send
```

**Scope:** `whatsapp:write`. Sends a one-off WhatsApp message to a single lead immediately — outside the sequence engine. The message is sent from the given account and threads into the lead's inbox conversation.

> [!WARNING]
>
> **This costs 1 monthly unit** against your quota, like any ordinary request. See [Rate limits](https://developers.flowestate.app/rate-limits.md).

### Request body

| Field | Type | Notes |
| - | - | - |
| `leadId` | string (uuid) | **Required.** The lead to message. Must belong to your organization and have a valid phone number. |
| `whatsappAccountId` | string (uuid) | **Required.** The sending account id, from [`GET /whatsapp/accounts`](#list-whatsapp-accounts). |
| `message` | string | **Required**, 1..4096 chars. When `media` is present, this is used as the media caption. |
| `media` | object | Optional. `{ url (https string), type, mimetype? (string), fileName? (string) }`, where `type` is one of [`WhatsappMediaType`](https://developers.flowestate.app/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": "Hi! Here is the brochure you asked about.",
    "media": {
      "url": "https://cdn.example.com/brochure.pdf",
      "type": "document",
      "mimetype": "application/pdf",
      "fileName": "brochure.pdf"
    }
  }'
```

### Response 200

```json theme={null}
{ "messageId": "..." }
```

### Common errors

* `404 NOT_FOUND` — the lead does not exist or belongs to another organization.
* `400 OPTED_OUT` — the lead opted out of WhatsApp and cannot be messaged.
* `400 ACCOUNT_UNAVAILABLE` — the WhatsApp account was not found or is not connected.
* `400 BAD_REQUEST` — the lead has no valid phone number.
* `400 VALIDATION_ERROR` — invalid body (e.g. empty `message`, `leadId` not a UUID, invalid `media.type`).
* `403 FORBIDDEN` — personal credential using an account that is not the caller's.
* `429 NUMBER_RATE_LIMITED` — the number is paused or out of budget.


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