Sending WhatsApp Messages with the Convo Project API

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

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`

Phone numbers must include the country code with no + sign. For example, use 917089379345 for the Indian number +91 70893 79345.

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 to re-engage contacts.

Message Types

Text
Image
Video
Audio
Document

Send a plain text message using type: "text" and a text.body string.

{
  "to": "917089379345",
  "type": "text",
  "recipient_type": "individual",
  "text": {
    "body": "Hello!"
  }
}

Send an image by providing a publicly accessible URL. Use caption to add a description below the image.

{
  "to": "917089379345",
  "type": "image",
  "image": {
    "caption": "Check this out",
    "link": "https://example.com/image.jpg"
  }
}

Send an MP4 video file via a public URL. Captions are displayed below the video player.

{
  "to": "917089379345",
  "type": "video",
  "video": {
    "caption": "Watch this",
    "link": "https://example.com/video.mp4"
  }
}

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

{
  "to": "917089379345",
  "type": "audio",
  "audio": {
    "link": "https://example.com/audio.ogg"
  }
}

Send a PDF, Word document, spreadsheet, or other file. Use filename to control the display name shown to the recipient.

{
  "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

{
  "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 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.

{
  "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

{
  "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"
        }
      }
    }
  }
}

To use draft mode for testing, set "flow_action": "navigate" and add "mode": "draft" inside the parameters object.

Get Started

Core Concepts

Guides

Sending WhatsApp Messages with the Convo Project API

Endpoint

Required fields

Message Types

Interactive Messages

Single product example

Success Response

WhatsApp Flows

Published flow example

​Endpoint

​Required fields

​Message Types

​Interactive Messages

​Single product example

​Success Response

​WhatsApp Flows

​Published flow example

Endpoint

Required fields

Message Types

Interactive Messages

Single product example

Success Response

WhatsApp Flows

Published flow example