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

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

> [!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](https://convo.co.in/docs/guides/template-messages.md) to re-engage contacts.

***

## Message Types

**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!"
  }
}
```

**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"
  }
}
```

**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"
  }
}
```

**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"
  }
}
```

**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"
  }
}
```

***

## 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](https://convo.co.in/docs/guides/catalogue-commerce.md) 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.


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