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

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

POST https://connect.api-wa.co/project-apis/v1/project/{project_id}/messages

Authentication

Include your project API password in every request header:

X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD

Path Parameters

string

required

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

Request Body

string

required

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

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

string

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

string

Always set this to "whatsapp".

object

Required when type is "text".

Show text object fields

string

required

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

boolean

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

object

Required when type is "image".

Show image object fields

string

required

A publicly accessible URL pointing to the image file.

string

Optional caption text displayed below the image.

object

Required when type is "video".

Show video object fields

string

required

A publicly accessible URL pointing to the video file.

string

Optional caption text displayed below the video.

object

Required when type is "audio".

Show audio object fields

string

required

A publicly accessible URL pointing to the audio file.

object

Required when type is "document".

Show document object fields

string

required

A publicly accessible URL pointing to the document file.

string

Optional caption displayed with the document.

string

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

object

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

Show template object fields

string

required

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

object

required

Language configuration for the template.

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

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

object

Required when type is "interactive".

Show interactive object fields

string

required

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

object

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

object

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

object

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

Examples

Text Message
Image Message
Template Message
Interactive Product

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?"
    }
  }'

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! 🎉"
    }
  }'

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"
            }
          ]
        }
      ]
    }
  }'

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

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

string

Always "whatsapp".

array

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

array

Array containing the sent message object. Each object includes:

id (string): The WhatsApp message ID (wamid...). Use this to retrieve message details.

Save the returned messages[0].id — you can pass it to the Get Message 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.

Overview

Business & Project

Messages

Contacts

Templates

Campaigns

Webhooks

Catalogue

Media

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

Endpoint

Authentication

Path Parameters

Request Body

Examples

Response

Error Responses

​Endpoint

​Authentication

​Path Parameters

​Request Body

​Examples

​Response

​Error Responses

Endpoint

Authentication

Path Parameters

Request Body

Examples

Response

Error Responses