API builder

2026-06-29

On this page

Some API request functions can be run in the Calculator.

Requests are sent via the POST or GET method to a URL in the following format:

https://chatter.mavibot.ai/api/{api\\_key}/{action}

Where:

api_key — the API access key generated in the project settings.

To use the token in a URL request, you first need to generate an API key.

Instructions for doing this are provided in the "Generating an API Key" section. ссылка

When copying a URL from this page, a space may appear and must be removed.

Example of an incorrect link:
https://chatter.mavibot.pro /api/callback

If the space after .pro remains, the request won’t work.

Do not use prohibited characters when sending a GET request.

Make sure you understand the correct format for GET requests.

How to generate an API key

The old API key generation feature still works as before but is not available for new projects.

If your project already has API keys generated without the access settings described in this section, those existing API keys will continue to function normally.

If you need to generate new keys, use the updated settings.

To generate an API key, go to the project settings:

Next, go to the "Integrations" section:

You’ll find the “Add API key” button in the "Integrations" section:

After clicking the button, a modal window will open with access settings and API key generation options:

Next, you need to select the access permissions for the API key:

The API function will work according to the access permissions you select.

Please note!

The API function depends on the access permissions you set: if you generate an API key with read-only access to client information and then use it to send a message to a client or modify their variables, the API request will fail.

The required permission for each API request is specified in the API request card:

Next, enter a name for the API key:

Generate the API key by clicking the "Generate" button:

После чего нажмите "Готово" и ключ api добавится в раздел:

You can add as many API keys as needed, assigning different access permissions to each.

Next, you need to set a primary project key. This allows you to use the key in a request URL with the #{api_key} placeholder.

To do this, click the "{+}" button to the right of the desired API key:

A label will then appear next to the key, indicating that it is the primary project key.

You can access the primary project key via api_key: simply generate the required key, set its permissions, and designate it as the primary project key. Then, in the Calculator, use the request URL with the #{api_key} placeholder, which will contain the value of the primary project key.

Any other generated keys with access settings will be considered secondary keys. In the request URL, you can use their value instead of #{api_key}. To do this, copy the value of the secondary key:

and paste it into the request URL in place of #{api_key}:

An API key generated using the old method is set as the primary project key by default and has full permissions.

Note!

If you delete the key set as the primary project key, you will need to manually designate a new key as the primary.

Please note!

If you have API keys generated using the old method, they will continue to work normally. It is not possible to generate new API keys of the old type.

How to receive messages at the Webhook URL specified in the project settings

Project settings

Each incoming or outgoing message will be sent as the following JSON POST request:

{
    "id": "message ID in the system",
    "client": {
        "id": "client ID in the system",
        "recepient": "client ID in the messenger",
        "client_type": "type of messenger",
        "name": "client's name",
        "avatar": "client's avatar",
        "created_at": "client creation date",
        "tag": "subscription key",
        "group": "bot the client is linked to"
    },
    "message": "message text",
    "attachments": "array containing file links or dictionaries of file links",
    "message_id": "ID of the block from which the message was sent",
    "project_id": "project ID",
    "is_input": "1 if the message is from the client, 0 if from the bot",
    "delivered": "1 if the message was sent successfully, 0 if there was an error",
    "error_message": "text of the message delivery error"
}

If a request returns an error, it will not be retried. Even if the server returns errors, notifications will continue to be sent.

How to create a JSON request

Go to the settings of the block where the data will be recorded in the table.

Add an API Request section.
Select POST-JSON as the request type.
Then proceed to fill in the request fields:

Request URL — the path to the function to be called. In the documentation, this is always shown on the first line next to the request type:

Saved values — a list of response parameters with the variable names where the results should be stored, in the following format:

request_parameter -> your_variable

If the response contains parameters with a complex structure, parse them as follows:

"cell_number":{"row":4,"col":2}

cell_number|row ->String;
cell_number|col -> Column

Request headers — fill in if needed. This usually includes the data format and/or access token.

JSON parameters — the request body, where you specify the data parameters in JSON format. Example:

{"client_id": "#{recipient_id_in_builder}", "message":"Hello!"}

To understand the structure of the response, write #{custom_answer} in the Message field to output the variable’s value.

Next, the documentation lists the allowed parameters in the "Body" section:

How to use a universal webhook

The listed methods can now be executed as either POST or GET requests.

callback
whatsapp_callback
message
whatsapp_message

Previously, our methods had fixed parameters (such as client_id and fb_id) for triggering subscriber actions, which imposed certain limitations when integrating with third-party services.

Now you can specify which request parameter SaleBot should use to find the user ID. Use a parameter with the value_ prefix, for example, value_user_id or value_group_id.

Additionally, the callback sending method can now be triggered using the client’s email (client_email) or phone number (client_phone).

The callback, fb_callback, and whatsapp_callback methods are not tied to specific parameter names. You can specify which parameter contains the client’s phone number, email, or ID.

This is useful when setting up webhook reception from a website.

To specify which variable contains the client_id, use the value_client_id parameter and provide the name of the parameter holding this value.

To specify which variable contains the phone number, use value_phone.

To specify which variable contains the email, use value_email.

To specify which variable contains the user_id, use value_user_id.

To specify which variable contains the group_id, use value_group_id.

To specify the variable containing the message itself in the webhook, use value_message (passed in the same way as the other parameters).

Example:

In the address, specify value_client_id = my_client.

https://chatter.mavibot.ai/api/d3f31dabef80ddeb73d43938b4ef8bb0/callback?value_client_id=my_client
{"my_client":49177759, "message":"Hello world"}

The request will be equivalent to the one below:

https://chatter.mavibot.pro/api/d3f31dabef80ddeb73d43938b4ef8bb0/callback
{"client_id":49177759, "message":"Hello world"}

As you can see, the parameter name containing the value is prefixed with value_.

Please note!

Some events generate system notifications within the project.

For example, there are system notifications with a message field that are not empty but contain no client text.

At the same time, the project may also generate message hooks with specific content, such as "message: new_chat_member".

Therefore, it’s important to check the content: it will either be a system notification or a hook for a specific event.

How to start the bot

Start the bot

URL запроса: https://chatter.mavibot.ai/api/#{api\\_key}/callback

This method can be used to trigger a funnel for a client or confirm an action on an external resource. The client will not see this message.

Please note: any parameters you additionally pass will be saved in variable

The callback method can now also be triggered using the client’s email (client_email) or phone number (client_phone).

Access permission when generating a key: "Permission to modify/delete client information".

Path

api key* - access token

Body

client_phone - phone number used to look up the client

client_email - email used to look up the client

client_id - client ID in the builder

message - message text

resume_bot - True (optional parameter). If the bot is paused, this is used to unpause it.

Example: resume_bot = True

time_shift - number. If specified, the message will be sent after the given number of seconds from the current time.

send_time - date and time in the format "%Y-%m-%d %H:%M:%S" (e.g., "2024-10-16 13:15:59"). This sets the date and time for sending the message. If both time_shift and send_time are specified, time_shift will take precedence.

import requests
import json

params = {"message": "some_text", "client_id": "25554"}
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.salebot.pro/api/{token}/callback'
requests.post(url, json=params)

Starting the bot using a WhatsApp number

URL request: https://chatter.mavibot.ai/api/\\<api_key>/whatsapp_callback

This method can trigger the WhatsApp bot after a client registers on the website or submits a request with their phone number.

Please note: any parameters you additionally pass will be saved in variable

Access permission when generating a key: "Permission to modify or delete client information".

Path

api key* - access token

Body

name - client name
message - message text
phone - client phone number
bot_id - bot ID
resume_bot - True (optional parameter). If the bot is paused, use this to resume it. Example: resume_bot = True

time_shift - number. If specified, the message will be sent after the given number of seconds from the current time.

Starting the bot using a Telegram ID

URL request: https://chatter.mavibot.pro/api/#{api\\_key}/tg\\_callback

This method can be used to trigger a funnel for a client or confirm an action on an external website. The client will not see this message.

Please note: any parameters you additionally pass will be saved in variables.

Access permission when generating a key: "Permission to modify or delete client information".

Path

api key* - access token

Body

message - message text
user_id - Telegram user ID
group_id - bot name (ended as bot)
resume_bot - True (optional parameter). If the bot is paused, use this to resume it. Example: resume_bot = True

time_shift - number. If specified, the message will be sent after the given number of seconds from the current time.

Sending callback messages to a list of clients by platform_id

URL request: https://chatter.mavibot.ai/api/#{api\\_key}/send\\_callback\\_by\\_platform\\_id

When clients with a platform_id from the list are found in the project, a callback will be sent with the text from the callback_text field.
\ Limit: 1 request = maximum 300 sends

Example of request parameters:
{"platform_ids":[407184121, "79609879898", "2rwewefw"], "callback_text": "test_callback"}

Access permission when generating a key: "Permission to modify or delete client information".

Path

api key* - access token

Body

platform_ids - List of client IDs in the messenger
callback_text - callback text
group_id - bot ID

time_shift - number. If specified, the message will be sent after the given number of seconds from the current time.

Sending a callback message to a client by email

URL request: https://chatter.mavibot.ai/api/#{api\\_key}/email\\_callback

This method can trigger the email bot after a client registers on the website or submits a request with their email. The method will locate the client’s email or create it if not found.

Access permission when generating a key: "Permission to modify or delete client information".

Please note: any parameters you additionally pass will be saved in variable

Path

api key* - access token

Body

name - client name
message - message text
email - email address
email_id_bot - bot email address
resume_bot - True (optional parameter).

If the bot is paused, use this to resume it. Example: resume_bot = True

time_shift - number. If specified, the message will be sent after the given number of seconds from the current time.

How to work with messages

Message sending parameters

attachment_type — can be: image, video, link, file, or audio.

When sending an attachment, the message parameter is optional.

buttons — defines the buttons to be attached to the message. The button format matches the advanced button settings.

Buttons can be passed in two ways: with a hint for messengers that don’t support buttons, or without it.

Example of the buttons parameter:

"buttons": {
  "hint": "This text will be displayed in WhatsApp",
  "buttons": [
    {
      "type": "reply",
      "text": "Tell me about the services",
      "line": 0,
      "index_in_line": 0
    },
    {
      "type": "reply",
      "text": "Service prices",
      "line": 0,
      "index_in_line": 1
    },
    {
      "type": "reply",
      "text": "Contacts",
      "line": 1,
      "index_in_line": 0
    },
    {
      "type": "reply",
      "text": "Submit a request",
      "line": 1,
      "index_in_line": 1
    }
  ]
}

Sending a message to a client

URL запроса: https://chatter.mavibot.ai/api/#{api\\_key}/message

This method can be used to send notification messages. The message parameter is required unless you are sending a file. If you are sending a file, the text is optional.

Access permission when generating a key: "Permission to modify or delete client information".

Path

api key* - access token

Body

message_id - block number for sending
message - message text
client_id - client ID in the builder
attachment_type - file display type. Required if attachment_url is provided.
attachment_url - file URL
buttons - buttons

time_shift - number. If specified, the message will be sent after the given number of seconds from the current time.

import requests
import json

# Sending a text message
params = {"message": "some_text", "client_id": "25554"}
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/message'
requests.post(url, json=params)

# Sending an attachment
params = {
    "message": "some message",
    "client_id": "1234565",
    "attachment_type": "video/image/file",
    "attachment_url": "https://qwreqw"
}
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/message'
requests.post(url, json=params)

# In 'attachment_type', specify either 'video', 'image', or 'file'
# depending on the type of attachment: video, image, or document.

Sending a message in WhatsApp

URL запроса: https://chatter.mavibot.pro/api/\\<api_key>/whatsapp_message

Allows you to send a message on behalf of the connected bot to the specified number. The whatsapp_bot_id must be taken from the "Messengers and chats" section. Each connected WhatsApp account is assigned a unique identifier by the builder.

Access permission when generating a key: "Permission to modify or delete client information".

Path

api key* - access token

Body

message_id - block number for sending
whatsapp_bot_id - WhatsApp bot ID from which the message should be sent
attachment_url - file URL
attachment_type - file display type. Required if attachment_url is provided.
message - message text
phone - recipient phone number

time_shift - number. If specified, the message will be sent after the given number of seconds from the current time.

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)

Bulk message sending

URL request: https://chatter.mavibot.ai/api/#{api\\_key}/broadcast

This method allows you to start a broadcast.

You can use one of the following mutually exclusive options:

list parameter — the broadcast will be sent to the specified list of clients.
clients parameter — the broadcast will be sent to an array of client IDs.
platform_ids and group_id parameters — the broadcast will be sent to an array of platform_ids (messenger IDs) for the specified bot (group_id).
If none of the above parameters are provided, the broadcast will not be sent.

Required parameters: message (and/or attachment_type and attachment_url) or message_id.

Access permission when generating a key: "Permission to modify or delete client information".

Path

api key* - access token

Body

list - list number to which the broadcast should be sent

clients - client IDs in the builder

message - message text

platform_ids - recipient IDs in the messenger. Must be used together with the required group_id parameter

group_id - required only when using platform_ids. Ignored with other options. Specifies the bot for sending to the given platform_ids

attachment_url - file URL

attachment_type - file display type. Required if attachment_url is provided.

buttons - buttons

message_id - block number for sending

shift — number of seconds between messages. The default is 0.2.

time_shift - number. If specified, the message will be sent after the given number of seconds from the current time.

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)

Retrieving message history

URL request: https://chatter.mavibot.ai/api/#{api\\_key}/get\\_history?client\\_id=

The client_id parameter can be obtained here. ссылка

Access permission when generating the key: "Permission to read client information".

Path

api key* - access token

Body

client_id - client ID

limit - number of items in the response. Default: 2000, maximum: 2000

start_date - start date of the selection period (required if stop_date is specified), format: dd.mm.yyyy

stop_date - end date of the selection period (required if start_date is specified), format: dd.mm.yyyy

{
  "status": "success",
  "result": [
    {
      "id": 104500,
      "answered": true,
      "client_replica": false,
      "message_id": 390,
      "message_from_outside": 0,
      "created_at": 1587895014,
      "text": "Meow meow",
      "attachments": {
        
      },
      "delivered": true,
      "error_message": "true",
      "manager_id": 12486,
      "manager_email": "[email protected]"
    },
  ]
}

Clear message history

URL запроса: https://chatter.mavibot.ai/api/#{api\\_key}/clear\\_history?client\\_id=

Deletes chat history

Access permission when generating a key: "Permission to modify/delete client information".

Path

api key* - access token

Body

client_id - client ID

import requests
import json


token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/clear_history?client_id=85856'
requests.get(url)

How to assign clients

Assigning a client to an employee

URL request: https://chatter.mavibot.ai/api/#{api\\_key}/assign\\_to\\_user

This method allows you to assign a client to an employee. The email parameter is optional. If no email is provided, the system will assign the client according to its algorithm.

Access permission when generating a key: "Permission to modify/delete client information".

Path

api key* - access token

Body

client_id - client ID
email - employee email (optional)

import requests
import json

params = {"client_id":"#{client_id}","email":"[email protected]"}
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/broadcast'
requests.post(url, json=params)

Importing clients into the system

URL request: https://chatter.mavibot.pro/api/#{api\\_key}/load\\_clients

This method allows you to import clients into the system. When uploading WhatsApp clients, you can provide the number in any format, either with the ending @s.whatsapp.net or without it.

The group ID (group_id) can be obtained HERE via /api/<api_key>/connected_channels. (If client_type = 13 (telephony), then group_id is an empty string: ""). ссылка

The messenger type from which the client came (client_type) can be found HERE. ссылка

Example: [{"platform_id":"79875555555","group_id":34810,"client_type":6}]

Access permission when generating a key: "Permission to modify or delete client information".

Path

api key* - access token

Body

platform_id - phone number
group_id - group ID
client_type - the messenger type a client came from

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)
# if successful, the function will return an ID and an addition status for each item
# response example
# {"status":"success","items":[{"platform_id":"[email protected]","group_id":"5kqchxwyvdvFZOsp80q2qw==","client_type":6,"status":"success","id":1469409}]}

Add clients to a list

URL request: https://chatter.mavibot.ai/api/\\<api_key>/add_to_list

Adds clients to a list

Access permission when generating a key: "Permission to modify or delete client information".

Path

api key* - access token

Body

list_id - list number
clients - client ID array

Example:
JSON parameters
{"list_id":1170282, "clients":[411262772, 646410963]}

Remove clients from a list

URL request: https://chatter.mavibot.ai/api/#{api\\_key}/remove\\_from\\_list

Removes clients from a list

Access permission when generating a key: "Permission to modify or delete client information".

Path

api key* - access token

Body

list_id - list number
clients - client numbers array in the Mavibot builder (values of client_id)

Retrieve client list

URL request: https://chatter.mavibot.a/aipi/\\<api_key>/get_clients

Access permission when generating a key: "Permission to modify or delete client information".

Path

api key* - access token

Body

offset – Offset from the first element

limit – Number of items in the response / Default: 500, Maximum: 500

list – List number

reverse – Indicates reverse sorting (from the oldest record to the newest). This parameter works only if the list is not specified.

Returns the status and an array of items.

{
"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
    }
]
}

Retrieve the list of bot subscribers in any messenger

URL request: https://chatter.mavibot.ai/api/#{api\\_key}/subscribers

Retrieves client information from a selected messenger.

Note! This method does not return variables.

Access permission when generating a key: "Permission to modify or delete client information".

Path

api key* - access token

Body

page

tag – Tag specified on the subscription page

group – VK group ID the subscriber is linked to

date_from – Subscribed after this date (timestamp)

date_to – Subscribed before this date (timestamp)

client_type – Messenger ID for which to retrieve the subscriber list. If not specified, all clients will be returned

[  
  {
    "id": 44886,
    "tag": null,
    "created_at": 1609867984,
    "name": "John Smith",
    "vk_id": "146467928",
    "group": "155824294",
    "variables": null
  },
  {
    "id": 44889,
    "tag": null,
    "created_at": 1609867984,
    "name": "Anna Smith",
    "vk_id": "1609867984",
    "group": "155824294",
    "variables": {
      "utm_source": "some_value"
    }
  }
]

How to work with variables

Assigning variables

URL request: https://chatter.mavibot.ai/api/#{api\\_key}/save\\_variables

!** **No limit applies to this request.

Allows you to save variables in both the lead and the client.
By default, the variable assignment request adds them to deal variables.
To update variables in the client profile, use the client. prefix. For example, for a phone: client.phone.

Access permission when generating a key: "Permission to modify or delete client information".

Update: The clients parameter allows assigning variables in bulk.

Example: {"client_id":49177759, "variables":{"client.phone":"88888888888"}}

Path

api key* - access token

Body

clients – Array of client IDs for variable assignment

client_id – Client ID

variables – Hash of variables (key-value pairs)

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)

Retrieve variables

URL request: https://chatter.mavibot.ai/api/#{api\\_key}/get\\_variables?client\\_id=

Access permission when generating a key: "Permission to modify or delete client information".

Example: https://chatter.mavibot.ai/api/d3f31dabef80ddeb73d43938b4ef8bb0/get\\_variables?client\\_id=49177759

Path

api key* - access token

Body

client_id - client ID

import requests
import json


token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/get_variables?client_id=85856'
requests.get(url)

How to retrieve the client ID (client_id)

Retrieve client_id using the platform_id value

URL request: https://chatter.mavibot.ai/api/#{api\\_key}/find\\_client\\_id\\_by\\_platform\\_id

Access permission when generating a key: "Permission to modify or delete client information".

Path

api key* - access token

Body

platform_ids - ID's array in a messanger
group_id - bot ID

[{
"id":15099119,
"tag":null,
"created_at":1618815253,
"name":"ОЛЬГА БЕЛИК",
"avatar":"https:\\/\\/files.mavibot.ai\\/uploads\\/avatars\\/256865200.jpg",
"platform_id":"2568652",
"group":"Mavibotai_bot",
"variables":{"tg_username":"@belik"}},

{"id":21087377,
"tag":null,
"created_at":1626275893,
"name":"John Smith",
"avatar":"https:\\/\\/files.mavibot.ai\\/uploads\\/avatars\\/571830542.jpg",
"platform_id":"571830542",
"group":"Mavibotai_bot",
"variables":{"tg_username":"@jsmith61"}
}]

Retrieve the client ID from the online chat

URL request: https://chatter.mavibot.ai/api/#{api\\_key}/online\\_chat\\_client\\_id?recipient=

This method allows you to integrate a website with a chat bot. For example, if a user visits a promotion page, you can immediately send a message in the chat with a personalized offer.

Access permission when generating a key: "Permission to modify or delete client information".

Path

api key* - access tiken

Body

tag - tag (client tag)
name - client name
recipient - dialog ID on a website

Where to get the recipient?

You can get it on the website with the Mavibot.ai online chat, use JS to get the property MavibotAi.recipient_id.

{ "client_id": 36553 }

Retrieve client_id by WhatsApp number

URL request: https://chatter.mavibot.ai/api/#{api\\_key}/whatsapp\\_client\\_id?phone=

This method returns the client ID for making API requests if you know the client’s WhatsApp phone number.

If no client exists with that number, the method will return a 404 error.

Access permission when generating a key: "Permission to modify or delete client information".

Path

api key* - access token

Body

phone - phone number
group_id - bot ID

Retrieve client_id by phone number

URL request: https://chatter.mavibot.ai/api/\\<api_key>/find_client_id_by_phone?phone=

This method returns the client ID for making API requests.

The search is performed both among WhatsApp clients and via variables.

Access permission when generating a key: "Permission to modify or delete client information".

Path

api key* - access token

Body

phone - phone number

Retrieve client_id by email

URL request: https://chatter.mavibot.ai/api/#{api\\_key}/find\\_client\\_id\\_by\\_email?email= 

This method returns the client ID for making API requests.

The search is performed using variables.

Access permission when generating a key: "Permission to modify or delete client information".

Path

api key* - access token

Body

email - email for search

Retrieve client_id by variable value

URL запроса: https://chatter.mavibot.ai/api/#{api\\_key}/find\\_client\\_id\\_by\\_var?var=\\&val=

This method returns the client ID for making API requests.

Access permission when generating the key: "Permission to read client information"

Path

api key* - access token

Body

var - variable name to search by
val - variable value
group_id - group ID
search_in - pass the value 'order' to search in deal variables; searches up to three variables for project clients and returns a list of clients that have all the specified variables.

Retrieve the ID of the most recently created client by variable value

URL request: https://chatter.mavibot.ai/api/#{api\\_key}/find\\_latest\\_client\\_id\\_by\\_var ?var=&val=

This method returns the ID of the most recently created client for making API requests. It searches both client and deal variables.

Access permission when generating the key: "Permission to read client information"

Path

api key* - access token

Body

var - variable name to search by
val - variable value

Retrieve a list of client_id values by variable value

URL request: https://chatter.mavibot.ai/api/#{api\\_key}/find\\_all\\_client\\_id\\_by\\_var?var=\\&val=

This method returns a list of client IDs that have the specified variable with the specified value.

Access permission when generating the key: "Permission to read client information"

Path

api key* - access token

Body

var - variable name to search by
val - variable value

{
    // Response
}

Retrieve a list of client_id values based on multiple variable values

URL request: https://chatter.mavibot.ai/api/#{api\\_key}/find\\_all\\_client\\_id\\_by\\_several\\_vars?var=val

Access permission when generating the key: "Permission to read client information".

Path

api key* - acces token

Body

variable1 - Value1

variable2 - Value2

variable3 - Value3

{
 "status":"success","client_ids":[93891114]
}

Search by variables

URL request: https://chatter.mavibot.ai/api/#{api\\_key}/find\\_clients

This method searches by variables and returns a list of client IDs that meet the query conditions.

By default, the search is performed on client variables (recommended): {"q": {"result": "ok", "var": "home", "var": "60"}} – the client must have all specified variables

Search in deal variables, at least one of the specified variables must be present: {"q": {"result": "ok", "var": "home", "var": "60"}, "search_in": "order", "include_all": False}

Client variable name equals one of the list values: {"q": {"name": {"_in": ["Joe", "Jane", "Donald"]}}}

Client variable name does NOT equal any of the list values: {"q": {"name": {"_not_in": ["Joe", "Jane", "Donald"]}}}

Client variable name does not equal "Joe": {"q": {"name": {"_not": "Joe"}}}

Note: Number comparison works only if all clients have numeric values in the searched variable. If even one client has a string, the request will fail.

Access permission when generating the key: "Permission to read client information"

Parameters

Path

api key* - access token

Body

q – required parameter, contains the query conditions for searching variables

search_in – specifies which entity’s variables to search; if not provided, the search is done on client variables. Can take the value order.

include_all – whether all conditions in q must be met;

False – if at least one condition matches, the entity is selected

Success
{"status":"success","client_ids":[41203, 5622354, 785212]} 
{"status":"success","client_ids":[]} 
{"status": "fail", "message": "Parameter "q" required"} {"status": "fail", "message": "Error in parameter format"}
Error
{"status":"fail","message":"Something went wrong"}

How to work with deals

Retrieve the current deal ID

URL request: https://chatter.mavibot.ai/api/#{api\\_key}/get\\_current\\_order\\_id

Access permission when generating the key: "Permission to read CRM information".

Path

api key* - access token

Body

client_id - client ID

Successful response: {"status":"success","order_id":40632}, where
order_id - current deal ID
Error response: {"status":"client_not_found"}

Retrieve the list of deals

URL request: https://chatter.mavibot.ai/api/#{api\\_key}/get\\_orders

Access permission when generating the key: "Permission to read CRM information"

Path

api key* - access token

Body

client_id - client ID

order_status - deal stage:
0 - active deals
1 - successful deals
2 - unsuccessful deals

Successful response: {"status":"success","order_id":[40338,40340,40341]} 
Error response: {"status":"client_not_found"}

Move a deal to the next stage in the Mavibot funnel

URL request: https://chatter.mavibot.ai/api/#{api\\_key}/move\\_order\\_to\\_next\\_state

Access permission when generating the key: "Permission to modify/delete CRM information"

Path

api key* - access token

Body

client_id - client ID

order_id - deal ID

Successful response: 
{"status":"success","state_id":37}, где 
state_id - stage ID in MavibotCRM 
Error response: 
{"status":"client_not_found"}

Retrieve deal data

URL request: https://chatter.mavibot.ai/api/#{api\\_key}/get\\_order\\_vars

Access permission when generating the key: "Permission to read CRM information"

Path

api key* - access token

Body

client_id - client ID

order_id - deal ID

variables - variable array
(format:["var_name1", "var_name2"])

Successful response: 
{"status":"success","result":{"var_name1":"111","var_name2":"13.04.2023"}} 

Error example: 
{"status":"client_not_found"}

Add deal variables

URL request: https://chatter.mavibot.ai/api/#{api\\_key}/set\\_order\\_vars

Access permission when generating the key: "Permission to modify/delete CRM information"

Path

api key* - access token

Body

client_id - client ID

order_id - deal ID

variables -A dictionary of variables (the key is the variable name, and the value is what should be saved in that variable)
(format:{"var_name": "var_velue"})

Successful response: {"status":"success"} 
Error response: {"status":"order 12345 not found"}

Create a deal

URL request: https://chatter.mavibot.ai/api/#{api\\_key}/create\\_order

Access permission when generating the key: "Permission to modify/delete CRM information"

Path

api key* - access token

Body

client_id - client ID

name - deal name

description - deal description

budget - deal amount

You must specify one of the following parameters in the request: client_id, email, or phone.

If multiple parameters are provided, only one will be used. The priority order is: client_id > phone > email.

If phone or email is provided and no client exists with that phone number or email, a new client will be created.

Successful response: {"status":"success","order_id":40654}, 
where order_id is the ID of the new active deal.
Error response: {"status":"client_not_found"}

Move a deal to a stage in MavibotCRM

URL request: https://chatter.mavibot.ai/api/#{api\\_key}/set\\_order\\_state

Access permission when generating the key: "Permission to modify/delete CRM information"

Path

api key* - access token

Body

client_id - client ID

state_id - the stage number to which the client’s deal should be moved

Retrieve the funnel stage ID in Mavibot CRM

URL request: https://chatter.mavibot.ai/api/#{api\\_key}/get\\_order\\_state

Access permission when generating the key: "Permission to read CRM information"

Path

api key* - access token

Body

client_id - client ID

state_id - deal ID (if not specified, the method will return the stage ID of the current deal)

Example of a successful response:
{'status': 'success', 'state_id': 123456}

Example of an unsuccessful response:
{'status': 'order not found'}

What other capabilities are available?

Check if a phone number has WhatsApp

URL request: https://chatter.mavibot.ai/api/#{api\\_key}/check\\_whatsapp

To use this method, WhatsApp must be connected to Mavibot.

Access permission when generating a key: "Permission to modify or delete client information".

Can be called using either GET or POST.

The phone number can be provided in any format.

Path

api key* - access token

Body

phone - phone number to check

Get the list of messengers connected to the project

URL request: https://chatter.mavibot.ai/api/\\<api_key>/connected_channels

Access permission when generating a key: "Permission to modify or delete client information".

The function returns the group_id parameter for each messenger, which must be used when importing clients.

For WhatsApp, it also returns a status field, which can have the following values:

NOT_STARTED = 0
STARTED = 1
ASLEEP = 2
STOPPED = 3

Path

api key* - access token

{'project_id': 1, 
'viber': [{
        'id': 14, 
        'uri': 'mavibotstage', 
        'name': 'mavibotstage', 
        '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': [], 
'avito': [], 
'ok': [], 
'vkontakte': [{
        'id': 33, 
        'group': '143414131',
        'group_id': '143414131'}]
}

Retrieve the list of blocks from the bot’s flow

URL request: https://chatter.mavibot.ai/api/\\<api_key>/get_messages

Access permission when generating a key: "Permission to modify or delete client information".

Path

api key* - access token

Retrieve nested client data

To retrieve client_id and/or the client’s phone number from nested dictionaries (not at the first level), use the delimiter parameter.

Add the following to your request URL:

?delimiter=1&delimiter_value_client_id={key1}1{key2}&delimiter_value_phone={key1}1{key2}

where:

?delimiter=1 – the delimiter value that separates keys {key1}1{key2}1{key3}

delimiter_value_client_id={key1}1{key2} – to retrieve the client ID

delimiter_value_phone={key1}1{key2} – to retrieve the client phone number

{key1}, {key2}, … – keys containing the values (can include any characters except the delimiter). You can have an unlimited number of keys:
?delimiter=1&delimiter_value_client_id={key1}1{key2}1{key3}1{key4}1{key5}1{key6}.
Keys are passed without curly braces.

Use the delimiter between keys. For example, if delimiter=2, then {key1}2{key2}2{key3}; if delimiter=5, then {key1}5{key2}5{key3}. Ensure the key does not contain the delimiter character.

Example:

https://chatter.mavibot.a/aipi/\\<api_key>/callback****?delimiter=1&delimiter_value_client_id={key1}1{key2}&delimiter_value_phone={key1}1{key2}****

You can also retrieve only the ID or only the phone number:

https://chatter.salebot.pro/api/\\<api_key>/callback****?delimiter=1&delimiter_value_client_id={key1}1{key2} -**** only client ID;

https://chatter.salebot.pro/api/\\<api_key>/callback****?delimiter=1delimiter_value_phone={key1}1{key2}**** - only phone number;

API methods:

Start bot: https://chatter.mavibotbot.ai/api/\\<api_key>/callback
Start bot by WhatsApp number: https://chatter.mavibotbot.ai/api/\\<api_key>/whatsapp_callback
Start bot by Telegram ID: https://chatter.mavibotbot.ai/api/\\<api_key>/tg_callback
Send callback message to email client: https://chatter.mavibotbot.ai/api/\\<api_key>/email_callback
Send message to client: https://chatter.mavibotbot.ai/api/\\<api_key>/message
Send WhatsApp message: https://chatter.mavibotbot.ai/api/\\<api_key>/whatsapp_message
Bulk messaging: https://chatter.mavibotbot.ai/api/\\<api_key>/broadcast
Assign variables: https://chatter.mavibotbot.ai/api/\\<api_key>/save_variables
\

If you need additional methods, please contact support.