API Overview

The ChatBreeZ API is a RESTful API designed to help developers integrate WhatsApp messaging into their applications.

Base URL

All API requests should be made to the following base URL:

https://api.chatbreez.com

Authentication

Authentication is handled via the X-API-Key header. You must include your API Key in every request.

Header	Description
X-API-Key	Your secret API key found in the ChatBreeZ dashboard.

Example Header

X-API-Key: your_api_key_here
Content-Type: application/json

Instances

The API uses an :instance parameter in the URL. This is the unique name you gave to your WhatsApp instance when you created it in the dashboard.

Example: https://api.chatbreez.com/whatsapp/send-text/{instance}

Recipients

For any sending endpoint, recipient can be an international WhatsApp phone number or the full sender address from a webhook.

• Include the country code — for example 254123456789.
• Spaces, dashes, parentheses, and a leading + are removed automatically before the number is validated.
• For webhook replies, you can use the complete data.key.remoteJid value, which may end in @lid or @s.whatsapp.net.
• Send an @lid address exactly as received. Do not format it, remove its suffix, or turn it into a phone number.
• Phone-number recipients must be registered on WhatsApp; an unregistered number returns 400 Bad Request.

Error Handling

The API returns standard HTTP status codes to indicate the success or failure of a request.

Status	Meaning	What it indicates
201 Created	Success	The message was queued for delivery, or the resource was created.
400 Bad Request	Invalid request	A required field is missing or invalid, or the recipient is not registered on WhatsApp.
401 Unauthorized	Authentication failed	The X-API-Key header is missing or the key is invalid.
403 Forbidden	Account deactivated	Your ChatBreez account is deactivated. Contact support to reactivate it.
404 Not Found	Instance not found	The instance in the URL does not exist on your account.
409 Conflict	Instance not connected	The instance is not connected to WhatsApp. Reconnect it and scan the QR code before sending.
500 Internal Server Error	Server error	An unexpected error occurred on our side. Try again shortly.
502 Bad Gateway	Message not acknowledged	WhatsApp did not acknowledge the message. Verify the recipient number and try again.

Success Responses

Sending endpoints return 201 Created with the ID of the queued message:

{
  "message": "Message queued for delivery.",
  "messageId": "3EB0C767D097B7C7C030"
}

Keep the messageId if you need to reference the message later when investigating a delivery.

Validation Errors

Requests with missing or invalid fields return 400 Bad Request with one or more field errors:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "recipient: Required · latitude: Expected number, received string"
  }
}

Standard Error Response Shape

All error responses across the sending endpoints follow this shape:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "correlationId": "abc123-def456-ghi789"
  }
}

Field	Description
error.code	A stable error code you can program against (VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT, UPSTREAM_ERROR, INTERNAL_SERVER_ERROR).
error.message	A human-readable explanation of the error.
error.correlationId	A unique ID for the request. Include it when contacting support so the request can be traced in server logs.

Error codes and their meanings are listed on each endpoint's page under Common Errors.