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

# WhatsApp

> Send and receive WhatsApp messages from your own systems. Drive messaging and business-scoped AI off a number connected to meetergo.

The WhatsApp API lets you **send** messages to, and **receive** messages from,
a WhatsApp number connected to meetergo. Address messages by phone number, get
inbound messages via webhook (or polling), and read conversation history. It is
built for teams that want to run their own messaging or business AI on top of
WhatsApp.

<Note>
  Requires the **WhatsApp add-on** and an **API Platform** subscription, and a
  WhatsApp Business number connected in your meetergo dashboard. Calls without the
  add-on return `403`.
</Note>

## The 24-hour window (read this first)

WhatsApp only lets businesses send **free-form** messages within **24 hours** of
the contact's last inbound message (the "customer-service window"). Outside that
window you may only send **pre-approved templates**.

| You want to send                 | Window open | Window closed                     |
| -------------------------------- | ----------- | --------------------------------- |
| `text` (free-form)               | ✅ allowed   | ❌ `403` — send a template instead |
| `media` (image / document / ...) | ✅ allowed   | ❌ `403` — send a template instead |
| `template` (approved)            | ✅ allowed   | ✅ allowed                         |

The window opens (and re-opens) whenever the contact messages you. Every
conversation reports `windowOpen` and `windowExpiresAt` so you can decide
client-side. This is a WhatsApp platform rule — meetergo enforces it the same
way via the API and the dashboard.

## Send a message

One endpoint sends all three kinds; pick with `type`. The conversation for the
number is **created or reused automatically** — you never manage conversation
ids to send.

### Text (within the window)

```bash theme={null}
curl https://api.meetergo.com/v4/whatsapp/messages \
  -H "Authorization: Bearer ak_live:..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+491234567890",
    "type": "text",
    "text": "Hi! Your order has shipped."
  }'
```

### Template (anytime)

```bash theme={null}
curl https://api.meetergo.com/v4/whatsapp/messages \
  -H "Authorization: Bearer ak_live:..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+491234567890",
    "type": "template",
    "template": {
      "name": "appointment_reminder",
      "language": "en_US",
      "params": ["John", "Tuesday at 10:00"]
    }
  }'
```

### Media (within the window)

```bash theme={null}
curl https://api.meetergo.com/v4/whatsapp/messages \
  -H "Authorization: Bearer ak_live:..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+491234567890",
    "type": "media",
    "media": {
      "url": "https://files.example.com/invoice.pdf",
      "mimeType": "application/pdf",
      "filename": "invoice.pdf",
      "caption": "Your invoice"
    }
  }'
```

The response is the created message, including its `id`, `conversationId`,
`waMessageId`, and `status`. The media `url` must be **HTTPS** and publicly
reachable by WhatsApp.

### Finding your templates

To send a template you need its exact `name`, `language`, and how many
positional `params` it takes. List them:

```bash theme={null}
curl https://api.meetergo.com/v4/whatsapp/templates \
  -H "Authorization: Bearer ak_live:..."
```

Each entry returns `name`, `language`, `status` (only `APPROVED` can be sent),
`category`, `variableCount` (the length of the `params` array), and the `body`
text with its `{{n}}` placeholders.

### Delivery & read receipts

After you send, the message's status moves `sent` → `delivered` → `read` (or
`failed`). Subscribe to the
[`whatsapp_message_status`](/developer-docs/webhooks/events#whatsapp_message_status)
webhook to track it — the payload carries the `waMessageId` you got back from
the send call, so you can correlate without polling.

## Receive messages

### Webhook (recommended)

Subscribe a webhook to the
[`whatsapp_message_received`](/developer-docs/webhooks/events#whatsapp_message_received)
event. meetergo POSTs every inbound message to your URL with the conversation
id, sender, text, and whether the 24h window just (re)opened. No polling, no new
infrastructure beyond an HTTPS endpoint.

```json theme={null}
{
  "webhookType": "whatsapp_message_received",
  "conversationId": "conv-uuid-123",
  "from": "+491234567890",
  "contactName": "Jane Doe",
  "contactId": null,
  "type": "text",
  "text": "Do you have this in size M?",
  "isFirstMessage": false,
  "windowReopened": true,
  "labels": ["Sales"],
  "receivedAt": "2026-06-25T10:00:00.000Z"
}
```

Reply by calling `POST /v4/whatsapp/messages` with the `from` number. Because
the contact just messaged you, the window is open, so a free-form `text` reply
is allowed.

<Note>
  For media messages (`type` of `image`, `document`, `audio`, ...), the webhook
  signals arrival but does not embed the file. Fetch it, with a fresh
  time-limited URL, via
  `GET /v4/whatsapp/conversations/{conversationId}/messages`.
</Note>

### Polling (fallback)

If you can't host a webhook, poll
`GET /v4/whatsapp/messages?since=<ISO timestamp>`. It returns messages created
after `since`, oldest first, defaulting to inbound only. Persist the returned
`nextSince` and pass it back each cycle. `since` is millisecond-granular; for
guaranteed no-skip delivery, prefer the webhook.

```bash theme={null}
curl "https://api.meetergo.com/v4/whatsapp/messages?since=2026-06-25T10:00:00.000Z" \
  -H "Authorization: Bearer ak_live:..."
```

## Read conversation history

```bash theme={null}
# List conversations (newest first), or look one up by exact number
curl "https://api.meetergo.com/v4/whatsapp/conversations?phone=+491234567890" \
  -H "Authorization: Bearer ak_live:..."

# Messages in a conversation (newest first, cursor-paginated)
curl "https://api.meetergo.com/v4/whatsapp/conversations/conv-uuid-123/messages" \
  -H "Authorization: Bearer ak_live:..."
```

## Endpoints

| Method | Path                                       | Purpose                         |
| ------ | ------------------------------------------ | ------------------------------- |
| `GET`  | `/v4/whatsapp/ping`                        | Connection test (key + add-on)  |
| `POST` | `/v4/whatsapp/messages`                    | Send text / template / media    |
| `GET`  | `/v4/whatsapp/messages?since=`             | Poll inbound messages           |
| `GET`  | `/v4/whatsapp/templates`                   | List approved message templates |
| `GET`  | `/v4/whatsapp/conversations`               | List, or look up by `phone`     |
| `GET`  | `/v4/whatsapp/conversations/{id}`          | Get one conversation            |
| `GET`  | `/v4/whatsapp/conversations/{id}/messages` | List its messages               |

Full schemas and a request playground are in the
[API Reference](/openapi.json) under **WhatsApp V4**.

## Authentication

Use an API key (`Authorization: Bearer ak_live:...`) or a
[Personal Access Token](/developer-docs/personal-access-tokens). With an API
key, you may target a specific sending user with the
`x-meetergo-api-user-id` header; omit it to act as the company owner.

<Warning>
  **Allowed use.** WhatsApp permits business-scoped AI (customer service,
  order/contract/logistics Q\&A) but **bans general-purpose AI assistants**. Keep
  any AI you connect scoped to your business process. You must have opt-in to
  message a contact, and WhatsApp message data must not be used to train
  third-party AI models. These are Meta WhatsApp Business Platform rules.
</Warning>