- How to get messages on Webhook URL that is specified in the project’s settings
- How to use a universal webhook
- How to launch the bot
- How to work with messages
- How to distribute the clients
- How to work with variables
- How to get client_id
- What other possibilities there are
The requests are carried out with the method POST on URL i.e. https://chatter.mavibot.ai/api/{api\\_key}/{action}
Where it’s located: api_key is the key to accessing API which is obtained in the project’s settings:
You can get the access key by using the variable #{api_key}. It holds the relevant generated key. Don’t forget to generate one before using it.
When copying the url of the query from this page a space is put in that needs to be deleted when calling
An example of copying the link the wrong way: https://chatter.mavibot.ai/api/callback 
The space after .pro is easy to not notice but if it’s left in place the query won’t work
When sending the request with the GET method, don’t use prohibited words. Look into the right formation of GET requests
How to get messages on Webhook URL that is specified in the project’s settings
Every incoming or outcoming message comes with the following json POST requests:
{
'id': the identifier of the message in the system,
'client': {
'id': the identifier of the client in the system,
'recepient': the identifier of the client in the messenger,
'client_type': the messenger’s type,
'name': the client’s name,
'avatar': the client’s avatar,
'created_at': the date when the client was created,
'tag': the subscription key,
'group': the bot to which the client is tied to,
},
'message': the message text,
'attachments': the array of links to files,
'message_id': the id of the block from which the message was sent from,
'project_id': the project’s id,
'is_input': 1 if the message is from a client, 0 if it’s from the bot,
'delivered': 1 if the message is sent successfully, 0 if there was an error,,
'error_message': the message explaining the error
}
If the request came back with an error it won’t be resent. If the server came back with an error then the notifications will come through despite this.
How to use a universal webhook
These methods now can be launched with both the POST and the GET request.
Previously, the parameters (with which the clients’ methods were launched, i.e. client_id) were very strictly written in our methods and it would implement some restrictions when using them with the third-party services.
Now you can point out in which parameter of the request Mavibot will look for the identifier of the user: for this, a parameter with the prefix value_ is used, like value_user_id and value_group_id.
Also the method for sending the callback callback can be launched by transmitting an email (client_email) and a client’s phone number (client_phone).
Methods callback and whatsapp_callback aren’t tied to the parameter’s names. You can specify which parameter will hold the client’s phone number, email and id.
It’s useful when you’re setting up the webhook’s reception through another site.
To specify which variable holds client_id you need to transfer value_client_id and mention the name of the parameter with this value in it
To specify which variable holds phone you need to transfer value_phone and mention the name of the parameter with this value in it
To specify which variable holds email you need to transfer value_email and mention the name of the parameter with this value in it
To specify which variable holds user_id you need to transfer value_user_id and mention the name of the parameter with this value in it
To specify which variable holds group_id you need to transfer value_group_id and mention the name of the parameter with this value in it
Example:
Type in the address value_client_id = my_client
https://chatter.mavibot.ai/api/d3f31dabef80ddeb73d43938b4ef8bb0/callback?value_client_id=my_client
{"my_client":49177759, "message":"Hello world"}
The query will be the equivalent to the query below:
https://chatter.mavibot.ai/api/d3f31dabef80ddeb73d43938b4ef8bb0/callback
{"client_id":49177759, "message":"Hello world"}
As you can see, the name of the parameter that holds the name is differentiated by the prefix value_
How to launch the bot
The bot’s launch
POST https://chatter.mavibot.ai/api/<api_key>/callback
The method can be used for launching the workflow for the client or for approving the action on a third-party service. This message won’t be visible for the client.
Additionally transferred parameters are saved in the variables.
The method for sending the callback can now be turned on by sharing an email (client_email) or the client’s phone number (client_phone)
Path Parameters
| Name | Type | Description |
|---|---|---|
| api_key | string | access token |
Request Body
| Name | Type | Description |
|---|---|---|
| client_phone | string | phone number using which the client is found |
| client_email | string | email using which the client is found |
| client_id | string | client’s id in the editor |
| message | string | the message text |
**200: OK **
import requests
import json
params = {"message": "some_text", "client_id": "25554"}
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/callback'
requests.post(url, json=params)
Launching the bot through the number on WhatsApp
POST https://chatter.mavibot.ai/api/<api_key>/whatsapp_callback
This method launches the bot in WhatsApp after the client registers through the site or after they leave a request with their phone number
Additionally transferred parameters are saved to the variables
Path Parameters
| Name | Type | Description |
|---|---|---|
| api_key | string | access token |
Request Body
| Name | Type | Description |
|---|---|---|
| name | string | the client’s name |
| message | string | the message text |
| phone | string | the client's phone number |
| bot_id | string | the bot's id |
**200: OK **
{
// Response
}
Bot launch through Telegram id
POST https://chatter.mavibot.ai/api/<api_key>/tg_callback
The method can be used for launching the workflow or confirming actions on a third-party site. This message won't be visible to the client.
Additionally transferred parameters are saved to the variables
Path Parameters
| Name | Type | Description |
|---|---|---|
| api_key | string | access token |
Request Body
| Name | Type | Description |
|---|---|---|
| message | string | the message text |
| user_id | string | the user's id in Telegram |
| group_id | string | the bot's name (must end in bot) |
**200: OK **
{
// Response
}
How to work with messages
Params for sending messages
attachment_type can take these values: image, video, link, file, audio
When sending attachments the parameter message isn’t mandatory
buttons identifies the buttons that will be attached to the message. The buttons’ format is comparable to the button’s advanced settings. Two variants of the buttons’ transmition are possible: one with the tooltip in messengers without buttons and one without it
Here’s an example of the buttons parameter:
"buttons": {"hint": "This text will be shown in Whatsapp",
"buttons": [
{"type": "reply",
"text": "What services we can provide",
"line": 0, "index_in_line": 0},
{"type": "reply",
"text": "Payment info",
"line": 0,
"index_in_line": 1},
{"type": "reply",
"text": "Our contact info",
"line": 1, "index_in_line": 0},
{"type": "reply",
"text": "Leave an application",
"line": 1, "index_in_line": 1}
]
}
Sending the message to the client
POST https://chatter.mavibot.ai/api/<api_key>/message
This method can be used for sending messages with notifications. The parameter message is mandatory if you’re not sending a file. If you are, then the text isn’t needed
Path Parameters
| Name | Type | Description |
|---|---|---|
| api_key | string | the access key |
Request Body
| Name | Type | Description |
|---|---|---|
| message_id | string | the sending block's number |
| message | string | the message text |
| client_id | string | the client's id in the editor |
| attachment_type | string | the file display type |
| attachment_url | string | the file's URL |
| buttons | object | buttons |
**200: OK **
import requests
import json
params = {"message": "some_text", "client_id": "25554"}
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/message'
requests.post(url, json=params)
Sending messages in WhatsApp
POST https://chatter.mavibot.ai/api/<api_key>/whatsapp_message
Allows sending a message from the name of the connected bot to the mentioned number whatsapp_bot_id has to be taken from the “Messengers and chats” section. Each connected WhatsApp page gets a unique identification
Path Parameters
| Name | Type | Description |
|---|---|---|
| api_key | string | the access key |
Request Body
| Name | Type | Description |
|---|---|---|
| message_id | string | the sending block's number |
| whatsapp_bot_id | number | the WhatsApp bot that sends the message |
| attachment_url | string | the file's url |
| attachment_type | string | the file display type |
| message | string | the message text |
| phone | string | the recipient's phone number |
**200: OK **
import requests
import json
params = {"message": "some_text", "phone": "79875146788"}
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/whatsapp_message'
requests.post(url, json=params)
Sending messages in bulk
POST https://chatter.mavibot.ai/api/<api_key>/broadcast
The method allows message distribution. If the param clients isn’t mentioned, the broadcast will be sent out to all users. It’s necessary to either send a file or a text
Path Parameters
| Name | Type | Description |
|---|---|---|
| api_key | string | the access key |
Request Body
| Name | Type | Description |
|---|---|---|
| message_id | string | the sending block's number |
| list | string | the list of recipients' numbers |
| shift | string | the amount of seconds between messages. 0.2 by default |
| message | string | the message text |
| clients | array | the recipients' ids |
| attachment_type | string | the file display type |
| attachment_url | string | the file's URL |
| buttons | string | buttons |
**200: OK **
{import requests
import json
params = {"message": "some_text", "clients": ["5", "58", "110"]}
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/broadcast'
requests.post(url, json=params)
Getting the message history
GET https://chatter.mavibot.ai/api/<api_key>/get_history?client_id=
Getting the message history. You can get the client_id param HERE
Path Parameters
| Name | Type | Description |
|---|---|---|
| api_key | string | the access key |
Query Parameters
| Name | Type | Description |
|---|---|---|
| client_id | string | the client's id |
**200: OK **
{
"status": "success",
"result": [
{
"id": 104500,
"answered": true,
"client_replica": false,
"message_id": 390,
"message_from_outside": 0,
"created_at": 1587895014,
"text": "CouCou",
"attachments": {
},
"delivered": true,
"error_message": "true"
},
]
}
Clearing the message history
GET https://chatter.mavibot.ai/api/<api_key>/clear_history?client_id=
Path Parameters
| Name | Type | Description |
|---|---|---|
| api_key | string | the access key |
Query Parameters
| Name | Type | Description |
|---|---|---|
| client_id | string | the client's id |
**200: OK **
import requests
import json
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/clear_history?client_id=85856'
requests.get(url)
How to distribute the clients
Assigning a client to an employee
GET https://chatter.mavibot.ai/api/<api_key>/assign_to_user
The method allows assigning a client to an employee. The email parameter is optional. If the email isn’t provided, it will be distributed through the system’s algorithm
Path Parameters
| Name | Type | Description |
|---|---|---|
| api_key | string | the access key |
Query Parameters
| Name | Type | Description |
|---|---|---|
| client_id | String | the client's id |
| String | the worker's email (optional) |
**200: OK **
import requests
import json
params = {"message": "some_text", "clients": ["5", "58", "110"]}
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/broadcast'
requests.post(url, json=params)
Loading clients into the system
GET https://chatter.mavibot.ai/api/<api_key>/load_clients
The method allows loading clients into the system. When uploading WhatsApp clients you can transfer the number freely with the @s.whatsapp.net at the end or without it.
You can get the group id (group_id) here through /api/<api_key>/connected_channels
(if client_type=13 (telephony) then group_id=””)
You can see the type of messenger the client came from (client_type)
Ex.: [{"platform_id":"79875555555","group_id":34810,"client_type":6}]
Path Parameters
| Name | Type | Description |
|---|---|---|
| api_key | string | the access key |
Request Body
| Name | Type | Description |
|---|---|---|
| platform_id | String | the phone number |
| group_id | String | the group id |
| client_type | String | the type of messenger the client came from |
**200: OK **
import requests
import json
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/load_clients'
params = [{ "platform_id": 274827917, "group_id": 169166236, "client_type":0},
{"platform_id":"[email protected]", "group_id": "1hwF7lwEjv4SKYIGFhQnBw==", "client_type": 6}]
requests.post(url, json=params)
# in case of success the function returns each element its id and addition status
# answer example
# {"status":"success","items":[{"platform_id":"[email protected]","group_id":"5kqchxwyvdvFZOsp80q2qw==","client_type":6,"status":"success","id":1469409}]}
Adding clients to the list
POST https://chatter.mavibot.ai/api/<api_key>/add_to_list
Path Parameters
| Name | Type | Description |
|---|---|---|
| api_key | string | the access key |
Request Body
| Name | Type | Description |
|---|---|---|
| list_id | integer | the list's number |
| clients | array | the clients' numbers' array |
**200: OK **
{
// Response
}
Removing clients from the list
POST https://chatter.mavibot.ai/api/<api_key>/remove_from_list
Path Parameters
| Name | Type | Description |
|---|---|---|
| api_key | string | the access key |
Request Body
| Name | Type | Description |
|---|---|---|
| list_id | integer | the list's number |
| clients | array | the clients' numbers' array |
**200: OK **
{
// Response
}
Getting the clients list
POST https://chatter.mavibot.ai/api/<api_key>/get_clients
Path Parameters
| Name | Type | Description |
|---|---|---|
| api_key | string | the access key |
Query Parameters
| Name | Type | Description |
|---|---|---|
| offset | string | offset from the first element |
| limit | integer | the amount of elements in the answer. 500 by default, max. 500 |
| list | string | the list's number |
200: OK Returns the elements’ status and array
{
"status":"success",
"clients":[{
"id":44483,
"platform_id":"146467928",
"client_type":0,
"name":null,
"avatar":null,
"message_id":null,
"project_id":1,
"created_at":1588248599,
"updated_at":1588248599,
"custom_answer":null,
"tag":null,
"group":"143414131",
"operator_start_dialog":null
}
]
}
Getting the subscribers list in any messenger
POST https://chatter.mavibot.ai/api/<api_key>/subscribers
Getting the information on the clients in the chosen messenger
Path Parameters
| Name | Type | Description |
|---|---|---|
| api_key | string | the access key |
Query Parameters
| Name | Type | Description |
|---|---|---|
| page | integer | |
| tag | string | the tag that was mentioned on t subscription page |
| group | integer | the id of the group the subscriber is tied to |
| date_from | integer | timestamp of the date after they subscribed |
| date_to | integer | timestamp of the date they subscribed until |
| client_type | integer | the id of the messenger to which you need to sub list. if you change nothing all clients come up |
**200: OK **
[
{
"id": 44886,
"tag": null,
"created_at": 1609867984,
"name": "John Smith",
"tg_id": "146467928",
"group": "155824294",
"variables": null
},
{
"id": 44889,
"tag": null,
"created_at": 1609867984,
"name": "Jane Austen",
"tg_id": "1609867984",
"group": "155824294",
"variables": {
"utm_source": "some_value"
}
}
]
Permission to delete clients
POST ``https://chatter.mavibot.ai/api/<api_key>/get_clients
Access permission when generating the key: “Permission to delete clients”
Parameters
Path
api key* — access token
Body
client_ids — list of client IDs to be deleted. Maximum 500. Example: [199571, 199707, 1935722]
How to work with variables
Attributing variables
POST https://chatter.mavibot.ai/api/<api_key>/save_variables
Allows saving variables in the application and in the client.
The request of attributing variables by default adds to transaction variables.
If you need to change the variables in the profile you need to add the prefix client.
Ex. for mobile: client.phone
The param clients allows attributing variables in bulk
Ex.: {"client_id":49177759, "variables":
{"client.phone":"1234567890"}}
Path Parameters
| Name | Type | Description |
|---|---|---|
| api_key | string | the access key |
Request Body
| Name | Type | Description |
|---|---|---|
| clients | array | clients id array for assigning variables |
| client_id | string | client's id |
| variables | object | variable hash (key value) |
**200: OK **
import requests
import json
params = {"client_id": "25554", "variables": {"var_name": "var_value"}}
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/save_variables'
requests.post(url, json=params)
Obtaining variables
GET https://chatter.mavibot.ai/api/<api_key>/get_variables?client_id=
Path Parameters
| Name | Type | Description |
|---|---|---|
| api_key | string | access token |
Query Parameters
| Name | Type | Description |
|---|---|---|
| client_id | string | client id |
**200: OK **
import requests
import json
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/get_variables?client_id=85856'
requests.get(url)
How to get client_id
Getting client_id by the platform_id value
POST https://chatter.mavibot.ai/api/<api_key>/find_client_id_by_platform_id
The method returns the client id for executing requests to the API
Example of parameters: {"platform_ids": ["571830542", "256865200"]}
Path Parameters
| Name | Type | Description |
|---|---|---|
| string | access key |
Request Body
| Name | Type | Description |
|---|---|---|
| platform_ids | string | ids array in the messenger |
**200: OK **
[{
"id":15099119,
"tag":null,
"created_at":1618815253,
"name":"Oscar Wilde",
"avatar":"https:\\/\\/files.salebot.pro\\/uploads\\/avatars\\/256865200.jpg",
"platform_id":"2568652",
"group":"Salebotpro_bot",
"variables":{"tg_username":"@wildeo"}},
{"id":21087377,
"tag":null,
"created_at":1626275893,
"name":"Freddie Mercury",
"avatar":"https:\\/\\/files.salebot.pro\\/uploads\\/avatars\\/571830542.jpg",
"platform_id":"571830542",
"group":"Salebotpro_bot",
"variables":{"tg_username":"@freddieisqueen"}
}]
How to get client id on Online chat
GET https://chatter.mavibot.ai/api/<api_key>/online_chat_client_id?recipient=
This method allows to integrate the site and chatbot, i.e. if a person went on the page with the special offer, you can send out instantly a message about the offer in the chat
Path Parameters
| Name | Type | Description |
|---|---|---|
| api_key | string | access token |
Query Parameters
| Name | Type | Description |
|---|---|---|
| tag | string | customer tag |
| name | string | the client's name |
| recipient | string | the dialogue id on the site |
**200: OK **
{ "client_id": 36553 }
Where do you get the recipient? On the site that carries online chat “Mavibot.ai” you need to get the feature SaleBotPro.recipient_id with the help of JS.
How to get client id with the WhatsApp number
GET https://chatter.mavibot.ai/api/<api_key>/whatsapp_client_id?phone=
The method gives back the client id for executing requests to the API if you know the client’s phone number in WhatsApp.
If there is no such client with this number, you’ll get a 404.
Path Parameters
| Name | Type | Description |
|---|---|---|
| api_key | string | access token |
Query Parameters
| Name | Type | Description |
|---|---|---|
| phone | string | the phone number |
**200: OK **
{
// Response
}
Getting client id with the phone number
GET https://chatter.mavibot.ai/api/<api_key>/find_client_id_by_phone?phone=
The method gives back the client id for executing requests to the API.
The search happens through WhatsApp clients, as well as through variables.
Path Parameters
| Name | Type | Description |
|---|---|---|
| api_key | string | access token |
Query Parameters
| Name | Type | Description |
|---|---|---|
| phone | string | the phone number |
**200: OK **
{
// Response
}
Getting client id through email
GET https://chatter.mavibot.ai/api/<api_key>/find_client_id_by_email?email=
The method gives back the client id for executing requests to the API. The search happens through variables.
Path Parameters
| Name | Type | Description |
|---|---|---|
| api_key | string | access token |
Query Parameters
| Name | Type | Description |
|---|---|---|
| string | email for search |
**200: OK **
{
// Response
}
Getting client id by the variable value
GET https://chatter.mavibot.ai/api/<api_key>/find_client_id_by_var?var=&val=
The method gives back the client id for executing requests to the API
Path Parameters
| Name | Type | Description |
|---|---|---|
| api_key | string | access token |
Query Parameters
| Name | Type | Description |
|---|---|---|
| var | string | the name of the variable the search will go on through |
| val | string | the variable value |
**200: OK **
{
// Response
}
What other possibilities there are
Moving the transaction into the MavibotCRM state
POST https://chatter.mavibot.ai/api/<api_key>/set_order_state
The transaction number can be obtained in the MavibotCRM workflow’s editing window.
Path Parameters
| Name | Type | Description |
|---|---|---|
| api_key | string | the access key |
Request Body
| Name | Type | Description |
|---|---|---|
| client_id | string | client's id |
| state_id | string | the state number to transfer the client’s transaction into |
**200: OK **
{
// Response
}
Checking if the person follows the Instagram account
GET https://chatter.mavibot.ai/api/<api_key>/check_insta_subscription
Can be called with both the POST method and the GET method
Path Parameters
| Name | Type | Description |
|---|---|---|
| api_key | string | the access key |
Request Body
| Name | Type | Description |
|---|---|---|
| user_name | string | the username of the client you want to check |
| login | string | the login of the bot that’s being checked |
200: OK The field is_follower is the one that holds the info on either or not the person follows it
{
"username": "beyonce",
"account_id": "1463220603",
"avatar": "https://instagram.fhel6-1.fna.fbcdn.net/v/t51.2885-19/1060168..",
"real_name": "Beyonce",
"is_follower": true,
"status": 200
}
Checking if the phone number carries WhatsApp
GET https://chatter.mavibot.ai/api/<api_key>/check_whatsapp
To use the method you HAVE to have connected WhatsApp and Mavibot
Can be called with both the POST method and the GET method
The phone number can be transferred in any format
Path Parameters
| Name | Type | Description |
|---|---|---|
| api_key | string | access token |
Request Body
| Name | Type | Description |
|---|---|---|
| phone | string | the phone number |
**200: OK **
{
// Response
}
Getting the list of messengers connected to the project (including group_id)
GET https://chatter.mavibot.ai/api/<api_key>/connected_channels
The function returns the parameter group_id to each messenger and it is the one that needs to be transferred when loading the clients
The field status also returns for WhatsApp, and it holds a value of:
NOT_STARTED = 0
STARTED = 1
ASLEEP = 2
STOPPED = 3
Path Parameters
| Name | Type | Description |
|---|---|---|
| api_key | string | access token |
**200: OK **
{'project_id': 1,
'viber': [{
'id': 14,
'uri': 'salebotstage',
'name': 'salebotstage',
'enabled': true,
'group_id': 11}],
'facebook': [],
'telegram': [{
'id': 23,
'short_name': 'bulls_vs_bears_bot',
'name': 'bulls_vs_bears_bot',
'enabled': true,
'group_id': 'bulls_vs_bears_bot'}],
'whatsapp': []
}
Getting the list of blocks from the bot’s schema
GET https://chatter.mavibot.ai/api/<api_key>/get_messages
Path Parameters
| Name | Type | Description |
|---|---|---|
| api_key | string | access token |
**200: OK **
{
// Response
}
If you need additional methods, please contact customer support