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
}

Commands - Reports

Extract report data from the Convrs platform via the API. Report queries return the same data used by the Convrs dashboard reports, delivered as JSON.

Report Command

Request report data by specifying a report ID, date range, and optional filters.

Response Field	Description
subcmd	The report ID that was requested
report	Schema metadata describing the report structure
report.id	Report identifier
report.name	Human-readable report name
report.description	Report description
report.dataType	Data structure type (e.g. SIMPLE_TABLE, DISTRIBUTION, TIME_SERIES_SINGLE)
report.fields	Array of field definitions describing each column in the data
data	Array of report data objects

Date Range and Filters

Requirements for date range and optional filter parameters.

• Both from and to must be provided in ISO 8601 format (UTC).
• The maximum date range is 90 days. Requests exceeding this will return error code 4003.
• from must be before to (error code 1021 if reversed).
• Optional filters are report-dependent — not all reports support all filters. Unsupported filters are ignored.

Rate Limits and Timeouts

Rate limits and timeout behaviour for report queries.

Response Data Formats

How to interpret field values in the report data.

Each field in the report.fields array includes a type property that describes how to interpret the corresponding values in the data array:

Field Type	Value Format	Example
number	Integer	1234
duration	Milliseconds	330000 (5 minutes 30 seconds)
percent	Decimal percentage	45.5
decimal	Number with decimal	3.7
date	ISO 8601 date string	"2026-03-15"
datetime	ISO 8601 datetime string	"2026-03-15T14:30:00Z"
text	Plain string	"Sales Team"
category	Category string	"Customer Service"
id	Raw identifier	12345
agent	Numeric agent ID	42
bot	Bot name (resolved)	"WhatsApp Support"
country	ISO 3166-1 alpha-2 code	"SG"
hour	Hour of day (0-23)	14

Available Reports

The following reports are available via the API. Use the Report ID as the subcmd value.

Report ID	Name	Description
Volume
chatsByHour	Hourly Distribution	Conversation volume across hours of the day
chatsByDay	Daily Volume	Conversation volume trend over the date range
chatsByBot	Chats by Channel	Chat volume grouped by bot/channel
channelVolumeSummary	Channel Volume Summary	Volume, response times, and message totals by channel type
chatsByBotByDay	Chats by Channel by Day	Daily chat volume trend per channel
serviceLevel	Service Level	Service level metrics including answered and missed chats
closureReasons	Closure Reasons	Distribution of how conversations end
queueTimeDistribution	Queue Wait Time Distribution	Customer wait times grouped into time buckets
inboundVsOutbound	Inbound vs Outbound	Conversation direction split over time
durationDistribution	Duration Distribution	Conversation length distribution
dayOfWeekPatterns	Day of Week Patterns	Volume and metrics by day of week
peakHours	Peak Hours Analysis	Identifies busiest hours with peak indicators
firstResponseDistribution	First Response Time Distribution	Agent response times in buckets
repeatContactAnalysis	Repeat Contact Analysis	Users with multiple contacts (FCR approximation)
chatsByCountry	Chats by Country	Conversation volume by customer country
chatsByCountryByDay	Chats by Country by Day	Daily conversation trends by country
serviceLevelByCountry	Service Level by Country	Service quality metrics by customer country
Agent
chatsByAgent	Chats by Agent	Chat volume and performance metrics by agent
chatsByAgentByDay	Chats by Agent by Day	Daily chat volume trend per agent
chatsByAgentByDayByBU	Chats by Agent by Day by BU	Daily chat volume per agent for a specific Business Unit
chatsByAgentByChannel	Chats by Agent by Channel	Agent performance metrics with channel breakdown
chatsByAgentByBU	Chats by Agent by BU	Agent performance for a specific Business Unit
chatsByBU	Chats by Business Unit	Agent performance across all Business Units
agentAvailability	Agent Availability	Agent status change history over the date range
transferRate	Transfer Rate Analysis	Percentage of conversations transferred by agent
messageCountAnalysis	Message Count Analysis	Average messages per conversation by agent
agentWorkloadBalance	Agent Workload Balance	Chat distribution and workload balance across agents
Users
usersCreated	Users Created	New user registrations by bot/channel
usersCreatedWhoChat	Users Created Who Chat	New users split by whether they were assigned to an agent
usersCreatedByCountry	Users Created by Country	New user registrations by country
WhatsApp
whatsAppTemplateUsage	WhatsApp Template Usage	Usage statistics for WhatsApp message templates
campaigns	Campaign Performance	WhatsApp campaign delivery metrics and performance
templateDeliveryFunnel	Template Delivery Funnel	Template message delivery progression
templatePerformance	Template Performance	Compare template effectiveness across key metrics
whatsAppQualityDashboard	WhatsApp Quality Dashboard	Channel quality ratings and messaging limits
templateLanguageEffectiveness	Template Language Effectiveness	Performance comparison across template languages
templateOptimalTiming	Template Optimal Timing	Best times to send templates for maximum replies
AI
csatDistribution	CSAT Score Distribution	Distribution of AI-predicted customer satisfaction scores
sentimentDistribution	Sentiment Distribution	Distribution of conversation sentiments
emotionDistribution	Emotion Distribution	Distribution of detected customer emotions
categoryVolume	Category Volume	Conversation volume by AI-detected topic category
sentimentByHour	Sentiment by Hour	Customer sentiment patterns by hour of day
csatByAgent	CSAT by Agent	Customer satisfaction scores by agent
csatByChannel	CSAT by Channel	Customer satisfaction across channels
csatByBU	CSAT by Business Unit	Customer satisfaction across business units
sentimentByAgent	Sentiment by Agent	Conversation sentiment breakdown by agent
sentimentByChannel	Sentiment by Channel	Conversation sentiment across channels
csatTrend	CSAT Trend	Customer satisfaction trend over time
sentimentTrend	Sentiment Trend	Daily sentiment distribution over time
emotionTrend	Emotion Trend	Daily emotion distribution trend
emotionByCategory	Emotion by Category	Emotions detected by topic category
agentSentimentRanking	Agent Sentiment Ranking	Agent leaderboard by customer sentiment score
dissatisfactionDrivers	Dissatisfaction Drivers	Categories most associated with customer dissatisfaction
categoryByAgent	Category by Agent	Topic categories handled by each agent
aiBotContainment	AI Bot Containment	AI agent resolution and transfer metrics
csatByCountry	CSAT by Country	Customer satisfaction scores by country
sentimentByCountry	Sentiment by Country	Customer sentiment breakdown by country
categoryByCountry	Category by Country	Top conversation categories for each country
Sales
outboundVolume	Outbound Volume	Daily outbound conversation volume trend
agentOutboundPerformance	Agent Outbound Performance	Outbound activity metrics by agent
responseRateAnalysis	Response Rate Analysis	User response rates to outbound messages over time
smsVsWhatsApp	SMS vs WhatsApp Comparison	Compare outbound performance across messaging channels
templateUsageByBU	Template Usage by BU	Template usage breakdown by business unit
outboundByAgentByDay	Outbound by Agent by Day	Daily outbound volume per agent
Executive
csExecutiveSummary	CS Executive Summary	Overview of inbound customer service performance
teamScorecard	Team Performance Scorecard	Compare performance metrics across business units
qualityAssuranceSummary	Quality Assurance Summary	AI-driven quality insights
channelPerformance	Channel Performance Comparison	Compare performance metrics across channels
customerLifecycle	Customer Lifecycle Report	Track customer journey from acquisition through support
escalationAnalysis	Escalation Analysis	Transfer and escalation insights
countryPerformanceScorecard	Country Performance Scorecard	Executive overview comparing all countries

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

Report Errors (4000-4005)

Code	Description
4000	Unknown or missing report ID
4001	Report is not available via the API
4002	Missing date range (both from and to are required)
4003	Date range exceeds maximum (90 days)
4004	Report rate limit exceeded (10 requests per 60 seconds)
4005	Report API not enabled for this organization

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.

Related Topics

• Reports