Convrs API

The Convrs API is a simple, secure JSON API that allows you to interact with the Convrs platform.

As Convrs is event driven, real time events can be delivered by Websockets or via a Webhook that resides on your servers.

To request information from the Convrs API, you can use the same websocket connection, or if using webhooks you can perform JSON POST requests to the API.

Enabling the Convrs API

How to enable and configure API access for your organization.

Enable API Access

Enable the Convrs API for your organization.

Steps:

1. Log onto the Convrs Dashboard and navigate to the Integrations menu.
2. Click on Convrs API.
3. Click on Enable API.

Result: A token will be generated that you need to access the API. This token must be kept secure and is issued for your organization only.

Reset Token

Reset your API token if it has been compromised.

Steps:

1. Navigate to Integrations > Convrs API.
2. Click on Reset Token.

Result: A new token will be issued, and the old token will no longer work.

Configure Webhook

Set up a webhook URL to receive real-time events.

Steps:

1. Navigate to Integrations > Convrs API.
2. Enter your webhook URL in the Webhook URL field.
3. Click Update Webhook.

Disable API

Remove API access for your organization.

Steps:

1. Navigate to Integrations > Convrs API.
2. Click on Disable API.

Result: Your API access will be removed.

Connecting to the API

How to connect to the Convrs API endpoint.

API Endpoint

The endpoint URLs for both websockets and POST requests can be found in the app.

Steps:

1. Navigate to Integrations > Convrs API.
2. The API Endpoints table displays the HTTPS and WSS URLs for your environment.

JSON Objects

Understanding the structure of JSON objects used in the API.

Response Format

The standard format for API responses.

Field	Type	Description
cmd	string	The name of the command/event (case sensitive)
ok	integer	1 if successful, 0 if an error occurred
data	object/array	Object or array containing the response data
uid	string	Unique identifier of the user (optional)
error	string	Human-readable error message (when ok=0)
errorCode	integer	Numeric error code (when ok=0)

Success response example:

{
  "cmd": "GetUser",
  "ok": 1,
  "data": {
    "uid": "73-tel-615940546",
    "name": "Billy Bob",
    "email": "billy@example.com"
  }
}

Error response example:

{
  "cmd": "GetUser",
  "ok": 0,
  "error": "unknown user",
  "errorCode": 1005
}

User Object Fields

Fields returned in user objects from GetUser, GetUsers, and events.

Field	Type	Description
uid	string	Unique identifier for the user (e.g., "73-tel-615940546")
name	string	Full name reported by the messaging platform
first_name	string	User's first name
last_name	string	User's last name
email	string	User's email address (may be empty)
phone	string	User's phone number (may be empty)
bot	string	Source messaging platform (Telegram, Messenger, Web, Line, Viber, CMS, WA3)
botID	integer	Numeric code of the bot
lang	string	User's natural language code (e.g., "en")
created	string	ISO 8601 datetime when user was created
notes	string	Notes associated with the user
url	string	Unique URL to chat with this user (safe for CRM display)

Using Websockets

How to connect and communicate using websockets.

Connect via Websocket

Authenticate your websocket connection.

Steps:

1. Connect to the WSS endpoint shown on the Integrations > Convrs API screen.
2. Send the connect command with your token.

Request:

{
  "cmd": "connect",
  "token": "2730b3490cf32a1c16ac8b91e034aa9f073996f7"
}

Response:

{
  "cmd": "connected",
  "ok": 1
}

Heartbeat

Keep your websocket connection alive.

Request:

{
  "cmd": "heartbeat"
}

Response:

{
  "ok": 1,
  "cmd": "heartbeat",
  "data": {
    "datetime": "2020-04-29T14:34:34.376Z"
  }
}

Using Webhooks and POST Requests

How to receive events and send commands via HTTP.

Receiving Events via Webhook

Configure a webhook to receive real-time events.

Steps:

1. Set your webhook URL in the Convrs Dashboard under Integrations > Convrs API.
2. Convrs will POST a JSON object to your webhook URL on new events.
3. Your response should be any valid HTTP response (200 OK recommended).

Sending Commands via POST

Send commands to the API via HTTP POST.

Steps:

1. Create a JSON object including the token, cmd, and any required parameters.
2. POST to the HTTPS endpoint shown on the Integrations > Convrs API screen.
3. Set the Content-Type header to application/json

Example POST request:

{
  "token": "2730b3490cf32a1c16ac8b91e034aa9f073996f7",
  "cmd": "GetUser",
  "uid": "73-tel-615940546"
}

Available Events

Events delivered to active websocket connections or webhooks. Events are sent automatically when user data changes.

onUserCreate

Sent when a new user is created within the Convrs system.

Payload:

{
  "cmd": "onUserCreate",
  "ok": 1,
  "data": {
    "uid": "73-tel-615940546",
    "name": "Billy Bob",
    "first_name": "Billy",
    "last_name": "Bob",
    "bot": "Telegram",
    "botID": 73,
    "lang": "en",
    "created": "2020-04-23T16:15:24.000Z",
    "notes": "",
    "email": "",
    "phone": "",
    "url": "https://app.conv.rs/u/abc123"
  }
}

onUserUpdate

Sent when a user object is updated. Contains both the full user object and the specific fields that changed.

Payload:

{
  "cmd": "onUserUpdate",
  "ok": 1,
  "data": {
    "user": {
      "uid": "73-tel-615940546",
      "name": "Billy Bob",
      "first_name": "Billy",
      "last_name": "Bob",
      "bot": "Telegram",
      "botID": 73,
      "lang": "en",
      "created": "2020-04-23T16:15:24.000Z",
      "notes": "",
      "email": "billy@example.com",
      "phone": "+44 7912 031410",
      "url": "https://app.conv.rs/u/abc123"
    },
    "update": {
      "email": "billy@example.com"
    }
  }
}

Field	Description
data.user	The complete user object after the update
data.update	Object containing only the fields that were updated and their new values

onUserDelete

Sent when a user is deleted from the Convrs database.

Payload:

{
  "cmd": "onUserDelete",
  "ok": 1,
  "uid": "73-tel-615940546"
}

onUserDisable

Sent when a user has been disabled (e.g., blocked the bot on their messaging platform).

Payload:

{
  "cmd": "onUserDisable",
  "ok": 1,
  "uid": "73-tel-615940546"
}

onUserEnable

Sent when a previously disabled user starts engaging with the bot again.

Payload:

{
  "cmd": "onUserEnable",
  "ok": 1,
  "uid": "73-tel-615940546"
}

onUserConversation

Sent when a conversation between a user and agent has been closed.

Payload:

{
  "cmd": "onUserConversation",
  "ok": 1,
  "uid": "73-tel-615940546",
  "data": [
    {
      "uid": "73-tel-615940546",
      "mid": "5fd89d8f15cf735bd7aaaee0",
      "msg": "Hello, I need help",
      "typ": "text",
      "sender": "client",
      "dt": "2020-12-15T10:30:00.000Z",
      "agent": "John Smith",
      "bot": "Telegram"
    },
    {
      "uid": "73-tel-615940546",
      "mid": "5fd89d9015cf735bd7aaaee1",
      "msg": "Hi! How can I assist you today?",
      "typ": "text",
      "sender": "agent",
      "dt": "2020-12-15T10:30:15.000Z",
      "agent": "John Smith",
      "bot": "Telegram"
    }
  ]
}

Field	Description
data	Array of message objects from the conversation
data[].mid	Unique message identifier
data[].msg	Message text content
data[].typ	Message type: "text", "image", "note", "transfer", "system"
data[].sender	Who sent the message: "client", "agent", or "system"
data[].dt	ISO 8601 datetime when message was sent

Commands - User Data

Commands for retrieving and updating user information.

GetUser

Retrieve a single user by their uid.

Field	Required	Type	Description
token	Yes	string	Your API token
cmd	Yes	string	"GetUser"
uid	Yes	string	The user's unique identifier

Request:

{
  "token": "2730b3490cf32a1c16ac8b91e034aa9f073996f7",
  "cmd": "GetUser",
  "uid": "73-tel-615940546"
}

Response:

{
  "ok": 1,
  "cmd": "GetUser",
  "data": {
    "uid": "73-tel-615940546",
    "name": "Billy Bob",
    "first_name": "Billy",
    "last_name": "Bob",
    "bot": "Telegram",
    "botID": 73,
    "lang": "en",
    "created": "2020-04-28T17:48:15.000Z",
    "notes": "",
    "email": "",
    "phone": "",
    "url": "https://app.conv.rs/u/abc123"
  }
}

GetUsers

Retrieve multiple users. Returns up to 5000 users maximum.

Field	Required	Type	Description
token	Yes	string	Your API token
cmd	Yes	string	"GetUsers"
botID	No	integer	Filter by bot ID
CreatedDate	No	string	Filter users created after this date (ISO 8601)

Request - All users:

{
  "token": "2730b3490cf32a1c16ac8b91e034aa9f073996f7",
  "cmd": "GetUsers"
}

Request - Filtered by date and bot:

{
  "token": "2730b3490cf32a1c16ac8b91e034aa9f073996f7",
  "cmd": "GetUsers",
  "botID": 73,
  "CreatedDate": "2020-03-01T00:00:00"
}

Response:

{
  "ok": 1,
  "cmd": "GetUsers",
  "data": [
    { "uid": "73-tel-615940546", "name": "Billy Bob", ... },
    { "uid": "73-tel-615940547", "name": "Jane Doe", ... }
  ]
}

SetUserData

Set custom user data associated with a user. Optionally trigger a flow route after setting data.

Field	Required	Type	Description
token	Yes	string	Your API token
cmd	Yes	string	"SetUserData"
uid	Yes	string	The user's unique identifier
data	Yes	object	Object containing the user data to set
route	No	string	Flow route to trigger after setting data
overwrite	No	integer	Set to 1 to replace all data instead of merging (default: 0)

Request - Merge data:

{
  "token": "2730b3490cf32a1c16ac8b91e034aa9f073996f7",
  "cmd": "SetUserData",
  "uid": "73-tel-615940546",
  "data": {
    "customerId": "CUST-12345",
    "accountType": "premium"
  }
}

Request - Overwrite and trigger flow:

{
  "token": "2730b3490cf32a1c16ac8b91e034aa9f073996f7",
  "cmd": "SetUserData",
  "uid": "73-tel-615940546",
  "data": { "status": "verified" },
  "route": "welcome_verified",
  "overwrite": 1
}

Response:

{
  "ok": 1,
  "cmd": "SetUserData"
}

SetUserName

Set the name of a user. Automatically splits into first_name and last_name.

Field	Required	Type	Description
token	Yes	string	Your API token
cmd	Yes	string	"SetUserName"
uid	Yes	string	The user's unique identifier
name	Yes	string	The new name (3-50 characters)

Request:

{
  "token": "2730b3490cf32a1c16ac8b91e034aa9f073996f7",
  "cmd": "SetUserName",
  "uid": "73-tel-615940546",
  "name": "John Doe"
}

Response:

{
  "ok": 1,
  "cmd": "SetUserName"
}

SetUserEmail

Set the email of a user.

Field	Required	Type	Description
token	Yes	string	Your API token
cmd	Yes	string	"SetUserEmail"
uid	Yes	string	The user's unique identifier
email	Yes	string	A valid email address

Request:

{
  "token": "2730b3490cf32a1c16ac8b91e034aa9f073996f7",
  "cmd": "SetUserEmail",
  "uid": "73-tel-615940546",
  "email": "john@example.com"
}

Response:

{
  "ok": 1,
  "cmd": "SetUserEmail"
}

SetUserNotes

Set notes for a user.

Field	Required	Type	Description
token	Yes	string	Your API token
cmd	Yes	string	"SetUserNotes"
uid	Yes	string	The user's unique identifier
notes	Yes	string	Notes text (max 1024 characters)

Request:

{
  "token": "2730b3490cf32a1c16ac8b91e034aa9f073996f7",
  "cmd": "SetUserNotes",
  "uid": "73-tel-615940546",
  "notes": "VIP customer. Preferred contact: morning hours."
}

Response:

{
  "ok": 1,
  "cmd": "SetUserNotes"
}

SetUserPhone

Set the phone number of a user.

Field	Required	Type	Description
token	Yes	string	Your API token
cmd	Yes	string	"SetUserPhone"
uid	Yes	string	The user's unique identifier
phone	Yes	string	International phone number (must be valid)

Request:

{
  "token": "2730b3490cf32a1c16ac8b91e034aa9f073996f7",
  "cmd": "SetUserPhone",
  "uid": "73-tel-615940546",
  "phone": "+441511234567"
}

Response:

{
  "ok": 1,
  "cmd": "SetUserPhone"
}

Commands - User Tags

Commands for managing user tags.

GetUserTags

Retrieve all tags for a user.

Field	Required	Type	Description
token	Yes	string	Your API token
cmd	Yes	string	"GetUserTags"
uid	Yes	string	The user's unique identifier

Request:

{
  "token": "2730b3490cf32a1c16ac8b91e034aa9f073996f7",
  "cmd": "GetUserTags",
  "uid": "73-tel-615940546"
}

Response:

{
  "ok": 1,
  "cmd": "GetUserTags",
  "data": ["customer", "vip", "newsletter"]
}

SetUserTag

Add a tag to a user. The tag must already exist in the system.

Field	Required	Type	Description
token	Yes	string	Your API token
cmd	Yes	string	"SetUserTag"
uid	Yes	string	The user's unique identifier
tag	Yes	string	The tag name (3-50 characters)

Request:

{
  "token": "2730b3490cf32a1c16ac8b91e034aa9f073996f7",
  "cmd": "SetUserTag",
  "uid": "73-tel-615940546",
  "tag": "Customer"
}

Response:

{
  "ok": 1,
  "cmd": "SetUserTag"
}

DeleteUserTag

Remove a tag from a user.

Field	Required	Type	Description
token	Yes	string	Your API token
cmd	Yes	string	"DeleteUserTag"
uid	Yes	string	The user's unique identifier
tag	Yes	string	The tag name to remove

Request:

{
  "token": "2730b3490cf32a1c16ac8b91e034aa9f073996f7",
  "cmd": "DeleteUserTag",
  "uid": "73-tel-615940546",
  "tag": "Customer"
}

Response:

{
  "ok": 1,
  "cmd": "DeleteUserTag"
}

CreateUserTag

Create a new tag in the system.

Field	Required	Type	Description
token	Yes	string	Your API token
cmd	Yes	string	"CreateUserTag"
tag	Yes	string	The tag name (3-50 characters)
color	No	string	Hex color code (e.g., "#FF5733")
description	No	string	Tag description (max 100 characters)

Request:

{
  "token": "2730b3490cf32a1c16ac8b91e034aa9f073996f7",
  "cmd": "CreateUserTag",
  "tag": "Premium",
  "color": "#FFD700",
  "description": "Premium subscription customers"
}

Response:

{
  "ok": 1,
  "cmd": "CreateUserTag",
  "data": 1
}

Commands - Conversations

Commands for retrieving conversation history.

GetConversation

Retrieve all chat messages for a specific user.

Field	Required	Type	Description
token	Yes	string	Your API token
cmd	Yes	string	"GetConversation"
uid	Yes	string	The user's unique identifier

Request:

{
  "token": "2730b3490cf32a1c16ac8b91e034aa9f073996f7",
  "cmd": "GetConversation",
  "uid": "73-tel-615940546"
}

Response:

{
  "ok": 1,
  "cmd": "GetConversation",
  "data": [
    {
      "uid": "73-tel-615940546",
      "email": "billy@example.com",
      "name": "Billy Bob",
      "phone": "+447912031410",
      "url": "https://app.conv.rs/u/abc123",
      "aid": 42,
      "agent": "John Smith",
      "agentemail": "john@company.com",
      "mid": "5fd89d8f15cf735bd7aaaee0",
      "msg": "Hello, I need help with my order",
      "typ": "text",
      "sender": "client",
      "dt": "2020-12-15T10:30:00.000Z",
      "bot": "Telegram"
    }
  ]
}

GetConversationsFlat

Retrieve completed conversations between agents and users. Supports polling and date range queries. Limited to 1000 conversations.

Response Field	Description
cid	Conversation ID (unique per conversation)
uid	User identifier
mid	Message identifier
typ	Message type: "text", "image", "transfer", "note", "system"
sender	"client", "agent", or "system"
bot	Channel: Messenger, Web, Line, Viber, Telegram, CMS (SMS), WA3 (WhatsApp)

GetOpenConversations

Retrieve currently open conversations between agents and users.

Response Field	Description
id	Conversation ID
uid	User identifier
aid	Agent ID
agent	Agent name
bid	Bot ID
sdt	Start datetime
aco	Agent message count
uco	User message count

Understanding WhatsApp Message Templates

WhatsApp message templates are pre-approved message formats required for sending business-initiated messages outside the 24-hour conversation window. Understanding how templates work and following best practices is essential to maintaining your messaging capabilities and avoiding account restrictions.

What Are WhatsApp Templates?

Understanding the WhatsApp template messaging system.

When a user messages your business on WhatsApp, a 24-hour "conversation window" opens during which you can send free-form messages. However, to initiate contact with a user outside this window—such as sending appointment reminders, shipping notifications, or marketing messages—you must use a pre-approved template.

Templates are submitted through Meta Business Manager and reviewed before use. Approval is typically immediate for verified businesses but may take up to 24 hours.

Template Categories

• Utility templates - Transactional messages like order confirmations, shipping updates, appointment reminders
• Authentication templates - One-time passwords and verification codes
• Marketing templates - Promotional content, offers, and re-engagement messages (requires explicit opt-in)

Template Quality Rating

How Meta monitors and rates your template performance.

Meta assigns a quality rating to each template based on user feedback over the past seven days. Ratings are:

• High - Template is performing well with good engagement
• Medium - Some negative signals detected; monitor closely
• Low - Significant user complaints; template may be paused

Quality signals include user blocks, reports, read rates, and feedback reasons. Templates with consistently low ratings will be automatically paused or permanently disabled.

Best Practices to Avoid Account Restrictions

Guidelines to maintain your WhatsApp messaging capabilities.

1. Always obtain opt-in consent

Sending messages without user consent is the primary cause of account restrictions. Users must explicitly agree to receive WhatsApp messages from your business before you contact them.

2. Personalize your messages

Avoid generic, impersonal templates. Use placeholders to include the recipient's name and relevant details. Personalized messages receive better engagement and fewer complaints.

3. Provide value, not spam

Send messages that users actually want to receive. Limit message frequency and ensure each message provides clear value. Businesses with strong engagement typically maintain read rates of 65-80%.

4. Include opt-out options

Always provide a clear way for users to stop receiving messages. This is especially important for marketing templates.

5. Follow template formatting guidelines

• Avoid excessive variable placeholders relative to message length
• Don't use adjacent placeholders like {{1}} {{2}}
• Don't include emojis, markup, or newline characters in headers/footers
• Keep messages concise and clear

6. Monitor your quality rating

Regularly check your template quality ratings in Meta Business Manager. Address any templates showing Medium or Low ratings before they get paused.

Official WhatsApp Resources

Links to WhatsApp's official documentation and policies.

• WhatsApp Business Policy - Official policy requirements
• Meta Business Help Center - Template guidelines and best practices

Commands - Sending Messages

Commands for sending messages via the API.

SendWhatsAppTemplate

Send a WhatsApp template message. Templates must be pre-approved by WhatsApp.

Field	Required	Type	Description
token	Yes	string	Your API token
cmd	Yes	string	"SendWhatsAppTemplate"
botID	Yes	integer	The Convrs WhatsApp bot identifier
phone	Yes	string	International mobile phone number
templateName	Yes	string	The WhatsApp template name
language	Yes	string	The template language code (e.g., "en")
parameters	No	array	Array of template parameters for dynamic content
header	No	object	Header parameters (for templates with headers)
agentEmail	No	string	Email of agent to assign the chat to
webhookURL	No	string	URL to receive delivery status updates
webhookPayload	No	object	Custom object to include in webhook callbacks
webhookHeaders	No	array	Array of headers for webhook callbacks

Request - Simple template:

{
  "token": "2730b3490cf32a1c16ac8b91e034aa9f073996f7",
  "cmd": "SendWhatsAppTemplate",
  "botID": 3941,
  "phone": "+44151999999",
  "language": "en",
  "templateName": "followup_inquiry_request"
}

Request - Template with parameters:

{
  "token": "2730b3490cf32a1c16ac8b91e034aa9f073996f7",
  "cmd": "SendWhatsAppTemplate",
  "botID": 3941,
  "phone": "+44151999999",
  "language": "en",
  "templateName": "order_confirmation",
  "parameters": [
    { "type": "text", "text": "David" },
    { "type": "text", "text": "ORD-12345" }
  ]
}

Request - With webhook for delivery tracking:

{
  "token": "2730b3490cf32a1c16ac8b91e034aa9f073996f7",
  "cmd": "SendWhatsAppTemplate",
  "botID": 3941,
  "phone": "+44151999999",
  "language": "en",
  "templateName": "order_update",
  "webhookURL": "https://yourserver.com/whatsapp-callback",
  "webhookPayload": { "orderId": "ORD-12345" }
}

Success Response:

{
  "ok": 1,
  "cmd": "SendWhatsAppTemplate",
  "phoneNumber": "+44151999999",
  "countryIso2": "GB",
  "uid": "3941-wa3-44151999999",
  "mid": "6462d3d8c8b0b08fddc34ca8"
}

Error Response:

{
  "ok": 0,
  "cmd": "SendWhatsAppTemplate",
  "error": "WhatsApp error",
  "errorCode": 3002,
  "whatsappErrorCode": 131047,
  "whatsappErrorDesc": "Re-engagement message"
}

GetWhatsAppTemplate

Retrieve a cached WhatsApp template to inspect its structure.

Field	Required	Type	Description
token	Yes	string	Your API token
cmd	Yes	string	"GetWhatsAppTemplate"
botID	Yes	integer	The Convrs bot identifier
templateName	Yes	string	The WhatsApp template name
language	Yes	string	The template language code

Request:

{
  "token": "2730b3490cf32a1c16ac8b91e034aa9f073996f7",
  "cmd": "GetWhatsAppTemplate",
  "botID": 3941,
  "language": "en",
  "templateName": "followup_inquiry_request"
}

Response:

{
  "ok": 1,
  "cmd": "GetWhatsAppTemplate",
  "template": {
    "name": "followup_inquiry_request",
    "language": "en",
    "status": "APPROVED",
    "components": [...]
  }
}

SendSMSMessage

Send an SMS message to a mobile phone number.

Field	Required	Type	Description
token	Yes	string	Your API token
cmd	Yes	string	"SendSMSMessage"
botID	Yes	integer	The Convrs SMS bot identifier
phone	Yes	string	International mobile phone number
message	Yes	string	The text message to send
agentEmail	No	string	Email of agent to assign the chat to

Request:

{
  "token": "2730b3490cf32a1c16ac8b91e034aa9f073996f7",
  "cmd": "SendSMSMessage",
  "botID": 3941,
  "phone": "+44151999999",
  "message": "Hello! Your order has been shipped."
}

Response:

{
  "ok": 1,
  "cmd": "SendSMSMessage",
  "phoneNumber": "+44151999999",
  "countryIso2": "GB",
  "uid": "3941-cms-44151999999",
  "mid": "9462d3d8c8b0b48fddc34ca8"
}

SendTextMessage

Send a text message to a specific Convrs user (by uid).

Field	Required	Type	Description
token	Yes	string	Your API token
cmd	Yes	string	"SendTextMessage"
uid	Yes	string	The Convrs user ID
message	Yes	string	Message text (max 2000 characters, UTF-8)

Request:

{
  "token": "2730b3490cf32a1c16ac8b91e034aa9f073996f7",
  "cmd": "SendTextMessage",
  "uid": "73-tel-615940546",
  "message": "Thank you for your inquiry!"
}

Response:

{
  "ok": 1,
  "cmd": "SendTextMessage"
}

SendMessage

Send a message with server-side routing logic. Routes are configured on the server.

Field	Required	Type	Description
token	Yes	string	Your API token
cmd	Yes	string	"SendMessage"
phone	Yes	string	Mobile phone number
route	Yes	string	Name of the route for message processing (max 256 chars)
message	No	string	Message text (max 2000 characters, UTF-8)
userdata	No	object	Additional user data for the route

Request:

{
  "token": "2730b3490cf32a1c16ac8b91e034aa9f073996f7",
  "cmd": "SendMessage",
  "phone": "44-792-202-1411",
  "route": "welcome",
  "message": "Welcome to our service!"
}

Response:

{
  "ok": 1,
  "cmd": "SendMessage",
  "mid": "5fd89d8f15cf735bd7aaaee0"
}

GetMessageDetails

Retrieve delivery status information about a sent message.

Field	Required	Type	Description
token	Yes	string	Your API token
cmd	Yes	string	"GetMessageDetails"
mid	Yes	string	The message ID from SendSMSMessage or SendWhatsAppTemplate

Request:

{
  "token": "2730b3490cf32a1c16ac8b91e034aa9f073996f7",
  "cmd": "GetMessageDetails",
  "mid": "6462d3d8c8b0b08fddc34ca8"
}

Response:

{
  "ok": 1,
  "cmd": "GetMessageDetails",
  "uid": "3941-wa3-44151999999",
  "botID": 3941,
  "ack": 3
}

Webhook Callbacks

If you provide a webhookURL when sending WhatsApp templates, you'll receive delivery status updates.

Callback payload:

{
  "ok": 1,
  "mid": "6462d3d8c8b0b08fddc34ca8",
  "uid": "3941-wa3-44151999999",
  "botID": 3941,
  "ack": 2,
  "timestamp": "2024-11-14T14:28:08",
  "webhookPayload": { "orderId": "ORD-12345" }
}

Message Acknowledgement Codes

Understanding message delivery status codes returned by GetMessageDetails and webhook callbacks.

Code	Meaning
-2	User does not exist on WhatsApp (WhatsApp only)
-1	An error occurred (check whatsappErrorCode for details)
0	Message is at the server (WhatsApp)
1	Message has been sent
2	Message has been delivered to the user's device
3	Message has been seen/read by the user (WhatsApp only)
10	User has replied to the template message

API Error Codes

Error codes returned by the API in the errorCode field.

Validation Errors (1000-1099)

Code	Description
1000	Missing API Token
1001	Invalid API Token
1002	Invalid end date passed to the API
1003	Invalid start date passed to the API
1004	Unknown command passed to the API
1005	Unknown user (uid)
1006	Invalid phone number
1007	Invalid phone number length
1008	Missing Chatbot ID
1009	Missing phone number
1010	Missing message
1011	Missing route
1012	Unknown or invalid route
1013	Message max characters reached (2000)
1014	Route name too large (max 256)
1015	Unknown ChatBot ID
1016	Wrong chatbot type for this operation
1017	Invalid JSON object passed to API
1018	Websocket connection reused (previous connection closed)
1019	Websocket Connect expected as first command
1020	Unknown Message ID
1021	Start date is after end date
1022	Invalid name format
1023	Invalid note format
1024	Invalid email format
1025	Missing uid

System Errors (2000-2099)

Code	Description
2000	Unable to create a user
2001	User is chatting to an agent, message cannot be sent
2002	Unable to assign user to agent (invalid agent email)
2003	Internal timeout (typically 5 seconds)
2004	Internal error
2005	SMS sending error
2006	User has been unsubscribed from automatic content
2007	Rate limit reached for this phone number
2008	Rate limit reached for this token
2009	WhatsApp too busy to send more messages

WhatsApp Errors (3000-3049)

Code	Description
3000	No WhatsApp Templates exist for this ChatBot
3001	No WhatsApp template exists for this name and language
3002	WhatsApp API error (see whatsappErrorCode and whatsappErrorDesc)
3003	Missing WhatsApp Template name
3004	Missing WhatsApp Template language field

Tag Errors (3050-3099)

Code	Description
3050	Invalid tag format
3051	Invalid tag color format (must be hex like #FF5733)
3052	Invalid tag description format
3053	Tag does not exist

Phone Number Formats

Valid phone number formats for API commands that require a phone number.

All numbers must include an international prefix and be mobile numbers. The following formats are accepted:

• +447922029419 - With plus prefix
• 447922021419 - Without plus prefix
• +44 792 202 1419 - With spaces
• 44-792-202-1419 - With dashes

The API will normalize the phone number and return the standardized format in the response.