Convo REST API Reference: Overview and Auth Guide

The Convo REST API allows you to manage WhatsApp messaging, contacts, campaigns, templates, webhooks, and catalogues programmatically. All endpoints are served over HTTPS and return JSON responses.

Base URL

Every API request is made against the following base URL:

https://connect.api-wa.co/project-apis/v1/

Authentication

Convo uses a single authentication header. Include the X-API-WA-Project-API-Pwd header on every request:

Header	Description
`X-API-WA-Project-API-Pwd`	Project API Password. Tied to a specific project and used for all API requests.

You can find your Project API Password in your Convo dashboard under Settings → Developers → API Keys.

Request Format

All request bodies must be sent as JSON. Set the Content-Type header accordingly:

Content-Type: application/json

Example request with body:

curl -X POST https://connect.api-wa.co/project-apis/v1/project/YOUR_PROJECT_ID/messages \
  -H "X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"to": "919876543210", "type": "text", "messaging_product": "whatsapp", "text": {"body": "Hello!"}}'

Response Format

All responses are returned as JSON objects.

Success response

A successful request returns an HTTP 2xx status code along with a JSON payload. The exact shape varies by endpoint; below is a representative example:

{
  "id": "61f0624bcf0a58553378ceb4",
  "active": true,
  "display_name": "Shop XY",
  "email": "owner@example.com",
  "company": "Shop XY",
  "timezone": "Asia/Calcutta"
}

Error response

When a request fails, the API returns a non-2xx status code and a JSON body in the following shape:

{
  "name": "ERR400",
  "message": "Invalid Business ID!"
}

Error Codes

HTTP Status	Error Name	Meaning
`400`	`ERR400`	Bad Request — one or more required parameters are missing or have invalid values.
`401`	`ERR401`	Unauthorized — the API key is missing, expired, or does not have permission for this resource.
`404`	`ERR404`	Not Found — the requested resource does not exist.
`409`	`ERR409`	Conflict — the resource you are trying to create already exists.
`500`	`ERR500`	Internal Server Error — something went wrong on Convo’s end. Retry with exponential back-off.

All error responses follow the same envelope:

{
  "name": "ERR4xx",
  "message": "A human-readable description of the error."
}

Pagination

Convo endpoints use two pagination styles depending on the resource.

Cursor-based pagination

List endpoints that return large, time-ordered datasets (for example, messages and contacts) use cursor pagination. Pass the opaque cursor string returned in the previous response as the before or after query parameter to page backwards or forwards through results.

GET /messages?after=<cursor>&limit=50

Parameter	Type	Description
`after`	string	Return records after this cursor (next page).
`before`	string	Return records before this cursor (previous page).
`limit`	integer	Maximum number of records to return per page.

The response includes a paging object:

{
  "data": [...],
  "paging": {
    "cursors": {
      "before": "abc123",
      "after":  "xyz789"
    },
    "next": "/messages?after=xyz789&limit=50"
  }
}

Offset-based pagination

Some endpoints (for example, campaign lists) use limit and skip query parameters:

GET /campaigns?limit=20&skip=40

Parameter	Type	Description
`limit`	integer	Maximum number of records to return.
`skip`	integer	Number of records to skip before returning results.

Resource Overview

Messages

Send template messages, session messages, and media to WhatsApp contacts.

Contacts

Create, retrieve, update, and manage your WhatsApp contact list.

Templates

Fetch approved WhatsApp message templates associated with your project.

Campaigns

Schedule and manage broadcast campaigns to segmented contact lists.

Webhooks

Catalogue

Manage your WhatsApp product catalogue and inventory listings.

Business

Retrieve business account details, linked projects, and billing info.

Project

Fetch project-level details including WhatsApp number, plan, and MAU usage.

Overview

Business & Project

Messages

Contacts

Templates

Campaigns

Webhooks

Catalogue

Media

Convo REST API Reference: Overview and Auth Guide

Base URL

Authentication

Request Format

Response Format

Success response

Error response

Error Codes

Resource Overview

Messages

Contacts

Templates

Campaigns

Webhooks

Catalogue

Business

Project

​Base URL

​Authentication

​Request Format

​Response Format

​Success response

​Error response

​Error Codes

​Pagination

​Cursor-based pagination

​Offset-based pagination

​Resource Overview

Messages

Contacts

Templates

Campaigns

Webhooks

Catalogue

Business

Project

Base URL

Authentication

Request Format

Response Format

Success response

Error response

Error Codes

Pagination

Cursor-based pagination

Offset-based pagination

Resource Overview