Get Started with the Convo WhatsApp API in Minutes

By the end of this guide, you’ll have authenticated with the Convo API, sent a WhatsApp text message, and verified that it was delivered — all from the command line. No SDK required. Let’s go.

Replace {project_id} in every URL and YOUR_API_PASSWORD in every header with your actual values from the Convo dashboard before running any example.

Get your Project API Password

Every Convo project has a dedicated Project API Password that authenticates your requests. To retrieve yours:

Log in to the Convo Dashboard.
Navigate to Settings → API & Integrations.
Copy the value labelled Project API Password.

This value is passed in the X-API-WA-Project-API-Pwd header on every request. Keep it secret — treat it like a password.

Find your Project ID

Most Convo API endpoints are scoped to a project. Your project_id uniquely identifies the WhatsApp number and configuration you want to interact with.You can find your project_id in two places:

URL bar — When you open a project in the dashboard, the URL contains your project ID: https://app.convo.com/project/{project_id}/...
Project Settings — Navigate to Settings → Project Details and look for the Project ID field.

Copy this value — you’ll use it as a path parameter in every API call.

Send a text message

With your API password and project ID in hand, you’re ready to send your first message. Run the following curl command, substituting your real values:

curl -X POST https://connect.api-wa.co/project-apis/v1/project/{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",
    "text": {
      "body": "Hello from Convo!"
    }
  }'

Field	Description
`to`	Recipient’s phone number in E.164 format (country code + number, no `+` sign).
`type`	Message type — `text` for a plain text message.
`recipient_type`	Always `individual` for one-to-one messages.
`text.body`	The message content, up to 4096 characters.

Text messages can only be sent within a 24-hour customer service window — that is, after the user has messaged you first. To initiate a conversation, use a template message (Step 5).

Check the response

A successful request returns HTTP 200 with a JSON body confirming the message was accepted by WhatsApp:

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

The messages[0].id field is the WhatsApp message ID (wamid). You can use this ID to correlate delivery and read receipts that arrive via webhooks. If you receive a 4xx response instead, double-check your API password and project ID.

Send a template message

To message a user who hasn’t contacted you first — or outside the 24-hour service window — you must use a pre-approved Message Template. Templates are created and submitted for approval inside the Convo dashboard under Templates.Once your template is approved, send it like this:

curl -X POST https://connect.api-wa.co/project-apis/v1/project/{project_id}/messages \
  -H "Content-Type: application/json" \
  -H "X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD" \
  -d '{
    "to": "917089379345",
    "type": "template",
    "template": {
      "name": "sample_shipping_confirmation",
      "language": {"policy": "deterministic", "code": "en_us"},
      "components": [
        {
          "type": "body",
          "parameters": [
            {"type": "text", "text": "6-7 days"}
          ]
        }
      ]
    }
  }'

Field	Description
`template.name`	The exact name of your approved template.
`template.language.code`	Language code of the template (e.g. `en_us`, `hi`, `es`).
`components`	Array of component objects supplying dynamic variable values.

See the Template Messages guide for a full breakdown of header, body, button, and media components.

What’s Next?

You’ve sent your first WhatsApp message via the Convo API. Here are the natural next steps:

Core Concepts

Understand Businesses, Projects, Contacts, and how they relate to each other.

API Reference

Explore every available endpoint with full parameter and response documentation.

Send Templates

Learn how to build rich template messages with images, buttons, and variables.

Set Up Webhooks

Receive real-time delivery receipts, read events, and inbound message payloads.

​What’s Next?

Core Concepts

API Reference

Send Templates

Set Up Webhooks

What’s Next?