> ## Documentation Index
> Fetch the complete documentation index at: https://doc.convo.co.in/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

<ParamField path="project_id" type="string" required>
  Your Convo project ID. You can find this in your Convo dashboard under **Project Settings**.
</ParamField>

## Request Body

<ParamField body="to" type="string" required>
  The recipient's phone number including country code. Do **not** include a leading `+` sign. Example: `917089379345` for an Indian number.
</ParamField>

<ParamField body="type" 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.)    |
</ParamField>

<ParamField body="recipient_type" type="string">
  Specifies the recipient type. Always set this to `"individual"` for direct one-to-one messages.
</ParamField>

<ParamField body="messaging_product" type="string">
  Always set this to `"whatsapp"`.
</ParamField>

<ParamField body="text" type="object">
  Required when `type` is `"text"`.

  <Expandable title="text object fields">
    <ParamField body="text.body" type="string" required>
      The text content of the message. Supports WhatsApp-style formatting (bold, italic, etc.).
    </ParamField>

    <ParamField body="text.preview_url" type="boolean">
      Set to `true` to enable link preview if your message contains a URL. Defaults to `false`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="image" type="object">
  Required when `type` is `"image"`.

  <Expandable title="image object fields">
    <ParamField body="image.link" type="string" required>
      A publicly accessible URL pointing to the image file.
    </ParamField>

    <ParamField body="image.caption" type="string">
      Optional caption text displayed below the image.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="video" type="object">
  Required when `type` is `"video"`.

  <Expandable title="video object fields">
    <ParamField body="video.link" type="string" required>
      A publicly accessible URL pointing to the video file.
    </ParamField>

    <ParamField body="video.caption" type="string">
      Optional caption text displayed below the video.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="audio" type="object">
  Required when `type` is `"audio"`.

  <Expandable title="audio object fields">
    <ParamField body="audio.link" type="string" required>
      A publicly accessible URL pointing to the audio file.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="document" type="object">
  Required when `type` is `"document"`.

  <Expandable title="document object fields">
    <ParamField body="document.link" type="string" required>
      A publicly accessible URL pointing to the document file.
    </ParamField>

    <ParamField body="document.caption" type="string">
      Optional caption displayed with the document.
    </ParamField>

    <ParamField body="document.filename" type="string">
      The filename shown to the recipient (e.g., `invoice_march_2024.pdf`).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="template" type="object">
  Required when `type` is `"template"`. Use this to send pre-approved WhatsApp template (HSM) messages.

  <Expandable title="template object fields">
    <ParamField body="template.name" type="string" required>
      The name of the approved template as registered in WhatsApp Business Manager.
    </ParamField>

    <ParamField body="template.language" type="object" required>
      Language configuration for the template.

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

    <ParamField body="template.components" type="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.).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="interactive" type="object">
  Required when `type` is `"interactive"`.

  <Expandable title="interactive object fields">
    <ParamField body="interactive.type" type="string" required>
      The interactive message subtype. Accepted values: `product`, `product_list`, `flow`.
    </ParamField>

    <ParamField body="interactive.body" type="object">
      The main body of the interactive message. Contains a `text` field (string).
    </ParamField>

    <ParamField body="interactive.footer" type="object">
      Optional footer text. Contains a `text` field (string).
    </ParamField>

    <ParamField body="interactive.action" type="object">
      Defines the interactive elements (product catalog, flow trigger, etc.). Structure varies by `interactive.type`.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

<Tabs>
  <Tab title="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?"
        }
      }'
    ```
  </Tab>

  <Tab title="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! 🎉"
        }
      }'
    ```
  </Tab>

  <Tab title="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"
                }
              ]
            }
          ]
        }
      }'
    ```
  </Tab>

  <Tab title="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"
          }
        }
      }'
    ```
  </Tab>
</Tabs>

## Response

**200 OK**

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

<ResponseField name="messaging_product" type="string">
  Always `"whatsapp"`.
</ResponseField>

<ResponseField name="contacts" type="array">
  Array containing the recipient's input number and resolved WhatsApp ID.
</ResponseField>

<ResponseField name="messages" type="array">
  Array containing the sent message object. Each object includes:

  * `id` (string): The WhatsApp message ID (`wamid...`). Use this to [retrieve message details](/api-reference/messages/get-message).
</ResponseField>

<Note>
  Save the returned `messages[0].id` — you can pass it to the [Get Message](/api-reference/messages/get-message) endpoint to track delivery status, read receipts, and billing details.
</Note>

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