> ## Documentation Index
> Fetch the complete documentation index at: https://convo.co.in/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /project/{project_id}/messages — Send Message

> POST /project/{project_id}/messages — Send text, image, video, audio, document, template, and interactive WhatsApp messages to any phone number.

This endpoint sends any type of WhatsApp message to a recipient. You can send plain text, media (image, video, audio, document), pre-approved template messages, and interactive messages — all through a single endpoint.

## Endpoint

```text theme={null}
POST https://connect.api-wa.co/project-apis/v1/project/{project_id}/messages
```

## Authentication

Include your project API password in every request header:

```text theme={null}
X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD
```

## Path Parameters

**project\_id** `string` *required*

Your Convo project ID. You can find this in your Convo dashboard under **Project Settings**.

## Request Body

**to** `string` *required*

The recipient's phone number including country code. Do **not** include a leading `+` sign. Example: `917089379345` for an Indian number.

**type** `string` *required*

The type of message to send. Accepted values:

| Value | Description |
| - | - |
| `text` | Plain text message |
| `image` | Image with optional caption |
| `video` | Video with optional caption |
| `audio` | Audio file |
| `document` | Document file (PDF, DOCX, etc.) |
| `template` | Pre-approved WhatsApp message template (HSM) |
| `interactive` | Interactive message (product, flow, etc.) |

**recipient\_type** `string`

Specifies the recipient type. Always set this to `"individual"` for direct one-to-one messages.

**messaging\_product** `string`

Always set this to `"whatsapp"`.

**text** `object`

Required when `type` is `"text"`.

**text object fields**

**text.body** `string` *required*

The text content of the message. Supports WhatsApp-style formatting (bold, italic, etc.).

**text.preview\_url** `boolean`

Set to `true` to enable link preview if your message contains a URL. Defaults to `false`.

**image** `object`

Required when `type` is `"image"`.

**image object fields**

**image.link** `string` *required*

A publicly accessible URL pointing to the image file.

**image.caption** `string`

Optional caption text displayed below the image.

**video** `object`

Required when `type` is `"video"`.

**video object fields**

**video.link** `string` *required*

A publicly accessible URL pointing to the video file.

**video.caption** `string`

Optional caption text displayed below the video.

**audio** `object`

Required when `type` is `"audio"`.

**audio object fields**

**audio.link** `string` *required*

A publicly accessible URL pointing to the audio file.

**document** `object`

Required when `type` is `"document"`.

**document object fields**

**document.link** `string` *required*

A publicly accessible URL pointing to the document file.

**document.caption** `string`

Optional caption displayed with the document.

**document.filename** `string`

The filename shown to the recipient (e.g., `invoice_march_2024.pdf`).

**template** `object`

Required when `type` is `"template"`. Use this to send pre-approved WhatsApp template (HSM) messages.

**template object fields**

**template.name** `string` *required*

The name of the approved template as registered in WhatsApp Business Manager.

**template.language** `object` *required*

Language configuration for the template.

* `code` (string, required): BCP-47 language code, e.g., `"en_us"`, `"hi"`.
* `policy` (string): Typically `"deterministic"`.

**template.components** `array`

Array of component objects to populate template variables. Each component has:

* `type` (string): `"header"`, `"body"`, or `"button"`.
* `parameters` (array): List of parameter objects with `type` and `text` (or `image`, `document`, etc.).

**interactive** `object`

Required when `type` is `"interactive"`.

**interactive object fields**

**interactive.type** `string` *required*

The interactive message subtype. Accepted values: `product`, `product_list`, `flow`.

**interactive.body** `object`

The main body of the interactive message. Contains a `text` field (string).

**interactive.footer** `object`

Optional footer text. Contains a `text` field (string).

**interactive.action** `object`

Defines the interactive elements (product catalog, flow trigger, etc.). Structure varies by `interactive.type`.

## Examples

**Text Message**

```bash theme={null}
curl -X POST \
  "https://connect.api-wa.co/project-apis/v1/project/YOUR_PROJECT_ID/messages" \
  -H "Content-Type: application/json" \
  -H "X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD" \
  -d '{
    "to": "917089379345",
    "type": "text",
    "recipient_type": "individual",
    "messaging_product": "whatsapp",
    "text": {
      "body": "Hello! How can we help you today?"
    }
  }'
```

**Image Message**

```bash theme={null}
curl -X POST \
  "https://connect.api-wa.co/project-apis/v1/project/YOUR_PROJECT_ID/messages" \
  -H "Content-Type: application/json" \
  -H "X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD" \
  -d '{
    "to": "917089379345",
    "type": "image",
    "recipient_type": "individual",
    "messaging_product": "whatsapp",
    "image": {
      "link": "https://example.com/promo-banner.jpg",
      "caption": "Check out our latest offers! 🎉"
    }
  }'
```

**Template Message**

```bash theme={null}
curl -X POST \
  "https://connect.api-wa.co/project-apis/v1/project/YOUR_PROJECT_ID/messages" \
  -H "Content-Type: application/json" \
  -H "X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD" \
  -d '{
    "to": "917089379345",
    "type": "template",
    "messaging_product": "whatsapp",
    "template": {
      "language": {
        "policy": "deterministic",
        "code": "en_us"
      },
      "name": "sample_shipping_confirmation",
      "components": [
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "6-7 days"
            }
          ]
        }
      ]
    }
  }'
```

**Interactive Product**

```bash theme={null}
curl -X POST \
  "https://connect.api-wa.co/project-apis/v1/project/YOUR_PROJECT_ID/messages" \
  -H "Content-Type: application/json" \
  -H "X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD" \
  -d '{
    "to": "917089379345",
    "type": "interactive",
    "messaging_product": "whatsapp",
    "interactive": {
      "type": "product",
      "body": {
        "text": "Check out this product!"
      },
      "footer": {
        "text": "Tap below to view details"
      },
      "action": {
        "catalog_id": "YOUR_CATALOG_ID",
        "product_retailer_id": "YOUR_PRODUCT_ID"
      }
    }
  }'
```

## Response

**200 OK**

```json theme={null}
{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "917089379345",
      "wa_id": "917089379345"
    }
  ],
  "messages": [
    {
      "id": "wamid.HBgMOTE4ODUxOTQ0MzgxFQIAERgSRkMwRDFGM0FCRDI5ODVEREQ3AA=="
    }
  ]
}
```

**messaging\_product** `string`

Always `"whatsapp"`.

**contacts** `array`

Array containing the recipient's input number and resolved WhatsApp ID.

**messages** `array`

Array containing the sent message object. Each object includes:

* `id` (string): The WhatsApp message ID (`wamid...`). Use this to [retrieve message details](https://convo.co.in/docs/api-reference/messages/get-message.md).

> [!NOTE]
>
> Save the returned `messages[0].id` — you can pass it to the [Get Message](https://convo.co.in/docs/api-reference/messages/get-message.md) endpoint to track delivery status, read receipts, and billing details.

## Error Responses

| HTTP Status | Meaning |
| - | - |
| `400` | Bad request — missing required fields or invalid message type/format. |
| `401` | Unauthorized — invalid or missing `X-API-WA-Project-API-Pwd` header. |
| `404` | Project not found — check your `project_id`. |
| `429` | Rate limit exceeded — slow down your request rate. |


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