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. Results are limited to the latest 1000 conversations.

GetConversationsFlat supports two main use cases:

1. Allowing the caller to poll periodically to get the latest updates
2. 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:

1. 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.
    
2. Message Volume: Unusually high message volumes from a specific number within a short period may raise red flags and indicate potential spamming or misuse.
    
3. Content Analysis: WhatsApp may employ content analysis algorithms to detect spam, unsolicited advertising, or other policy violations in the messages being sent.
    
4. Behavioural Analysis: The API might analyze user behaviour, such as the frequency of messaging, the number of contacts, and the rate of responses, to identify suspicious or abnormal patterns.
    
5. 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.

It is extremely important to start slowly, especially with new numbers registered with the WhatsApp API, this is to allow the number to increase the quality and allow more messages to be sent. When running  automatic campaigns, especially with new templates the following is a good guide:

• Use a small subset of your users to test the receptiveness of your audience to the WhatsApp Template
• Use a small pause between each message, especially for large campaigns as WhatsApp can dynamically pause the template if little to no user interaction has happened

Check the error codes retuned from the API, for example, 

if (obj.ok==0) { //message failed
  if (obj.errorCode == 3002) //WhatsApp Error
     print obj.whatsappErrorCode;
     print obj.whatsappErrorDesc;
     exit;
  }
}

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. 

webhookURL: Optional, if populated we will call your webhook with status updates

webhookPayload: Optional, if populated we will pass this object back to your webhook. 

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 API, 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. 

WebHook Responses 

If the webhookURL is populated we will post a JSON object to your webhook. These events are the basic WhatsApp Ack events (sent, delivered, read, error) and would contain the following information:

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

The timestamp is in UTC and when we received the event from WhatsApp. NOTE. Due to the way events are delivered to us it is possible for events to be received out of order. Errors will return a -1 for the ack, and possibly have the following two fields populated:

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. 

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. 

API Error Codes

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.