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

# Sending WhatsApp Messages with the Convo Project API

> Learn how to send text, image, video, audio, document, and interactive WhatsApp messages programmatically using the Convo messaging API endpoints.

The `POST /project/{project_id}/messages` endpoint is your single entry point for sending every type of WhatsApp message — plain text, rich media, interactive product cards, and more. Choose the right `type` value and supply the matching payload object, and Convo routes the message to the recipient over WhatsApp Business API.

## Endpoint

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

| Header                     | Value               |
| -------------------------- | ------------------- |
| `X-API-WA-Project-API-Pwd` | `YOUR_API_PASSWORD` |
| `Content-Type`             | `application/json`  |

### Required fields

| Field  | Type   | Description                                                                |
| ------ | ------ | -------------------------------------------------------------------------- |
| `to`   | string | Recipient phone number including country code, no `+` sign                 |
| `type` | string | Message type: `text`, `image`, `video`, `audio`, `document`, `interactive` |

<Note>
  Phone numbers must include the country code with **no `+` sign**. For example, use `917089379345` for the Indian number +91 70893 79345.
</Note>

<Warning>
  WhatsApp's 24-hour session window means you can only send non-template (session) messages to users who have messaged you within the last 24 hours. Sending a session message outside that window will fail. Use an approved [template message](/guides/template-messages) to re-engage contacts.
</Warning>

***

## Message Types

<Tabs>
  <Tab title="Text">
    Send a plain text message using `type: "text"` and a `text.body` string.

    ```json theme={null}
    {
      "to": "917089379345",
      "type": "text",
      "recipient_type": "individual",
      "text": {
        "body": "Hello!"
      }
    }
    ```
  </Tab>

  <Tab title="Image">
    Send an image by providing a publicly accessible URL. Use `caption` to add a description below the image.

    ```json theme={null}
    {
      "to": "917089379345",
      "type": "image",
      "image": {
        "caption": "Check this out",
        "link": "https://example.com/image.jpg"
      }
    }
    ```
  </Tab>

  <Tab title="Video">
    Send an MP4 video file via a public URL. Captions are displayed below the video player.

    ```json theme={null}
    {
      "to": "917089379345",
      "type": "video",
      "video": {
        "caption": "Watch this",
        "link": "https://example.com/video.mp4"
      }
    }
    ```
  </Tab>

  <Tab title="Audio">
    Send an audio clip (OGG, MP3, or AAC) via a public URL. Audio messages appear as a playable waveform in chat.

    ```json theme={null}
    {
      "to": "917089379345",
      "type": "audio",
      "audio": {
        "link": "https://example.com/audio.ogg"
      }
    }
    ```
  </Tab>

  <Tab title="Document">
    Send a PDF, Word document, spreadsheet, or other file. Use `filename` to control the display name shown to the recipient.

    ```json theme={null}
    {
      "to": "917089379345",
      "type": "document",
      "document": {
        "caption": "Invoice",
        "link": "https://example.com/invoice.pdf",
        "filename": "invoice.pdf"
      }
    }
    ```
  </Tab>
</Tabs>

***

## Interactive Messages

Interactive messages let you embed product cards directly in the chat, turning a conversation into a mini storefront. There are two interactive sub-types for catalogue commerce:

| Type           | Description                                                                  |
| -------------- | ---------------------------------------------------------------------------- |
| `product`      | Displays a single product card with price, image, and an Add to Cart button  |
| `product_list` | Displays multiple products organised into sections, each with its own header |

### Single product example

```json theme={null}
{
  "recipient_type": "individual",
  "messaging_product": "whatsapp",
  "to": "917089379345",
  "type": "interactive",
  "interactive": {
    "type": "product",
    "body": {
      "text": "Check out this product"
    },
    "footer": {
      "text": "Limited stock"
    },
    "action": {
      "catalog_id": "570881508310768",
      "product_retailer_id": "someId15"
    }
  }
}
```

> See the [Commerce Catalogues guide](/guides/catalogue-commerce) for full details on setting up your catalogue and sending multi-product messages.

***

## Success Response

A successful request returns HTTP `200` with a JSON body that includes the WhatsApp message ID (`wamid`). Store this ID if you want to correlate delivery status webhooks back to the original send.

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

***

## WhatsApp Flows

WhatsApp Flows let you send rich, multi-screen interactive forms inside a chat — ideal for lead capture, appointment booking, surveys, and onboarding sequences. You send a Flow using `type: "interactive"` with `interactive.type: "flow"`.

Flows have two modes:

| Mode        | When to use                                         |
| ----------- | --------------------------------------------------- |
| `draft`     | Testing only — visible to developers, not end users |
| `published` | Live flows sent to real users                       |

### Published flow example

```json theme={null}
{
  "recipient_type": "individual",
  "messaging_product": "whatsapp",
  "to": "917089379345",
  "type": "interactive",
  "interactive": {
    "type": "flow",
    "header": {
      "type": "text",
      "text": "Book Your Appointment"
    },
    "body": {
      "text": "Choose a date and time that works for you."
    },
    "footer": {
      "text": "Powered by Convo"
    },
    "action": {
      "name": "flow",
      "parameters": {
        "flow_message_version": "3",
        "flow_token": "AQAAAAACS5FpgQ_cAAAAAD0QI3s.",
        "flow_id": "1234567890",
        "flow_cta": "Book Now",
        "flow_action": "navigate",
        "flow_action_payload": {
          "screen": "APPOINTMENT_SCREEN"
        }
      }
    }
  }
}
```

<Note>
  To use draft mode for testing, set `"flow_action": "navigate"` and add `"mode": "draft"` inside the `parameters` object.
</Note>