API редактора

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

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

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

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

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

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

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

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

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

Запросы выполняются методом 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': сообщение с объяснением ошибки
}

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

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

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

• callback

• whatsapp_callback

• message

• whatsapp_message

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

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

Также метод для отправки callback callback может быть запущен при передаче email (client_email) и номера телефона клиента (client_phone).

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

Это полезно, когда вы настраиваете прием webhook через другой сайт.

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

Чтобы указать, какая переменная содержит phone нужно передать 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)

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

Name	Тип	Описание
api_key	строковых	токен доступа

Тело запроса

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

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 после того, как клиент зарегистрировался через сайт или оставил заявку с номером телефона Дополнительно переданные параметры сохраняются в переменных

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

Name	Тип	Описание
api_key	строковых	токен доступа

Тело запроса

Name	Тип	Описание
name	строковых	имя клиента
message	строковых	текст сообщения
phone	строковых	номер телефона клиента
bot_id	строковых	id бота

200: OK

{
    // Ответ
}

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

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

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

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

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

Name	Тип	Описание
api_key	строковых	токен доступа

Тело запроса

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

200: OK

{
    // Ответ
}

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

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

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 обязателен, если вы не отправляете файл. Если отправляете, текст не нужен

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

Name	Тип	Описание
api_key	строковых	ключ доступа

Тело запроса

Name	Тип	Описание
message_id	строковых	номер блока отправки
message	строковых	текст сообщения
client_id	строковых	id клиента в редакторе
attachment_type	строковых	тип отображения файла
attachment_url	строковых	URL файла
buttons	объект	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)

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

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

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

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

Name	Тип	Описание
api_key	строковых	ключ доступа

Тело запроса

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

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 не указан, рассылка будет отправлена всем пользователям. Необходимо либо отправить файл, либо текст

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

Name	Тип	Описание
api_key	строковых	ключ доступа

Тело запроса

Name	Тип	Описание
message_id	строковых	номер блока отправки
list	строковых	список номеров получателей
shift	строковых	количество секунд между сообщениями. По умолчанию 0.2
message	строковых	текст сообщения
clients	массив	id получателей
attachment_type	строковых	тип отображения файла
attachment_url	строковых	URL файла
buttons	строковых	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)

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

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

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

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

Name	Тип	Описание
api_key	строковых	ключ доступа

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

Name	Тип	Описание
client_id	строковых	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=

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

Name	Тип	Описание
api_key	строковых	ключ доступа

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

Name	Тип	Описание
client_id	строковых	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 не указан, распределение будет выполнено по алгоритму системы

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

Name	Тип	Описание
api_key	строковых	ключ доступа

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

Name	Тип	Описание
client_id	Строка	id клиента
e-mail	Строка	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 в конце, так и без него.

Получить group id (group_id) здесь через /api/<api_key>/connected_channels

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

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

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

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

Name	Тип	Описание
api_key	строковых	ключ доступа

Тело запроса

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

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

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

Name	Тип	Описание
api_key	строковых	ключ доступа

Тело запроса

Name	Тип	Описание
list_id	целое	номер списка
clients	массив	массив номеров клиентов

200: OK

{
    // Ответ
}

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

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

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

Name	Тип	Описание
api_key	строковых	ключ доступа

Тело запроса

Name	Тип	Описание
list_id	целое	номер списка
clients	массив	массив номеров клиентов

200: OK

{
    // Ответ
}

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

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

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

Name	Тип	Описание
api_key	строковых	ключ доступа

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

Name	Тип	Описание
offset	строковых	смещение от первого элемента
limit	целое	количество элементов в ответе. По умолчанию 500, максимум 500
list	строковых	номер списка

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

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

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

Name	Тип	Описание
api_key	строковых	ключ доступа

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

Name	Тип	Описание
page	целое
tag	строковых	тег, указанный на странице подписки
group	целое	id группы, к которой привязан подписчик
date_from	целое	timestamp даты, после которой они подписались
date_to	целое	timestamp даты, до которой они подписались
client_type	целое	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. Напр., для mobile: client.phone

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

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

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

Name	Тип	Описание
api_key	строковых	ключ доступа

Тело запроса

Name	Тип	Описание
clients	массив	массив id клиентов для присваивания переменных
client_id	строковых	id клиента
переменные	объект	хэш переменной (ключ-значение)

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=

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

Name	Тип	Описание
api_key	строковых	токен доступа

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

Name	Тип	Описание
client_id	строковых	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"]}

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

Name	Тип	Описание
	строковых	ключ доступа

Тело запроса

Name	Тип	Описание
platform_ids	строковых	массив id в мессенджере

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

Как получить client id в Online chat

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

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

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

Name	Тип	Описание
api_key	строковых	токен доступа

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

Name	Тип	Описание
tag	строковых	тег клиента
name	строковых	имя клиента
recipient	строковых	id диалога на сайте

200: OK

{ "client_id": 36553 }

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

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

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

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

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

Name	Тип	Описание
api_key	строковых	токен доступа

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

Name	Тип	Описание
phone	строковых	номер телефона

200: OK

{
    // Ответ
}

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

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

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

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

Name	Тип	Описание
api_key	строковых	токен доступа

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

Name	Тип	Описание
phone	строковых	номер телефона

200: OK

{
    // Ответ
}

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

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

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

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

Name	Тип	Описание
api_key	строковых	токен доступа

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

Name	Тип	Описание
email	строковых	email для поиска

200: OK

{
    // Ответ
}

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

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

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

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

Name	Тип	Описание
api_key	строковых	токен доступа

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

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

200: OK

{
    // Ответ
}

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

Перевод транзакции в состояние MavibotCRM

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

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

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

Name	Тип	Описание
api_key	строковых	ключ доступа

Тело запроса

Name	Тип	Описание
client_id	строковых	id клиента
state_id	строковых	номер состояния, в которое нужно перевести транзакцию клиента

200: OK

{
    // Ответ
}

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

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

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

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

Name	Тип	Описание
api_key	строковых	ключ доступа

Тело запроса

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

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 Номер телефона можно передавать в любом формате

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

Name	Тип	Описание
api_key	строковых	токен доступа

Тело запроса

Name	Тип	Описание
phone	строковых	номер телефона

200: OK

{
    // Ответ
}

Получение списка мессенджеров, подключенных к проекту (включая 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

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

Name	Тип	Описание
api_key	строковых	токен доступа

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

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

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

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

Name	Тип	Описание
api_key	строковых	токен доступа

200: OK

{
    // Ответ
}

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