# Send a WhatsApp message (/api-reference/whatsapp/sendWhatsAppMessage)

## POST /api/v1/whatsapp/messages

Operation ID: `sendWhatsAppMessage`
Send a WhatsApp message
Sends a template, text, media, interactive, location or contacts message to `to` (or `contactId`) from `phoneId` or your default number. Templates can be sent any time; every other type needs the customer to have messaged you in the last 24 hours. A refusal by WhatsApp after the message was created returns 200 with `status: failed` and `error`; a temporary refusal returns 429 or 503 with `Retry-After`, and nothing was delivered.

### Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `Idempotency-Key` | header | no | Any unique string up to 255 characters. Retrying with the same key and body within 24 hours returns the first result instead of acting twice. |

### Request body

`application/json` (required)

```json
{
  "properties": {
    "contactId": {
      "default": "",
      "description": "Id of an existing WhatsApp contact, instead of `to`.",
      "title": "Contactid",
      "type": "string"
    },
    "content": {
      "description": "For `interactive`, `location` or `contacts`: the object the WhatsApp Cloud API takes under that key.",
      "title": "Content"
    },
    "media": {
      "anyOf": [
        {
          "properties": {
            "caption": {
              "default": "",
              "description": "Caption shown under an image, video or document.",
              "maxLength": 1024,
              "title": "Caption",
              "type": "string"
            },
            "filename": {
              "default": "",
              "description": "File name shown for a document.",
              "maxLength": 240,
              "title": "Filename",
              "type": "string"
            },
            "id": {
              "default": "",
              "description": "WhatsApp media id of a file you already uploaded.",
              "maxLength": 128,
              "title": "Id",
              "type": "string"
            },
            "link": {
              "default": "",
              "description": "Public https URL of the file.",
              "maxLength": 2000,
              "title": "Link",
              "type": "string"
            }
          },
          "title": "WhatsAppMediaRef",
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "description": "Required for media types: `link` or `id`."
    },
    "optIn": {
      "anyOf": [
        {
          "properties": {
            "source": {
              "description": "Where consent was collected, e.g. `checkout`.",
              "maxLength": 64,
              "minLength": 1,
              "title": "Source",
              "type": "string"
            },
            "text": {
              "default": "",
              "description": "The consent wording the customer agreed to.",
              "maxLength": 2000,
              "title": "Text",
              "type": "string"
            }
          },
          "required": [
            "source"
          ],
          "title": "WhatsAppOptIn",
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "description": "Record the recipient's opt-in with this send (needed before marketing templates)."
    },
    "phoneId": {
      "default": "",
      "description": "Your sending WhatsApp number's id. Leave out to use your default number.",
      "title": "Phoneid",
      "type": "string"
    },
    "template": {
      "anyOf": [
        {
          "properties": {
            "components": {
              "anyOf": [
                {
                  "items": {
                    "additionalProperties": true,
                    "type": "object"
                  },
                  "type": "array"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Advanced: WhatsApp Cloud API `components` sent as-is instead of `values`.",
              "title": "Components"
            },
            "language": {
              "description": "Template language code, e.g. `en` or `en_US`.",
              "maxLength": 16,
              "minLength": 2,
              "title": "Language",
              "type": "string"
            },
            "name": {
              "description": "Template name exactly as approved.",
              "maxLength": 512,
              "minLength": 1,
              "title": "Name",
              "type": "string"
            },
            "values": {
              "additionalProperties": true,
              "description": "Values for the template's variables: `body` as a list in order (or `{\"1\": ...}`), plus `header` and `buttons` when the template has them.",
              "title": "Values",
              "type": "object"
            }
          },
          "required": [
            "name",
            "language"
          ],
          "title": "WhatsAppTemplateRef",
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "description": "Required for `type=template`."
    },
    "text": {
      "default": "",
      "description": "Message text for `type=text`.",
      "maxLength": 4096,
      "title": "Text",
      "type": "string"
    },
    "to": {
      "default": "",
      "description": "Recipient in international format, e.g. `+919812345678`. Or send `contactId`.",
      "maxLength": 32,
      "title": "To",
      "type": "string"
    },
    "type": {
      "default": "template",
      "description": "`template`, `text`, `image`, `video`, `audio`, `document`, `sticker`, `interactive`, `location` or `contacts`. Everything except `template` needs an open 24-hour window.",
      "title": "Type",
      "type": "string"
    }
  },
  "title": "WhatsAppMessageSend",
  "type": "object"
}
```

Example:

```json
{
  "template": {
    "language": "en",
    "name": "order_update",
    "values": {
      "body": [
        "Asha",
        "#1042"
      ]
    }
  },
  "to": "+919812345678",
  "type": "template"
}
```

### Responses

#### 200 OK

Example (example):

```json
{
  "conversationId": "0b6f2a8e-4c1d-4f7a-8f53-6a1c9e2d7b44",
  "createdAt": "2026-01-15T09:30:00+00:00",
  "id": "7d3c1a52-9f0e-4b8e-9a59-2f4f3c6b1e10",
  "status": "accepted",
  "wamid": "wamid.HBgMOTE5ODEyMzQ1Njc4FQIAERgSQ0Y2"
}
```

#### 400 Bad request: `bad_request`.

Example (The request could not be processed.):

```json
{
  "detail": "The request could not be processed.",
  "error": {
    "code": "bad_request",
    "docUrl": "https://docs.callmitra.ai/errors/bad_request",
    "message": "The request could not be processed.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "invalid_request_error"
  }
}
```

#### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`.

Example (The API key has expired.):

```json
{
  "detail": "The API key has expired.",
  "error": {
    "code": "api_key_expired",
    "docUrl": "https://docs.callmitra.ai/errors/api_key_expired",
    "message": "The API key has expired.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "authentication_error"
  }
}
```

Example (The API key is invalid or has been revoked.):

```json
{
  "detail": "The API key is invalid or has been revoked.",
  "error": {
    "code": "invalid_api_key",
    "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key",
    "message": "The API key is invalid or has been revoked.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "authentication_error"
  }
}
```

Example (Authentication required.):

```json
{
  "detail": "Authentication required.",
  "error": {
    "code": "unauthenticated",
    "docUrl": "https://docs.callmitra.ai/errors/unauthenticated",
    "message": "Authentication required.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "authentication_error"
  }
}
```

#### 403 Forbidden: `api_key_scope_denied`, `permission_denied`.

Example (The API key does not have the scope required for this request.):

```json
{
  "detail": "The API key does not have the scope required for this request.",
  "error": {
    "code": "api_key_scope_denied",
    "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied",
    "message": "The API key does not have the scope required for this request.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "permission_error"
  }
}
```

Example (You do not have permission to perform this action.):

```json
{
  "detail": "You do not have permission to perform this action.",
  "error": {
    "code": "permission_denied",
    "docUrl": "https://docs.callmitra.ai/errors/permission_denied",
    "message": "You do not have permission to perform this action.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "permission_error"
  }
}
```

#### 404 Not found: `resource_not_found`, `whatsapp_template_not_found`.

Example (The requested resource was not found.):

```json
{
  "detail": "The requested resource was not found.",
  "error": {
    "code": "resource_not_found",
    "docUrl": "https://docs.callmitra.ai/errors/resource_not_found",
    "message": "The requested resource was not found.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "not_found_error"
  }
}
```

Example (Template not found.):

```json
{
  "detail": "Template not found.",
  "error": {
    "code": "whatsapp_template_not_found",
    "docUrl": "https://docs.callmitra.ai/errors/whatsapp_template_not_found",
    "message": "Template not found.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "not_found_error"
  }
}
```

#### 409 Conflict: `idempotency_key_reused`, `idempotency_request_in_progress`, `whatsapp_client_message_id_reused`, `whatsapp_marketing_opted_out`, `whatsapp_number_not_connected`, `whatsapp_opt_in_required`, `whatsapp_recipient_opted_out`, `whatsapp_template_not_approved`, `whatsapp_window_closed`.

Example (This Idempotency-Key was already used with a different request body.):

```json
{
  "detail": "This Idempotency-Key was already used with a different request body.",
  "error": {
    "code": "idempotency_key_reused",
    "docUrl": "https://docs.callmitra.ai/errors/idempotency_key_reused",
    "message": "This Idempotency-Key was already used with a different request body.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "idempotency_error"
  }
}
```

Example (A request with this Idempotency-Key is still being processed.):

```json
{
  "detail": "A request with this Idempotency-Key is still being processed.",
  "error": {
    "code": "idempotency_request_in_progress",
    "docUrl": "https://docs.callmitra.ai/errors/idempotency_request_in_progress",
    "message": "A request with this Idempotency-Key is still being processed.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "idempotency_error"
  }
}
```

Example (This message id was already used for a different conversation.):

```json
{
  "detail": "This message id was already used for a different conversation.",
  "error": {
    "code": "whatsapp_client_message_id_reused",
    "docUrl": "https://docs.callmitra.ai/errors/whatsapp_client_message_id_reused",
    "message": "This message id was already used for a different conversation.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "conflict_error"
  }
}
```

Example (The recipient stopped marketing messages.):

```json
{
  "detail": "The recipient stopped marketing messages.",
  "error": {
    "code": "whatsapp_marketing_opted_out",
    "docUrl": "https://docs.callmitra.ai/errors/whatsapp_marketing_opted_out",
    "message": "The recipient stopped marketing messages.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "conflict_error"
  }
}
```

Example (No connected WhatsApp number.):

```json
{
  "detail": "No connected WhatsApp number.",
  "error": {
    "code": "whatsapp_number_not_connected",
    "docUrl": "https://docs.callmitra.ai/errors/whatsapp_number_not_connected",
    "message": "No connected WhatsApp number.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "conflict_error"
  }
}
```

Example (Marketing templates need a recorded opt-in.):

```json
{
  "detail": "Marketing templates need a recorded opt-in.",
  "error": {
    "code": "whatsapp_opt_in_required",
    "docUrl": "https://docs.callmitra.ai/errors/whatsapp_opt_in_required",
    "message": "Marketing templates need a recorded opt-in.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "conflict_error"
  }
}
```

Example (The recipient opted out of WhatsApp messages.):

```json
{
  "detail": "The recipient opted out of WhatsApp messages.",
  "error": {
    "code": "whatsapp_recipient_opted_out",
    "docUrl": "https://docs.callmitra.ai/errors/whatsapp_recipient_opted_out",
    "message": "The recipient opted out of WhatsApp messages.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "conflict_error"
  }
}
```

Example (The template is not approved.):

```json
{
  "detail": "The template is not approved.",
  "error": {
    "code": "whatsapp_template_not_approved",
    "docUrl": "https://docs.callmitra.ai/errors/whatsapp_template_not_approved",
    "message": "The template is not approved.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "conflict_error"
  }
}
```

Example (The 24-hour customer service window is closed.):

```json
{
  "detail": "The 24-hour customer service window is closed.",
  "error": {
    "code": "whatsapp_window_closed",
    "docUrl": "https://docs.callmitra.ai/errors/whatsapp_window_closed",
    "message": "The 24-hour customer service window is closed.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "conflict_error"
  }
}
```

#### 422 Invalid parameters: `parameter_invalid`.

Example (One or more parameters are invalid.):

```json
{
  "detail": [
    {
      "loc": [
        "body",
        "phone"
      ],
      "msg": "Field required",
      "type": "missing"
    }
  ],
  "error": {
    "code": "parameter_invalid",
    "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid",
    "message": "One or more parameters are invalid.",
    "param": "phone",
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "invalid_request_error"
  }
}
```

#### 429 Too many requests: `rate_limit_exceeded`, `whatsapp_upstream_throttled`.

Example (Too many requests. Slow down and retry later.):

```json
{
  "detail": "Too many requests. Slow down and retry later.",
  "error": {
    "code": "rate_limit_exceeded",
    "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded",
    "message": "Too many requests. Slow down and retry later.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "rate_limit_error"
  }
}
```

Example (WhatsApp is limiting messages from this number right now.):

```json
{
  "detail": "WhatsApp is limiting messages from this number right now.",
  "error": {
    "code": "whatsapp_upstream_throttled",
    "docUrl": "https://docs.callmitra.ai/errors/whatsapp_upstream_throttled",
    "message": "WhatsApp is limiting messages from this number right now.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "rate_limit_error"
  }
}
```

#### 500 Server error: `internal_error`.

Example (Something went wrong on our side.):

```json
{
  "detail": "Something went wrong on our side.",
  "error": {
    "code": "internal_error",
    "docUrl": "https://docs.callmitra.ai/errors/internal_error",
    "message": "Something went wrong on our side.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "api_error"
  }
}
```

#### 503 Service unavailable: `whatsapp_upstream_unavailable`.

Example (WhatsApp could not take the message right now.):

```json
{
  "detail": "WhatsApp could not take the message right now.",
  "error": {
    "code": "whatsapp_upstream_unavailable",
    "docUrl": "https://docs.callmitra.ai/errors/whatsapp_upstream_unavailable",
    "message": "WhatsApp could not take the message right now.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "api_error"
  }
}
```

### Error codes

- [`bad_request`](/errors/bad_request)
- [`api_key_expired`](/errors/api_key_expired)
- [`invalid_api_key`](/errors/invalid_api_key)
- [`unauthenticated`](/errors/unauthenticated)
- [`api_key_scope_denied`](/errors/api_key_scope_denied)
- [`permission_denied`](/errors/permission_denied)
- [`resource_not_found`](/errors/resource_not_found)
- [`whatsapp_template_not_found`](/errors/whatsapp_template_not_found)
- [`idempotency_key_reused`](/errors/idempotency_key_reused)
- [`idempotency_request_in_progress`](/errors/idempotency_request_in_progress)
- [`whatsapp_client_message_id_reused`](/errors/whatsapp_client_message_id_reused)
- [`whatsapp_marketing_opted_out`](/errors/whatsapp_marketing_opted_out)
- [`whatsapp_number_not_connected`](/errors/whatsapp_number_not_connected)
- [`whatsapp_opt_in_required`](/errors/whatsapp_opt_in_required)
- [`whatsapp_recipient_opted_out`](/errors/whatsapp_recipient_opted_out)
- [`whatsapp_template_not_approved`](/errors/whatsapp_template_not_approved)
- [`whatsapp_window_closed`](/errors/whatsapp_window_closed)
- [`parameter_invalid`](/errors/parameter_invalid)
- [`rate_limit_exceeded`](/errors/rate_limit_exceeded)
- [`whatsapp_upstream_throttled`](/errors/whatsapp_upstream_throttled)
- [`internal_error`](/errors/internal_error)
- [`whatsapp_upstream_unavailable`](/errors/whatsapp_upstream_unavailable)
