The editing software's API

Which requests the editing software supports and how to carry them out

• 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

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.

• callback

• whatsapp_callback

• message

• whatsapp_message

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
e-mail	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
email	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