The API is a RESTful JSON API. All endpoints require authentication headers and return consistent error responses. This page covers the conventions that apply across every endpoint.

​
What is the base URL?

https://{appId}.api-{region}.cometchat.io/v3/business-messaging/api
Replace {appId} with your CometChat App ID and {region} with your deployment region.

​
How do I authenticate?

Include these headers on every request:
​
appid
string
required
Your CometChat App ID. Uniquely identifies your CometChat app.
​
apikey
string
required
Your CometChat API Key. Authorizes the request.
See the Authentication guide for details.

​
What does the error response look like?

All errors follow a consistent structure: 
{
  "error": {
    "code": "ERR_BAD_REQUEST",
    "message": "User-facing message",
    "devMessage": "Developer-facing detail",
    "details": { "field": "validation error" }
  }
}
​
error.code
string
Machine-readable error code in SCREAMING_SNAKE_CASE.
​
error.message
string
A user-facing error message safe to display in UI.
​
error.devMessage
string
A developer-facing message with additional debugging detail.
​
error.details
object
Optional field-level validation errors. Keys are field names, values are error descriptions.

​
What are the common error codes?

CodeHTTP StatusDescription
ERR_BAD_REQUEST400Invalid request body or parameters
ERR_UNAUTHORIZED401Missing or invalid credentials
ERR_NOT_FOUND404Resource not found
ERR_TEMPLATE_NOT_APPROVED400Template is not in approved status
ERR_INVALID_VARIABLES400Missing or invalid template variables
ERR_TARGET_LIMIT_EXCEEDED400Too many targets for the mode
ERR_INVALID_MODE400Invalid delivery mode

​
How does pagination work?

List endpoints return paginated results. Use query parameters to control pagination:
​
page
integer
default:"1"
Page number (1-indexed).
​
limit
integer
default:"20"
Number of items per page.
Responses include pagination metadata alongside the data array.
All timestamps in the API use ISO 8601 format (e.g., 2024-01-15T09:30:00.000Z).