# Messages

## Endpoints

- `POST /graph/whatsapp/{version}/{phoneNumberId}/messages`: [Send a message](https://docs.polymorfa.com/api/graph/messages/send-a-message)
- `POST /graph/whatsapp/{version}/{phoneNumberId}/message_qrdls`: [Create QR code](https://docs.polymorfa.com/api/graph/messages/create-qr-code)
- `GET /graph/whatsapp/{version}/{phoneNumberId}/message_qrdls`: [List QR codes](https://docs.polymorfa.com/api/graph/messages/list-qr-codes)

## Send a message

`POST https://api.polymorfa.com/graph/whatsapp/{version}/{phoneNumberId}/messages` (Graph API)

Required permission: `messages:write`

**Protocols:** Linked Device API · Meta Cloud API

**Required scope:** `messages:write`

Graph read and typing status requests require an Official API connection. Linked Device connections return a capability error; use the native Messaging API with chat context for read or typing actions there. Official API typing requests are a successful no-op. Structured order_details and order_status interactive messages are not generally available. They are sent only for teams where they are enabled, from Official API Numbers that Meta has made eligible for payments in Brazil. Other teams receive Meta-compatible capability error 131026 without a provider send.

Structured `order_details` and `order_status` interactive messages are not
available for Linked Devices or Official API Numbers. The API returns
capability error `131026` before a provider send. A received order message is
an order snapshot, not proof that the customer paid. Confirm settlement with
your payment provider before marking an order paid.

### Path parameters

- `version` (string, required). Specifies version for this path parameter.
- `phoneNumberId` (string, required). Identifier for the phone number.

### Body

- `messaging_product` (string, required). Messaging product associated with this Graph API object.
- `recipient_type` (string). Category assigned to recipient.
- `to` (string). Recipient phone number. When both `to` and `recipient` are present, `to` is used.
- `recipient` (string). Recipient business-scoped user ID, for Official API numbers only. Omit `to` to address this ID. Parent business-scoped user IDs are not accepted.
- `type` (string). Type discriminator for this object. Values: `text`, `image`, `video`, `document`, `audio`, `sticker`, `location`, `contacts`, `reaction`, `interactive`, `template`.
- `text` (object). Text content carried by this object.
  - `body` (string). Primary text content shown to the recipient.
  - `preview_url` (boolean). Whether WhatsApp renders a link preview for URLs in the text message.
- `image` (object). Image attached to or representing this resource.
  - `id` (string). Identifier for this resource.
  - `link` (string). Link associated with this resource.
  - `caption` (string). Caption shown with the attached media.
  - `filename` (string). Filename presented for the media attachment.
  - `voice` (boolean). Whether WhatsApp treats this media payload as a push-to-talk voice message; set this only for audio attachments.
- `video` (object). Structured video values for this graph graph send message request.
  - `id` (string). Identifier for this resource.
  - `link` (string). Link associated with this resource.
  - `caption` (string). Caption shown with the attached media.
  - `filename` (string). Filename presented for the media attachment.
  - `voice` (boolean). Whether WhatsApp treats this media payload as a push-to-talk voice message; set this only for audio attachments.
- `document` (object). Structured document values for this graph graph send message request.
  - `id` (string). Identifier for this resource.
  - `link` (string). Link associated with this resource.
  - `caption` (string). Caption shown with the attached media.
  - `filename` (string). Filename presented for the media attachment.
  - `voice` (boolean). Whether WhatsApp treats this media payload as a push-to-talk voice message; set this only for audio attachments.
- `audio` (object). Structured audio values for this graph graph send message request.
  - `id` (string). Identifier for this resource.
  - `link` (string). Link associated with this resource.
  - `caption` (string). Caption shown with the attached media.
  - `filename` (string). Filename presented for the media attachment.
  - `voice` (boolean). Whether WhatsApp treats this media payload as a push-to-talk voice message; set this only for audio attachments.
- `sticker` (object). Structured sticker values for this graph graph send message request.
  - `id` (string). Identifier for this resource.
  - `link` (string). Link associated with this resource.
  - `caption` (string). Caption shown with the attached media.
  - `filename` (string). Filename presented for the media attachment.
  - `voice` (boolean). Whether WhatsApp treats this media payload as a push-to-talk voice message; set this only for audio attachments.
- `location` (object). Structured location values for this graph graph send message request.
  - `latitude` (number). Latitude in decimal degrees.
  - `longitude` (number). Longitude in decimal degrees.
  - `name` (string). Human-readable name for this resource.
  - `address` (string). Specifies address for this location.
- `contacts` (array of any, max items 1000, nullable items). Contact cards to send in this message.
- `reaction` (object). Reaction applied to the referenced message.
  - `message_id` (string). Identifier for the message.
  - `emoji` (string). Specifies emoji for this reaction.
- `interactive` (any, nullable). For Official API product and product_list sends, catalog_id must belong to a catalog linked to the Number's WABA. Product retailer IDs remain subject to Meta validation.
- `template` (any, nullable). Specifies template for this graph graph send message request.
- `context` (object). Structured context values for this graph graph send message request.
  - `message_id` (string, required). Identifier for the message.
- `status` (string). Message delivery status to report to WhatsApp.
- `message_id` (string). Identifier for the message.
- `typing_indicator` (object). Shows a typing indicator and marks `message_id` read. Requires `status: "read"`.
  - `type` (string, required). Type discriminator for this object. Values: `text`.

### Request

```bash
curl -X POST "https://api.polymorfa.com/graph/whatsapp/v26.0/<phoneNumberId>/messages" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "messaging_product": "whatsapp"
}'
```

### Responses

#### 200

Message sent, or status update accepted
- One of:
  - `GraphSendMessageResponse` (object).
    - `messaging_product` (string, required). Messaging product associated with this Graph API object.
    - `contacts` (array of object, required). Contacts returned or affected by this operation.
      - `input` (string, required). Specifies input for this contact.
      - `wa_id` (string). Recipient phone number. Omitted when the message was addressed with `recipient`.
      - `user_id` (string). Recipient business-scoped user ID. Present only when the message was addressed with `recipient`.
    - `messages` (array of object, required). Messages associated with this graph graph send message response.
      - `id` (string, required). Identifier for this resource.
  - `success` (object).
    - `success` (boolean, required). Whether the request succeeded.

Headers:

- `X-Polymorfa-Error-Code` (string). Polymorfa routing or operation error code; the JSON body retains Meta's numeric error code.
- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "string"
    }
  ],
  "messages": [
    {
      "id": "string"
    }
  ]
}
```

#### 400

Bad request
- `error` (object, required). Error details returned when the operation fails.
  - `message` (string, required). Human-readable message associated with this result.
  - `type` (string, required). Type discriminator for this object.
  - `code` (number, required). Stable machine-readable code for this result.
  - `error_subcode` (number). Machine-readable error subcode for this error.
  - `error_data` (any, nullable). Specifies error data for this error.
  - `fbtrace_id` (string, required). Identifier for the fbtrace.

Headers:

- `X-Polymorfa-Error-Code`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 401

Unauthenticated
Same fields as 400.

Headers:

- `X-Polymorfa-Error-Code`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 403

Permission error
Same fields as 400.

Headers:

- `X-Polymorfa-Error-Code`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 404

Object does not exist
Same fields as 400.

Headers:

- `X-Polymorfa-Error-Code`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 409

Conflict
Same fields as 400.

Headers:

- `X-Polymorfa-Error-Code`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 413

The complete JSON request exceeds 72 MiB before parsing
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 429

Rate limited
Same fields as 400.

Headers:

- `X-Polymorfa-Error-Code`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 500

Internal error
Same fields as 400.

Headers:

- `X-Polymorfa-Error-Code`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 503

Service unavailable
Same fields as 400.

Headers:

- `X-Polymorfa-Error-Code`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

## Create QR code

`POST https://api.polymorfa.com/graph/whatsapp/{version}/{phoneNumberId}/message_qrdls` (Graph API)

Required permission: `messages:write`

**Protocols:** Meta Cloud API

**Required scope:** `messages:write`

### Path parameters

- `version` (string, required). Specifies version for this path parameter.
- `phoneNumberId` (string, required). Identifier for the phone number.

### Body


### Request

```bash
curl -X POST "https://api.polymorfa.com/graph/whatsapp/v26.0/<phoneNumberId>/message_qrdls" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Content-Type: application/json" \
  -d 'null'
```

### Responses

#### 200

QR code

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
null
```

#### 400

Bad request
- `error` (object, required). Error details returned when the operation fails.
  - `message` (string, required). Human-readable message associated with this result.
  - `type` (string, required). Type discriminator for this object.
  - `code` (number, required). Stable machine-readable code for this result.
  - `error_subcode` (number). Machine-readable error subcode for this error.
  - `error_data` (any, nullable). Specifies error data for this error.
  - `fbtrace_id` (string, required). Identifier for the fbtrace.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 401

Unauthenticated
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 403

Permission error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 404

Object does not exist
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 429

Rate limited
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 500

Internal error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

## List QR codes

`GET https://api.polymorfa.com/graph/whatsapp/{version}/{phoneNumberId}/message_qrdls` (Graph API)

Required permission: `sessions:read`

**Protocols:** Meta Cloud API

**Required scope:** `sessions:read`

### Path parameters

- `version` (string, required). Specifies version for this path parameter.
- `phoneNumberId` (string, required). Identifier for the phone number.

### Request

```bash
curl "https://api.polymorfa.com/graph/whatsapp/v26.0/<phoneNumberId>/message_qrdls" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>"
```

### Responses

#### 200

QR codes

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
null
```

#### 400

Bad request
- `error` (object, required). Error details returned when the operation fails.
  - `message` (string, required). Human-readable message associated with this result.
  - `type` (string, required). Type discriminator for this object.
  - `code` (number, required). Stable machine-readable code for this result.
  - `error_subcode` (number). Machine-readable error subcode for this error.
  - `error_data` (any, nullable). Specifies error data for this error.
  - `fbtrace_id` (string, required). Identifier for the fbtrace.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 401

Unauthenticated
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 403

Permission error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 404

Object does not exist
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 429

Rate limited
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 500

Internal error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```
