Convrs API
The Convrs API is a simple, secure JSON API that will allow you to interact with the Convrs platform.
As Convrs is event driven and 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's
Log onto the Convrs Dashboard and navigate to the Integrations menu. Then click on Convrs API. If this menu item is missing, contact Convrs Support to enable this service for your account.
Then click on Enable API.
This will generate a token you will need to access the API. This token must be kept secure and is issued for your organization only. If your token is ever compromised, you can click on Reset Token, and a new token will be issued.
If you plan on using Webhooks, update the URL and click Update Webhook.
If you don’t need the API anymore, simply click on Disable API and your API access will be removed.
Connecting to the Convrs API
The endpoint of the api for both websockets and post requests:
data.conv.rs/api
Only secure requests are supported, ie, https://data.conv.rs/api for post requests and wss://data.conv.rs/api for websockets.
About the JSON objects
For websockets and webhooks/post requests the objects sent/received are identical.
All datetimes are in UTC and are in ISO 8601, ie, “2020-04-18T16:15:24”
Received objects typically arrive in this form:
{
cmd: “abc”,
ok: 1,
data: {},
uid: “def”
}The cmd field contains the name of the command/event and is case sensitive. The data field may contain an object that is related to the command. The uid field is optionally populated with the unique identifier of the user.
The ok field will equal 1 if the command/event is executed with no error.
If an error occurs, the object will typically look like:
{
cmd: “GetUser”,
ok: 0,
error: “Unknown user”
}The error field will contain a human-readable error message.
In many commands/events you will use the Convrs unique identifier (called uid in the API documentation). The uid will uniquely identify the user on the source messaging platform and can be used to update CRM’s. If the same real person engages two separate bots, they will have two separate uid’s. The uid can contain numbers, letters and symbols but is human readable.
For users a field called url is returned. This is a unique url that can be used to chat with this user. This URL is safe to display in 3rd party systems such as CRM’s as the agent will have to authenticate to be able to chat to this user
Using Websockets
Once connected to the API, the first object that you send is the following:
{
cmd: “connect”,
token: “2730b3490cf32a1c16ac8b91e034aa9f073996f7”
}
Where token is the token string from the Convrs dashboard. This will authenticate the token and give you access to the API. On successful connection:
{
cmd: “connected”,
ok: 1
}
You will now receive responses to commands and any real-time events. Note, you do not need to add the token for each command sent.
Depending on your websocket client library keeping websockets ‘alive’ can be a challenge. You can periodically (such as once a minute) send a ‘heartbeat’ command and the server will respond in kind:
From you:
{
"cmd":"heartbeat"
} The server will respond with:
{
"ok":1,
"cmd":"heartbeat",
"data":{
"datetime":"2020-04-29T14:34:34.376Z"
}
}Where the datetime field will contain the current time on the server.
Only 1 active websocket per organization is allowed.
Using Webhooks and Post requests
If you are not using websockets to receive real time events you will need to provide Convrs a webhook which we will call on a new event. To set the webhook, fill out the appropriate field on the integration screen on the Convrs dashboard
On any new events we will post a JSON object to this webhook url. Your response should be any valid server response.
To POST commands to the Convrs, you need to create a JSON object, including the token that is generated in the Convrs Dashboard, the command you wish to run, along with any optional parameters.
The JSON object should be posted to:
https://data.conv.rs/api
With the the header:
Content-Type
Set to:
application/json
Available events
The following events will be delivered to active websocket connections or webhooks if set:
onUserCreate - sent when a user is created
onUserUpdate - sent when a user object is updated
onUserDelete - sent when the user is deleted
onUserEnable - sent when a user is ‘enabled’
onUserDisable - sent when a user is ‘disabled’
onUserCreate
This event is sent when a user is created within the convs system. Typically it will contain the following:
{
"name":"Billy Bob",
"bot":"Telegram",
"uid":"73-tel-615940546",
"first_name":"Billy",
"lang":"en",
"created":"2020-04-23T16:15:24.000Z",
"last_name":"Bob",
"notes":"",
"email":"",
"phone":"",
"botID":73
}
The name is the full name reported by the messaging platform, typically this is just a concatenation of first_name and last_name but may not always be the case.
The bot field contains the source messaging platform, such as Telegram, Messenger etc.
The uid field is the Convrs identifier.
The lang field is the natural language of the user. This may not be populated depending on the source messaging platform.
The created field is when the user was created.
The notes field contains any notes that are associated with the user. The notes would typically be populated via an agent in chat, or can be updated via other systems/processes.
The email field contains the email address of the user. On creation, this is typically blank (see onUserUpdate for more information).
The phone field contains the (mobile) phone number of the user. On creation, this is typically blank (see onUserUpdate for more information).
The botID field contains a numeric code of the bot that created the user.
onUserUpdate
This event is sent when the user object is created. It is important to note that details about a user, such as an email address or phone number isn’t known when the user object is created. This information often comes as an update as the user interacts with the bot.
The data field contains the following objects:
user
update
The user field contains the user object as defined after the update while the update fields contains an object of the fields that have been updated and their values.
Example 1:
The following would be sent when a users email address has been changed.
{
"cmd":"onUserUpdate",
"data":{
"user":{
"name":"Billy Bob",
"bot":"Telegram",
"uid":"73-tel-615940546",
"first_name":"Billy",
"lang":"en",
"created":"2020-04-23T16:15:24.000Z",
"last_name":"Bob",
"notes":"",
"email":"hello@hello.com",
"phone":"+44 7912 031410",
"botID":73
},
"update":{
"email":"hello@hello.com"
}
}
}Example 2:
The following would be sent when a user has created a demo account on an MT4/5 server.
{
"cmd":"onUserUpdate",
"data":{
"user":{
"name":"Billy Bob",
"bot":"Telegram",
"uid":"73-tel-615940546",
"first_name":"Billy",
"lang":"en",
"created":"2020-04-23T16:15:24.000Z",
"last_name":"Bob",
"notes":"",
"email":"hello@hello.com",
"phone":"+44 7912 031410",
"botID":73
"MetaQuotes":{
"platform":"MT4",
"password":"RAhw4qq3M7",
"login":42681
},
},
"update":{
"MetaQuotes":{
"platform":"MT4",
"password":"RAhw4qq3M7",
"login":42681
}
}
}
}
onUserDelete
This event is sent when the user is deleted from the convrs database. The following object would be sent:
{
"cmd":"onUserDelete",
"uid":"73-tel-615940546"
}
Note: Users are only deleted when a bot is deleted or manually deleted within the convrs platform (ie, GDPR request).
onUserDisable
This event is sent when the user has been disabled within the convrs system. Several messaging platforms allow the user to ‘block the bot’ and where we are able to detect this, the user is set to be disabled. No more messages will be sent to the user. Example object:
{
"cmd":"onUserDisable",
"uid":"73-tel-615940546"
}
onUserEnable
If a user who ‘blocked the bot’ starts to engage with the bot, this event is sent. Example object:
{
"cmd":"onUserEnable",
"uid":"73-tel-615940546"
}onUserConversation
When a conversation has been closed between a user and an agent, this event is sent. Example object:
{
"cmd":"onUserConversation",
"uid":"73-tel-615940546"
"data": []
}The data field will contain an array of messages sent between the user and the agent.
Commands
The following “commands” can be sent either by post requests or via an opened websocket connection.
GetUser
This command will get a user.
Example object to send:
{
"token":"abc",
"cmd":"GetUser",
"uid":"73-tel-615940546"
}Example of result:
{
"data":{
"phone":"",
"notes":"",
"created":"2020-04-28T17:48:15.000Z",
"first_name":"Billy",
"bot":"Telegram",
"email":"",
"lang":"en",
"name":"Billy Bob",
"uid":"73-tel-615940546",
"last_name":"Bob",
"botID":73
},
"ok":1,
"cmd":"GetUser"
}
GetUsers
This command will get multiple users. As a default all users will be returned (result will be limited to a maximum of 5000 users). You can query by botID and by created datetime to limit the amount of users returned.
Example 1:
Get all users for your organization:
{
"token":"abc",
"cmd":"GetUsers",
}
Example 2:
Get all users created after March 1st 2020.
{
"token":"abc",
"cmd":"GetUsers",
"CreatedDate":"2020-03-01T00:00:00"
}
Example 3:
Get all users created after March 1st 2020 and for bot 73.
{
"token":"abc",
"cmd":"GetUsers",
"botID": 73,
"CreatedDate":"2020-03-01T00:00:00"
}
Results will be returned as below:
{
"data":[
{
...user...
},
{
...user...
},
],
"Ok":1,
"cmd":"GetUsers"
}
GetConversationsFlat
This command will return completed conversations between agents and users and is typically used to update external CRM systems.
GetConversationsFlat supports two main use cases:
- Allowing the caller to poll periodically to get the latest updates
- To request conversations between defined start and end dates
To poll, the command can be called with no other parameters and the API will remember the state of the last call.
Fields in input object:
start_date: a date in ISO, in utc
end_date: a date in ISO, in utc
reset: a string, “true”, when populated it will reset the polling dates
The command will return the following object:
{
"ok":1,
"cmd":"GetConversationsFlat",
"data":[],
"start_date":"2020-12-21T12:08:29.285Z",
"end_date":"2020-12-21T12:36:42.444Z"
}Where data will contain any array of conversation objects. Each conversation object contains the following fields:
cid: The conversation ID, which will be unique per conversation (string)
uid: A unique identifier for the user (string)
mid: A unique identifier for this message (string)
email: the email of the users, maybe empty or null
phone: the phone number of the user, maybe empty or null
url: This is a unique url that can be used to chat with this user. This URL is safe to display in 3rd party systems such as CRM’s as the agent will have to authenticate to be able to chat to this user
aid: A unique identifier for the agent (integer)
agent: The name of the agent
sender: The direction of the message, one of “client”, “agent” or “system”
dt: Datetime that the message was sent, in UTC.
typ: The type of the message, see below.
bot: The bot channel that this conversation is from. Possible values include Messenger, Web (Web chat), Line, Viber, Telegram, CMS (SMS) and CWA (WhatsApp). More channels are being added all the time.
Each message has a type associated with it:
text : the message is a text message
image: the message is an image message.
transfer: the message is a transfer from one agent to an another, can be ignored in most cases
note: the agent has added an inline note about the user
Depending on the type of message, the following additional fields will be populated.
When an text or note message type:
msg: the textual content of the message
When an image message type:
imageURL: the full url of the image
mimetype: the mimetype of the image
GetConversation
This command will return all the chat messages between agent(s) and the specified user id (uid) and is typically used to update external CRM systems.
Example:
Get all the chat messages for this user id:
{
"token":"abc",
"cmd":"GetConversation",
"uid: "User ID",
}See GetConversationsFlat for examples of what is returned by this command.
SetUserData
This command sets custom user data that is associated with the user. It optionally allows the setting of the route of the flow that the user is currently in, which in turn can send messages and run logic blocks. If a route has been set, it will be ran after the user data has been set. When setting user data, a merge approach is used, where the top level keys of the passed object are only set. This normally is the correct approach to stop other data items being cleared. If the overwrite flag is set to 1, then the user data will be overwritten by the passed in object.
{
"token":"abc",
"cmd":"SetUserData",
"data": "object",
"route": "route in flow",
"uid: "User ID",
"overwrite": 1,
}
Sending Messages using the Convrs API
The Convrs API provides 3 commands to send messages via the API:
SendSMSMessage can send SMS messages, SendWhatsAppTemplate can send WhatsApp Template messages and SendMessage for sending generic messages. The SendMessage command is for specific use-cases and typically should not be used.
All three commands are subject to strict throttling as all downstream message providers have strict protocols in place to limit the amount of spam. The following throttling rules are in place:
- Only 1 message can be sent to a mobile number per second
- Only 10 messages can sent in a 1 second period per token
There is scope to lift these restrictions in some specific circumstances, please contact Support for more details.
The command GetMessageDetails can provide information on a sent message, for example, if the message was delivered, seen or replied to.
Sending WhatsApp API Templates
A WhatsApp template message is a pre-approved message format that businesses can use to send messages to their customers on the WhatsApp platform. These template messages are designed to provide standardized and structured communication between businesses and their users.
WhatsApp has specific guidelines and policies in place for template messages to ensure that businesses use them appropriately and do not engage in spamming or misuse. Before sending template messages, businesses need to get their templates approved by WhatsApp.
Template messages can include text, emojis, and placeholders for dynamic content, such as the customer's name or order details. They are commonly used for sending transactional notifications, appointment reminders, shipping updates, customer support messages, and other types of structured messages. With the latest version of the WhatsApp API, marketing templates are also supported.
It's important to note that template messages are different from free-form, one-on-one messages. Template messages require prior approval and can only be sent to users who have initiated a conversation or have given some form of consent to receive messages from the business. Consent can be collected in many ways, and should be included in your privacy policy and list WhatsApp specifically.
Ensuring Your WhatsApp API number is not blocked or banned
The exact mechanisms and algorithms used by the WhatsApp API to detect and ban numbers are not publicly disclosed. However, WhatsApp employs various measures and algorithms to monitor user activity and identify patterns that indicate potential misuse or violation of their policies. Some of the factors that might be considered include:
- User Reports: WhatsApp relies on user reports to identify abusive or spammy behavior. If multiple users report a particular number or message as inappropriate, it may trigger further investigation.
- Message Volume: Unusually high message volumes from a specific number within a short period may raise red flags and indicate potential spamming or misuse.
- Content Analysis: WhatsApp may employ content analysis algorithms to detect spam, unsolicited advertising, or other policy violations in the messages being sent.
- Behavioral Analysis: The API might analyze user behavior, such as the frequency of messaging, the number of contacts, and the rate of responses, to identify suspicious or abnormal patterns.
- Compliance Monitoring: WhatsApp actively monitors API usage to ensure businesses adhere to their guidelines and policies. Violations or excessive reports related to a specific number could result in closer scrutiny and potential banning.
A key point to consider is user reporting. A common case where you can annoy customers is the time of day you send your Whatsapp template messages. Unless sending user requested content such as a OTP code, best practice is to send any WhatsApp Template message during business working hours for the users local time. Users typically are more likely to report your content if sent, for example at 2am or over the weekend
SendWhatsAppTemplate
This commands sends a WhatsApp template. The following fields are part of the object:
botID: Required, an integer, the Convrs bot Identifier.
phone: Required, an string, the international mobile phone number to send the WhatsApp template to. We use a 3rd party library to validate numbers, so several formats are supported. See below for more information.
templateName: Required, the WhatsApp template name.
language: Required, the WhatsApp template language code.
agentEmail: Optional, string. If populated, the chat will be stuck to the agent with this email address.
parameters: Optional, data structure. If the WhatsApp template has dynamic content this must be populated.
Example JSON object of sending a WhatsApp template:
{
"token":"abcd",
"cmd":"SendWhatsAppTemplate",
"botID":"3941",
"phone":"+44151999999",
"language":"en",
"templateName":"followup_inquiry_request"
}The following object will be returned:
{
"ok":1,
"cmd":"SendWhatsAppTemplate",
"phoneNumber":"+44151999999",
"countryIso2":"GB",
"uid":"3941-wa3-44151999999",
"mid":"6462d3d8c8b0b08fddc34ca8"
}The fields have the following meaning:
phoneNumber: The iso formatted of the passed in phone field.
countryIso2: The iso country code of the passed in phone field.
uid: The unique Convrs identifier for this user
mid: The unique Message identifier for this message. This ID can be used later to fetch information about the message (ie, was it delivered, read etc).
error: If an error message has occurred (ie, if “ok”: 0 ), human readable error message
whatsappErrorCode: If an error has occurred on the WhatsApp API, the specific WhatsApp error code.
whatsappErrorDesc: If an error has occurred on the WhatApp APP, a human readable description of the message code.
Example JSON object of sending a WhatsApp template with parameters:
{
"token":"abcd",
"cmd":"SendWhatsAppTemplate",
"botID":"3941",
"phone":"+44151999999",
"language":"en",
"templateName":"followup_inquiry_request",
"parameters": [ { "type": "text", "text": "David" },{ "type": "text", "text": "Simon" }],
}The parameters field contains an array of parameters that the specific WhatsApp template expects. The most common parameters is the text field, and has the following structure:
{ "type": "text", "text": "your string" }See WhatsApp documentation for more information on other types.
SendSMSMessage
This command sends a SMS message to a mobile phone number. The following fields are part of the object:
botID: Required, an integer, the Convrs bot Identifier.
phone: Required, an string, the international mobile phone number to send the WhatsApp template to. We use a 3rd party library to validate numbers, so several formats are supported - see below.
message: The text of the message you wish to send.
agentEmail: Optional, string. If populated, the chat will be stuck to the agent with this email address.
{
"token":"abcd",
"cmd":"SendSMSMessage",
"botID":"3941",
"phone":"+44151999999",
"message": "Hello world"
}
The following object will be returned:
{
"ok":1,
"cmd":"SendSMSMessage",
"phoneNumber":"+44151999999",
"countryIso2":"GB",
"uid":"3941-cms-44151999999",
"mid":"9462d3d8c8b0b48fddc34ca8"
}The fields have the following meaning:
phoneNumber: The iso formatted of the passed in phone field.
countryIso2: The iso country code of the passed in phone field.
uid: The unique Convrs identifier for this user
mid: The unique Message identifier for this message. This ID can be used later to fetch information about the message (ie, was it delivered, read etc).
error: If an error message has occurred (ie, if “ok”: 0 ), human readable error message
SendMessage
This command sends a message to a mobile phone number. This command is used when additional server side processing needs to take place. Please contact Convrs support for more information on the server side logic that can be run with this command.
The following fields are part of the object:
phone: Required, a string. The mobile number, see below for format
message: Optional, The message to send (encoded in UTF8), 2000 character limit.
route: Required, a string of the name of the route to which the message will be processed by
userdata: Optional, user data that is also send to the route
Routing
As there are several different ways to send messages to a mobile phone number (such as SMS and Whatsapp) and a route has to be specified. This route will provide the logic to ‘route’ the message to the correct downstream service provider.
The route as part of the API is simply a name, typically the business function that the route performs. The routing logic is beyond the scope of this specification and would be typically provided to users of the API.
Example
{
"token":"abc",
"cmd":"SendMessage",
"phone": "44-792-202-1411",
"route":"welcome",
"Message":"welcome to our service",
}Would return the response:
{"ok":1,"cmd":"SendMessage"}GetMessageDetails
This command retrieves information about a sent SMS or WhatsApp template message. The following fields are part of the object that needs to be sent:
mid: Required, string. The message ID returned from the SendSMSMessage or SendWhatsAppTemplate commands.
Example:
{
"token":"abc",
"cmd":"GetMessageDetails",
"mid":"6462d3d8c8b0b08fddc34ca8"
}Would return the following object:
{
"ok":1,
"cmd":"GetMessageDetails",
"uid":"3941-wa3-44151999999",
"botID":3941,
"ack: 1,
}uid: The Convrs unique identifier
botID: The Convrs bot identifier.
ack: The message acknowledgement code.
whatsappErrorCode: If an error has occurred on the WhatsApp API, the specific WhatsApp error code.
whatsappErrorDesc: If an error has occurred on the WhatApp API, a human readable description of the message code.
error: If an error has occurred when sending sms.
| Ack code | WhatsApp/SMS Ack Meaning |
|---|---|
| -2 | User does not exist on WhatsApp (WhatsApp only) |
| -1 | An error (WhatsApp and SMS) |
| 0 | Message is at the server (WhatsApp) |
| 1 | Message has been sent (WhatsApp and SMS) |
| 2 | Message has been delivered to the users device (WhatsApp and SMS) |
| 3 | Message has been seen by the user (WhatsApp only) |
Valid Phone Number formats
The phone field in the above commands suppors several different formats. All must include an international prefix and the number must be a mobile number. The following are examples of valid mobile numbers:
+447922029419
447922021419
+44 792 202 1419
44-792-202-1419
An error message will be returned if the number isn’t valid or not a mobile number.