Запросы выполняются методом POST по URL, т.е. https://chatter.mavibot.ai/api/{api\\_key}/{action}

Где находится: api_key — это ключ доступа к API, который получается в настройках проекта:

Вы можете получить ключ доступа, используя переменную #{api_key}. В ней хранится сгенерированный ключ. Не забудьте сгенерировать его перед использованием.

При копировании URL запроса с этой страницы вставляется пробел, который нужно удалить при вызове

Пример неправильного копирования ссылки: https://chatter.mavibot.ai/api/callback 

Пробел после .pro легко не заметить, но если его оставить, запрос не сработает

При отправке запроса методом GET не используйте запрещённые слова. Ознакомьтесь с правильным формированием GET-запросов

Как получать сообщения на Webhook URL, указанный в настройках проекта

Настройки проекта

Каждое входящее или исходящее сообщение приходит со следующими json POST-запросами:

{
    'id': идентификатор сообщения в системе,
    'client': {
        'id': идентификатор клиента в системе,
        'recepient': идентификатор клиента в мессенджере,
        'client_type': тип мессенджера,
        'name': имя клиента,
        'avatar': аватар клиента,
        'created_at': дата создания клиента,
        'tag': ключ подписки,
        'group': бот, к которому привязан клиент,
    },
    'message': текст сообщения,
    'attachments': массив ссылок на файлы,
    'message_id': id блока, из которого было отправлено сообщение,
    'project_id': id проекта,
    'is_input': 1, если сообщение от клиента, 0, если от бота,
    'delivered': 1, если сообщение отправлено успешно, 0, если была ошибка,
    'error_message': сообщение, объясняющее ошибку
}

Если запрос вернулся с ошибкой, он не будет отправлен повторно. Если сервер вернул ошибку, уведомления всё равно будут приходить.

Как использовать универсальный вебхук

Теперь эти методы можно запускать как с помощью POST, так и GET-запроса.

Ранее параметры (с помощью которых запускались методы клиентов, т.е. client_id) были очень строго прописаны в наших методах, что накладывало некоторые ограничения при использовании со сторонними сервисами.

Теперь вы можете указать, в каком параметре запроса Mavibot будет искать идентификатор пользователя: для этого используется параметр с префиксом value_, например value_user_id и value_group_id.

Также метод отправки callback callback можно запустить, передав email (client_email) и номер телефона клиента (client_phone).

Методы callback и whatsapp_callback не привязаны к именам параметров. Вы можете указать, в каком параметре будет находиться номер телефона, email и id клиента.

Это полезно при настройке приёма вебхука через другой сайт.

Чтобы указать, какая переменная содержит client_id, нужно передать value_client_id и указать имя параметра с этим значением

Чтобы указать, какая переменная содержит телефон, нужно передать value_phone и указать имя параметра с этим значением

Чтобы указать, какая переменная содержит email, нужно передать value_email и указать имя параметра с этим значением

Чтобы указать, какая переменная содержит user_id, нужно передать value_user_id и указать имя параметра с этим значением

Чтобы указать, какая переменная содержит group_id, нужно передать value_group_id и указать имя параметра с этим значением

Пример:

Введите в адресе value_client_id = my_client

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

Запрос будет эквивалентен запросу ниже:

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

Как видите, имя параметра, содержащего имя, отличается префиксом value_

Как запустить бота

Запуск бота

POST https://chatter.mavibot.ai/api/<api_key>/callback

Метод можно использовать для запуска сценария для клиента или для подтверждения действия на стороннем сервисе. Это сообщение не будет видно клиенту.
Дополнительно переданные параметры сохраняются в переменные.
Метод отправки callback теперь можно включить, передав email (client_email) или номер телефона клиента (client_phone)

Параметры пути

Имя Тип Описание
api_key string токен доступа

Тело запроса

Имя Тип Описание
client_phone string номер телефона, по которому находится клиент
client_email string email, по которому находится клиент
client_id string id клиента в редакторе
message string текст сообщения

**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)

Запуск бота через номер в WhatsApp

POST https://chatter.mavibot.ai/api/<api_key>/whatsapp_callback

Этот метод запускает бота в WhatsApp после того, как клиент зарегистрируется через сайт или оставит заявку с номером телефона
Дополнительно переданные параметры сохраняются в переменные

Параметры пути

Имя Тип Описание
api_key string токен доступа

Тело запроса

Имя Тип Описание
name string имя клиента
message string текст сообщения
phone string номер телефона клиента
bot_id string id бота

**200: OK **

{
    // Response
}

Запуск бота через Telegram id

POST https://chatter.mavibot.ai/api/<api_key>/tg_callback

Метод можно использовать для запуска сценария или подтверждения действий на стороннем сайте. Это сообщение не будет видно клиенту.

Дополнительно переданные параметры сохраняются в переменные

Параметры пути

Имя Тип Описание
api_key string токен доступа

Тело запроса

Имя Тип Описание
message string текст сообщения
user_id string id пользователя в Telegram
group_id string имя бота (должно заканчиваться на bot)

**200: OK **

{
    // Response
}

Как работать с сообщениями

Параметры для отправки сообщений

attachment_type может принимать следующие значения: image, video, link, file, audio
При отправке вложений параметр message не обязателен

buttons определяет кнопки, которые будут прикреплены к сообщению. Формат кнопок сопоставим с расширенными настройками кнопок. Возможны два варианта передачи кнопок: с подсказкой в мессенджерах без кнопок и без неё

Вот пример параметра buttons:

"buttons": {"hint": "Этот текст будет показан в Whatsapp",
 "buttons": [
    {"type": "reply", 
     "text": "Какие услуги мы предоставляем", 
     "line": 0, "index_in_line": 0}, 
       
    {"type": "reply", 
     "text": "Информация об оплате", 
     "line": 0, 
     "index_in_line": 1}, 
        
    {"type": "reply", 
     "text": "Наши контакты", 
     "line": 1, "index_in_line": 0}, 
        
    {"type": "reply", 
     "text": "Оставить заявку", 
     "line": 1, "index_in_line": 1}
   ] 
}

Отправка сообщения клиенту

POST https://chatter.mavibot.ai/api/<api_key>/message

Этот метод можно использовать для отправки сообщений с уведомлениями. Параметр message обязателен, если вы не отправляете файл. Если отправляете, то текст не нужен

Параметры пути

Имя Тип Описание
api_key string ключ доступа

Тело запроса

Имя Тип Описание
message_id string номер отправляющего блока
message string текст сообщения
client_id string id клиента в редакторе
attachment_type string тип отображения файла
attachment_url string URL файла
buttons object кнопки

**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)

Отправка сообщений в WhatsApp

POST https://chatter.mavibot.ai/api/<api_key>/whatsapp_message

Позволяет отправить сообщение от имени подключенного бота на указанный номер whatsapp_bot_id необходимо взять из раздела «Мессенджеры и чаты». Каждая подключенная страница WhatsApp получает уникальный идентификатор

Параметры пути

Имя Тип Описание
api_key string ключ доступа

Тело запроса

Имя Тип Описание
message_id string номер отправляющего блока
whatsapp_bot_id number WhatsApp бот, который отправляет сообщение
attachment_url string url файла
attachment_type string тип отображения файла
message string текст сообщения
phone string номер телефона получателя

**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)

Массовая отправка сообщений

POST https://chatter.mavibot.ai/api/<api_key>/broadcast

Метод позволяет осуществлять рассылку сообщений. Если параметр clients не указан, рассылка будет отправлена всем пользователям. Необходимо отправить либо файл, либо текст

Параметры пути

Имя Тип Описание
api_key string ключ доступа

Тело запроса

Имя Тип Описание
message_id string номер отправляющего блока
list string список номеров получателей
shift string количество секунд между сообщениями. По умолчанию 0.2
message string текст сообщения
clients array id получателей
attachment_type string тип отображения файла
attachment_url string URL файла
buttons string кнопки

**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)

Получение истории сообщений

GET https://chatter.mavibot.ai/api/<api_key>/get_history?client_id=

Получение истории сообщений. Параметр client_id можно получить ЗДЕСЬ

Параметры пути

Имя Тип Описание
api_key string ключ доступа

Параметры запроса

Имя Тип Описание
client_id string 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"
    },
  ]
}

Очистка истории сообщений

GET https://chatter.mavibot.ai/api/<api_key>/clear_history?client_id=

Параметры пути

Имя Тип Описание
api_key string ключ доступа

Параметры запроса

Имя Тип Описание
client_id string 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)

Как распределять клиентов

Назначение клиента сотруднику

GET https://chatter.mavibot.ai/api/<api_key>/assign_to_user

Метод позволяет назначить клиента сотруднику. Параметр email необязателен. Если email не указан, распределение произойдет по алгоритму системы

Параметры пути

Имя Тип Описание
api_key string ключ доступа

Параметры запроса

Имя Тип Описание
client_id String id клиента
e-mail String email сотрудника (необязательно)

**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)

Загрузка клиентов в систему

GET https://chatter.mavibot.ai/api/<api_key>/load_clients

Метод позволяет загружать клиентов в систему. При загрузке клиентов WhatsApp вы можете свободно передавать номер с @s.whatsapp.net в конце или без него.

Вы можете получить id группы (group_id) здесь через /api/<api_key>/connected_channels

(если client_type=13 (телефония), то group_id=””)

Вы можете увидеть тип мессенджера, из которого пришел клиент (client_type)

Напр.: [{"platform_id":"79875555555","group_id":34810,"client_type":6}]

Параметры пути

Имя Тип Описание
api_key string ключ доступа

Тело запроса

Имя Тип Описание
platform_id String номер телефона
group_id String id группы
client_type String тип мессенджера, из которого пришел клиент

**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)
# в случае успеха функция возвращает каждому элементу его id и статус добавления
# пример ответа
# {"status":"success","items":[{"platform_id":"[email protected]","group_id":"5kqchxwyvdvFZOsp80q2qw==","client_type":6,"status":"success","id":1469409}]}

Добавление клиентов в список

POST https://chatter.mavibot.ai/api/<api_key>/add_to_list

Параметры пути

Имя Тип Описание
api_key string ключ доступа

Тело запроса

Имя Тип Описание
list_id integer номер списка
clients array массив номеров клиентов

**200: OK **

{
    // Response
}

Удаление клиентов из списка

POST https://chatter.mavibot.ai/api/<api_key>/remove_from_list

Параметры пути

Имя Тип Описание
api_key string ключ доступа

Тело запроса

Имя Тип Описание
list_id integer номер списка
clients array массив номеров клиентов

**200: OK **

{
    // Response
}

Получение списка клиентов

POST https://chatter.mavibot.ai/api/<api_key>/get_clients

Параметры пути

Имя Тип Описание
api_key string ключ доступа

Параметры запроса

Имя Тип Описание
offset string смещение от первого элемента
limit integer количество элементов в ответе. По умолчанию 500, макс. 500
list string номер списка

200: OK Возвращает статус и массив элементов

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

Получение списка подписчиков в любом мессенджере

POST https://chatter.mavibot.ai/api/<api_key>/subscribers

Получение информации о клиентах в выбранном мессенджере

Параметры пути

Имя Тип Описание
api_key string ключ доступа

Параметры запроса

Имя Тип Описание
page integer
tag string тег, который был указан на странице подписки
group integer id группы, к которой привязан подписчик
date_from integer timestamp даты, после которой они подписались
date_to integer timestamp даты, до которой они подписались
client_type integer id мессенджера, для которого нужен список подписчиков. Если не менять, приходят все клиенты

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

Разрешение на удаление клиентов

POST ``https://chatter.mavibot.ai/api/<api_key>/get_clients

Разрешение доступа при генерации ключа: «Разрешение на удаление клиентов»

Параметры

Путь
api key* — токен доступа

Тело
client_ids — список ID клиентов для удаления. Максимум 500. Пример: [199571, 199707, 1935722]

Как работать с переменными

Присвоение переменных

POST https://chatter.mavibot.ai/api/<api_key>/save_variables

Позволяет сохранять переменные в приложении и у клиента.
Запрос присвоения переменных по умолчанию добавляет к переменным транзакции.
Если нужно изменить переменные в профиле, необходимо добавить префикс client.
Напр., для мобильного: client.phone

Параметр clients позволяет присваивать переменные массово

Напр.: {"client_id":49177759, "variables":
{"client.phone":"1234567890"}}

Параметры пути

Имя Тип Описание
api_key string ключ доступа

Тело запроса

Имя Тип Описание
clients array массив id клиентов для присвоения переменных
client_id string id клиента
variables object хеш переменных (ключ-значение)

**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)

Получение переменных

GET https://chatter.mavibot.ai/api/<api_key>/get_variables?client_id=

Параметры пути

Имя Тип Описание
api_key string токен доступа

Параметры запроса

Имя Тип Описание
client_id string 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)

Как получить client_id

Получение client_id по значению platform_id

POST https://chatter.mavibot.ai/api/<api_key>/find_client_id_by_platform_id

Метод возвращает id клиента для выполнения запросов к API

Пример параметров: {"platform_ids": ["571830542", "256865200"]}

Параметры пути

Имя Тип Описание
string ключ доступа

Тело запроса

Имя Тип Описание
platform_ids string массив id в мессенджере

**200: OK **

[{
"id":15099119,
"tag":null,
"created_at":1618815253,
"name":"Oscar Wilde",
"avatar":"https:\\/\\/files.mavibot.pro\\/uploads\\/avatars\\/256865200.jpg",
"platform_id":"2568652",
"group":"Mavibotpro_bot",
"variables":{"tg_username":"@wildeo"}},

{"id":21087377,
"tag":null,
"created_at":1626275893,
"name":"Freddie Mercury",
"avatar":"https:\\/\\/files.mavibot.pro\\/uploads\\/avatars\\/571830542.jpg",
"platform_id":"571830542",
"group":"Mavibotpro_bot",
"variables":{"tg_username":"@freddieisqueen"}
}]

Как получить client id в онлайн-чате

GET https://chatter.mavibot.ai/api/<api_key>/online_chat_client_id?recipient=

Этот метод позволяет интегрировать сайт и чат-бота, т.е. если человек зашел на страницу со спецпредложением, вы можете мгновенно отправить сообщение об этом предложении в чат

Параметры пути

Имя Тип Описание
api_key string токен доступа

Параметры запроса

Имя Тип Описание
tag string тег клиента
name string имя клиента
recipient string id диалога на сайте

**200: OK **

{ "client_id": 36553 }

Где взять recipient? На сайте, где работает онлайн-чат «Mavibot.ai», нужно получить свойство MaviBotPro.recipient_id с помощью JS.

Как получить client id по номеру WhatsApp

GET https://chatter.mavibot.ai/api/<api_key>/whatsapp_client_id?phone=

Метод возвращает id клиента для выполнения запросов к API, если вы знаете номер телефона клиента в WhatsApp.
Если такого клиента с этим номером нет, вы получите 404.

Параметры пути

Имя Тип Описание
api_key string токен доступа

Параметры запроса

Имя Тип Описание
phone string номер телефона

**200: OK **

{
    // Response
}

Получение client id по номеру телефона

GET https://chatter.mavibot.ai/api/<api_key>/find_client_id_by_phone?phone=

Метод возвращает id клиента для выполнения запросов к API.
Поиск происходит по клиентам WhatsApp, а также по переменным.

Параметры пути

Имя Тип Описание
api_key string токен доступа

Параметры запроса

Имя Тип Описание
phone string номер телефона

**200: OK **

{
    // Response
}

Получение client id по email

GET https://chatter.mavibot.ai/api/<api_key>/find_client_id_by_email?email=

Метод возвращает id клиента для выполнения запросов к API. Поиск происходит по переменным.

Параметры пути

Имя Тип Описание
api_key string токен доступа

Параметры запроса

Имя Тип Описание
email string email для поиска

**200: OK **

{
    // Response
}

Получение client id по значению переменной

GET https://chatter.mavibot.ai/api/<api_key>/find_client_id_by_var?var=&val=

Метод возвращает id клиента для выполнения запросов к API

Параметры пути

Имя Тип Описание
api_key string токен доступа

Параметры запроса

Имя Тип Описание
var string имя переменной, по которой будет производиться поиск
val string значение переменной

**200: OK **

{
    // Response
}

Какие ещё есть возможности

Перевод сделки в статус MavibotCRM

POST https://chatter.mavibot.ai/api/<api_key>/set_order_state

Номер сделки можно получить в окне редактирования сценария MavibotCRM.

Параметры пути

Имя Тип Описание
api_key string ключ доступа

Тело запроса

Имя Тип Описание
client_id string id клиента
state_id string номер статуса, в который нужно перевести сделку клиента

**200: OK **

{
    // Response
}

Проверка, подписан ли человек на аккаунт Instagram

GET https://chatter.mavibot.ai/api/<api_key>/check_insta_subscription

Может вызываться как методом POST, так и методом GET

Параметры пути

Имя Тип Описание
api_key string ключ доступа

Тело запроса

Имя Тип Описание
user_name string имя пользователя, которого нужно проверить
login string логин бота, который проверяется

200: OK Поле is_follower содержит информацию о том, подписан ли человек

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

Проверка, есть ли WhatsApp на номере телефона

GET https://chatter.mavibot.ai/api/<api_key>/check_whatsapp

Для использования метода ОБЯЗАТЕЛЬНО наличие подключенных WhatsApp и Mavibot

Может вызываться как методом POST, так и методом GET
Номер телефона можно передавать в любом формате

Параметры пути

Имя Тип Описание
api_key string токен доступа

Тело запроса

Имя Тип Описание
phone string номер телефона

**200: OK **

{
    // Response
}

Получение списка мессенджеров, подключенных к проекту (включая group_id)

GET https://chatter.mavibot.ai/api/<api_key>/connected_channels

Функция возвращает параметр group_id для каждого мессенджера, и его необходимо передавать при загрузке клиентов

Поле status также возвращается для WhatsApp и содержит значение:
NOT_STARTED = 0
STARTED = 1
ASLEEP = 2
STOPPED = 3

Параметры пути

Имя Тип Описание
api_key string токен доступа

**200: OK **

{'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': [] 
}

Получение списка блоков из схемы бота

GET https://chatter.mavibot.ai/api/<api_key>/get_messages

Параметры пути

Имя Тип Описание
api_key string токен доступа

**200: OK **

{
    // Response
}

Если вам нужны дополнительные методы, пожалуйста, обратитесь в службу поддержки