Конструктор API

Некоторые функции API-запросов можно запускать в Калькуляторе.

Запросы отправляются с помощью POST или GET метода на URL в следующем формате:

https://chatter.mavibot.ai/api/{api_key}/{action}

Где:

api_key — ключ доступа к API, сгенерированный в настройках проекта.

Чтобы использовать токен в URL-запросе, сначала нужно сгенерировать ключ API.

Инструкция по этому приведена в разделе «Генерация ключа API». ссылка

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

Пример некорректной ссылки: https://chatter.mavibot.pro /api/callback

Если пробел после .pro останется, запрос не сработает.

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

Убедитесь, что вы понимаете правильный формат GET-запросов.

Как сгенерировать ключ API

Старая функция генерации ключа API по-прежнему работает как прежде, но недоступна для новых проектов.

Если в вашем проекте уже есть сгенерированные ключи API без настроек доступа, описанных в этом разделе, они продолжат нормально работать.

Если вам нужно сгенерировать новые ключи, используйте обновлённые настройки.

Чтобы сгенерировать ключ API, перейдите в настройки проекта:

Затем перейдите в раздел «Интеграции»:

В разделе «Интеграции» вы найдёте кнопку «Добавить ключ API»:

После нажатия на кнопку откроется модальное окно с настройками доступа и параметрами генерации ключа API:

Далее нужно выбрать права доступа для ключа API:

API-функция будет работать в соответствии с выбранными вами правами доступа.

Обратите внимание!

API-функция зависит от заданных вами прав доступа: если вы сгенерируете ключ API только с правом чтения информации о клиенте, а затем используете его для отправки сообщения клиенту или изменения его переменных, запрос API завершится ошибкой. Требуемое разрешение для каждого API-запроса указано в карточке запроса API:

Далее введите имя для ключа API:

Сгенерируйте ключ API, нажав кнопку «Сгенерировать»:

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

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

Далее нужно установить основной ключ проекта. Это позволит использовать ключ в URL-запросе с подстановкой #{api_key}.

Для этого нажмите кнопку "{+}" справа от нужного ключа API:

После этого рядом с ключом появится метка, указывающая, что он является основным ключом проекта.

Основной ключ проекта можно использовать через api_key: просто сгенерируйте нужный ключ, задайте ему права и назначьте его основным ключом проекта. Затем в Калькуляторе используйте URL-запрос с подстановкой #{api_key}, в которой будет содержаться значение основного ключа проекта.

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

и вставьте его в URL-запрос вместо #{api_key}:

Ключ API, созданный старым способом, по умолчанию назначается основным ключом проекта и имеет полные права.

Примечание!

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

Обратите внимание!

Если у вас есть ключи API, созданные старым способом, они продолжат нормально работать. Сгенерировать новые ключи API старого типа невозможно.

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

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

{
    "id": "ID сообщения в системе",
    "client": {
        "id": "ID клиента в системе",
        "recepient": "ID клиента в мессенджере",
        "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": "текст ошибки доставки сообщения"
}

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

Как создать JSON-запрос

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

Добавьте раздел API Request.
Выберите тип запроса POST-JSON.
Затем заполните поля запроса:

URL запроса — путь к вызываемой функции. В документации он всегда указан в первой строке рядом с типом запроса:

Сохранённые значения — список параметров ответа с именами переменных, в которые должны сохраняться результаты, в следующем формате:

request_parameter -> your_variable
Если ответ содержит параметры со сложной структурой, разбирайте их следующим образом:
"cell_number":{"row":4,"col":2} cell_number|row ->String; cell_number|col -> Column

Заголовки запроса — заполните при необходимости. Обычно сюда входят формат данных и/или токен доступа.

Параметры JSON — тело запроса, где вы указываете параметры данных в формате JSON. Пример:

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

Чтобы понять структуру ответа, напишите #{custom_answer} в поле Message, чтобы вывести значение переменной.

Далее в документации перечислены допустимые параметры в разделе "Body":

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

Теперь перечисленные методы можно выполнять как POST- или GET-запросы.

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

Теперь вы можете указать, по какому параметру запроса SaleBot должен искать ID пользователя. Используйте параметр с префиксом value_например, value_user_id или value_group_id.

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

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

Это полезно при настройке получения webhook с сайта.

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

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

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

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

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

Чтобы указать переменную, содержащую само сообщение в webhook, используйте value_message (передаётся так же, как и другие параметры).

Пример:

В адресе укажите 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.pro/api/d3f31dabef80ddeb73d43938b4ef8bb0/callback {"client_id":49177759, "message":"Hello world"}

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

Обратите внимание!

Некоторые события создают системные уведомления внутри проекта.

Например, есть системные уведомления с непустым полем message, но без текста клиента.

В то же время проект также может генерировать хуки сообщений с определённым содержимым, например "message: new_chat_member".

Поэтому важно проверять содержимое: это будет либо системное уведомление, либо хук для определённого события.

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

Запустить бота

POST https://chatter.mavibot.ai/api/#{api_key}/callback

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

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

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

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

Права доступа при генерации ключа: "Разрешение на изменение/удаление информации о клиенте".

Путь

api key* - токен доступа

Body

client_phone - номер телефона, используемый для поиска клиента

client_email - email, используемый для поиска клиента

client_id - ID клиента в конструкторе

message - текст сообщения

resume_bot - True (необязательный параметр). Если бот приостановлен, это используется для его возобновления.

Пример: resume_bot = True

time_shift - число. Если указано, сообщение будет отправлено спустя указанное количество секунд от текущего времени.

send_time - дата и время в формате "%Y-%m-%d %H:%M:%S" (например, "2024-10-16 13:15:59"). Задаёт дату и время отправки сообщения. Если указаны и time_shift, и send_time, приоритет будет у time_shift.

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)

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

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

URL запроса: https://chatter.mavibot.ai/api/<api_key>/whatsapp_callback

Этот метод может запускать WhatsApp-бота после того, как клиент зарегистрируется на сайте или отправит запрос со своим номером телефона.

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

Права доступа при генерации ключа: "Разрешение на изменение или удаление информации о клиенте".

Путь

api key* - токен доступа

Body

name - имя клиента message - текст сообщения phone - номер телефона клиента bot_id - ID бота resume_bot - True (необязательный параметр). Если бот приостановлен, используйте это для его возобновления. Пример: resume_bot = True

Запуск бота с использованием Telegram ID

POST https://chatter.mavibot.pro/api/#{api_key}/tg_callback

URL запроса: https://chatter.mavibot.pro/api/#{api_key}/tg_callback

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

Обратите внимание: все дополнительные переданные параметры будут сохранены в переменных.

Права доступа при генерации ключа: "Разрешение на изменение или удаление информации о клиенте".

Путь

api key* - токен доступа

Body

message - текст сообщения user_id - Telegram ID пользователя group_id - имя бота (оканчивается на bot) resume_bot - True (необязательный параметр). Если бот приостановлен, используйте это для его возобновления. Пример: resume_bot = True

Отправка callback-сообщений списку клиентов по platform_id

POST https://chatter.mavibot.ai/api/#{api_key}/send_callback_by_platform_id

URL запроса: https://chatter.mavibot.ai/api/#{api_key}/send_callback_by_platform_id

Когда в проекте найдены клиенты с platform_id из списка, будет отправлен callback с текстом из поля callback_text. Лимит: 1 запрос = максимум 300 отправок

Пример параметров запроса: {"platform_ids":[407184121, "79609879898", "2rwewefw"], "callback_text": "test_callback"}

Права доступа при генерации ключа: "Разрешение на изменение или удаление информации о клиенте".

Путь

api key* - токен доступа

Body

platform_ids - список ID клиентов в мессенджере callback_text - текст callback group_id - ID бота

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

POST https://chatter.mavibot.ai/api/#{api_key}/email_callback

URL запроса: https://chatter.mavibot.ai/api/#{api_key}/email_callback

Этот метод может запускать email-бота после того, как клиент зарегистрируется на сайте или отправит запрос со своим email. Метод найдёт email клиента или создаст его, если он не найден.

Права доступа при генерации ключа: "Разрешение на изменение или удаление информации о клиенте".

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

Путь

api key* - токен доступа

Body

name - имя клиента message - текст сообщения email - адрес электронной почты email_id_bot - email бота resume_bot - True (необязательный параметр).

Если бот приостановлен, используйте это для его возобновления. Пример: resume_bot = True

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

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

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

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

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

Права доступа при генерации ключа: "Разрешение на изменение или удаление информации о клиенте".

Путь

api key* - токен доступа

Body

message_id - номер блока для отправки message - текст сообщения client_id - ID клиента в конструкторе attachment_type - тип отображения файла. Обязателен, если указан attachment_url. attachment_url - URL файла buttons - кнопки

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)

# Отправка вложения
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)

# В 'attachment_type' укажите 'video', 'image' или 'file'
# в зависимости от типа вложения: видео, изображение или документ.

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

POST https://chatter.salebot.pro/api/<api_key>/whatsapp_message

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

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

Права доступа при генерации ключа: "Разрешение на изменение или удаление информации о клиенте".

Путь

api key* - токен доступа

Body

message_id - номер блока для отправки whatsapp_bot_id - ID WhatsApp-бота, от имени которого должно быть отправлено сообщение attachment_url - URL файла attachment_type - тип отображения файла. Обязателен, если указан attachment_url. message - текст сообщения phone - номер телефона получателя

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

URL запроса: https://chatter.mavibot.ai/api/#{api_key}/broadcast

Этот метод позволяет запустить рассылку.

Вы можете использовать один из следующих взаимоисключающих вариантов:

параметр list — рассылка будет отправлена в указанный список клиентов.
параметр clients — рассылка будет отправлена массиву ID клиентов.
параметры platform_ids и group_id — рассылка будет отправлена массиву platform_ids (ID в мессенджере) для указанного бота (group_id).
Если ни один из перечисленных выше параметров не указан, рассылка отправлена не будет.

Обязательные параметры: message (и/или attachment_type и attachment_url) или message_id.

Права доступа при генерации ключа: "Разрешение на изменение или удаление информации о клиенте".

Путь

api key* - токен доступа

Body

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

clients - ID клиентов в конструкторе

message - текст сообщения

platform_ids - ID получателей в мессенджере. Должен использоваться вместе с обязательным параметром group_id

group_id - требуется только при использовании platform_ids. Игнорируется при других вариантах. Указывает бота, от имени которого выполняется отправка на указанные platform_ids

attachment_url - URL файла

attachment_type - тип отображения файла. Обязателен, если указан attachment_url.

buttons - кнопки

message_id - номер блока для отправки

shift — количество секунд между сообщениями. По умолчанию 0.2.

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=

URL запроса: https://chatter.mavibot.ai/api/#{api_key}/get_history?client_id=

Параметр client_id можно получить здесь. ссылка

Права доступа при генерации ключа: "Разрешение на чтение информации о клиенте".

Путь

api key* - токен доступа

Body

client_id - ID клиента

limit - количество элементов в ответе. По умолчанию: 2000, максимум: 2000

start_date - начальная дата периода выборки (обязательно, если указан stop_date), формат: dd.mm.yyyy

stop_date - конечная дата периода выборки (обязательно, если указан start_date), формат: dd.mm.yyyy

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

Очистить историю сообщений

GET https://chatter.mavibot.ai/api/#{api_key}/clear_history?client_id=

URL запроса: https://chatter.mavibot.ai/api/#{api_key}/clear_history?client_id=

Удаляет историю чата

Права доступа при генерации ключа: "Разрешение на изменение/удаление информации о клиенте".

Путь

api key* - токен доступа

Body

client_id - ID клиента

import requests
import json


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

Как назначать клиентов

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

POST https://chatter.mavibot.ai/api/#{api_key}/assign_to_user

URL запроса: https://chatter.mavibot.ai/api/#{api_key}/assign_to_user

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

Права доступа при генерации ключа: "Разрешение на изменение/удаление информации о клиенте".

Путь

api key* - токен доступа

Body

client_id - ID клиента email - email сотрудника (необязательно)

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)

Импорт клиентов в систему

POST https://chatter.mavibot.ai/api/#{api_key}/load_clients

URL запроса: https://chatter.mavibot.pro/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* - токен доступа

Body

platform_id - номер телефона group_id - ID группы client_type - тип мессенджера, из которого пришёл клиент

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

URL запроса: https://chatter.mavibot.ai/api/<api_key>/add_to_list

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

Права доступа при генерации ключа: "Разрешение на изменение или удаление информации о клиенте".

Путь

api key* - токен доступа

Body

list_id - номер списка clients - массив ID клиентов

Пример: JSON parameters {"list_id":1170282, "clients":[411262772, 646410963]}

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

POST https://chatter.mavibot.ai/api/#{api_key}/remove_from_list

URL запроса: https://chatter.mavibot.ai/api/#{api_key}/remove_from_list

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

Права доступа при генерации ключа: "Разрешение на изменение или удаление информации о клиенте".

Путь

api key* - токен доступа

Body

list_id - номер списка clients - массив номеров клиентов в конструкторе Mavibot (значения client_id)

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

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

URL запроса: https://chatter.mavibot.a/aipi/<api_key>/get_clients

Права доступа при генерации ключа: "Разрешение на изменение или удаление информации о клиенте".

Путь

api key* - токен доступа

Body

offset – смещение от первого элемента

limit – количество элементов в ответе / По умолчанию: 500, максимум: 500

list – номер списка

reverse – указывает обратную сортировку (от самой старой записи к самой новой). Этот параметр работает только если список не указан.

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

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

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

GET https://chatter.mavibot.ai/api/#{api_key}/subscribers

URL запроса: https://chatter.mavibot.ai/api/#{api_key}/subscribers

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

Примечание! Этот метод не возвращает переменные.

Права доступа при генерации ключа: "Разрешение на изменение или удаление информации о клиенте".

Путь

api key* - токен доступа

Body

page tag – тег, указанный на странице подписки group – ID группы VK, к которой привязан подписчик date_from – подписан после этой даты (timestamp) date_to – подписан до этой даты (timestamp) client_type – ID мессенджера, для которого нужно получить список подписчиков. Если не указан, будут возвращены все клиенты

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

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

Назначение переменных

POST https://chatter.mavibot.ai/api/#{api_key}/save_variables

URL запроса: https://chatter.mavibot.ai/api/#{api_key}/save_variables

! На этот запрос ограничение не распространяется.

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

Права доступа при генерации ключа: "Разрешение на изменение или удаление информации о клиенте".

Обновить: Параметр clients позволяет назначать переменные пакетно. Пример: {"client_id":49177759, "variables":{"client.phone":"88888888888"}}

Путь

api key* - токен доступа

Body

clients – массив ID клиентов для назначения переменных

client_id – ID клиента

variables – хэш переменных (пары ключ-значение)

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=

URL запроса: https://chatter.mavibot.ai/api/#{api_key}/get_variables?client_id=

Права доступа при генерации ключа: "Разрешение на изменение или удаление информации о клиенте".

Пример: https://chatter.mavibot.ai/api/d3f31dabef80ddeb73d43938b4ef8bb0/get_variables?client_id=49177759

Путь

api key* - токен доступа

Body

client_id - ID клиента

import requests
import json


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

Как получить ID клиента (client_id)

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

POST https://chatter.mavibot.ai/api/#{api_key}/find_client_id_by_platform_id

URL запроса: https://chatter.mavibot.ai/api/#{api_key}/find_client_id_by_platform_id

Права доступа при генерации ключа: "Разрешение на изменение или удаление информации о клиенте".

Путь

api key* - токен доступа

Body

platform_ids - массив ID в мессенджере group_id - 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"}
}]

Получить ID клиента из онлайн-чата

GET https://chatter.mavibot.ai/api/#{api_key}/online_chat_client_id?recipient=

URL запроса: https://chatter.mavibot.ai/api/#{api_key}/online_chat_client_id?recipient=

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

Права доступа при генерации ключа: "Разрешение на изменение или удаление информации о клиенте".

Путь

api key* - токен доступа

Body

tag - тег (тег клиента) name - имя клиента recipient - ID диалога на сайте

Где взять recipient?

Его можно получить на сайте с онлайн-чатом Mavibot.ai, используйте JS, чтобы получить свойство MavibotAi.recipient_id.

{ "client_id": 36553 }

Получить client_id по номеру WhatsApp

GET https://chatter.mavibot.ai/api/#{api_key}/whatsapp_client_id?phone=

URL запроса: https://chatter.mavibot.ai/api/#{api_key}/whatsapp_client_id?phone=

Этот метод возвращает ID клиента для выполнения API-запросов, если вы знаете номер WhatsApp клиента. Если клиента с таким номером не существует, метод вернёт ошибку 404.

Права доступа при генерации ключа: "Разрешение на изменение или удаление информации о клиенте".

Путь

api key* - токен доступа

Body

phone - номер телефона group_id - ID бота

Получить client_id по номеру телефона

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

URL запроса: https://chatter.mavibot.ai/api/<api_key>/find_client_id_by_phone?phone=

Этот метод возвращает ID клиента для выполнения API-запросов.

Поиск выполняется как среди клиентов WhatsApp, так и по переменным.

Права доступа при генерации ключа: "Разрешение на изменение или удаление информации о клиенте".

Путь

api key* - токен доступа

Body

phone - номер телефона

Получить client_id по email

GET https://chatter.mavibot.ai/api/#{api_key}/find_client_id_by_email?email=

URL запроса: https://chatter.mavibot.ai/api/#{api_key}/find_client_id_by_email?email=

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

Права доступа при генерации ключа: "Разрешение на изменение или удаление информации о клиенте".

Путь

api key* - токен доступа

Body

email - email для поиска

Получить client_id по значению переменной

GET https://chatter.mavibot.ai/api/#{api_key}/find_client_id_by_var?var=&val=

URL запроса: https://chatter.mavibot.ai/api/#{api_key}/find_client_id_by_var?var=&val=

Этот метод возвращает ID клиента для выполнения API-запросов.

Разрешение при создании ключа: "Разрешение на чтение информации о клиентах"

Путь

api key* - токен доступа

Body

var - имя переменной, по которой выполняется поиск val - значение переменной group_id - ID группы search_in - передайте значение 'order' для поиска в переменных сделки; выполняется поиск до трёх переменных для клиентов проекта и возвращается список клиентов, у которых есть все указанные переменные.

Получить ID последнего созданного клиента по значению переменной

GET https://chatter.mavibot.ai/api/#{api_key}/find_latest_client_id_by_var?var=&val=

URL запроса: https://chatter.mavibot.ai/api/#{api_key}/find_latest_client_id_by_var ?var=&val=

Этот метод возвращает ID последнего созданного клиента для выполнения API-запросов. Он выполняет поиск как по переменным клиента, так и по переменным сделки.

Разрешение при создании ключа: "Разрешение на чтение информации о клиентах"

Путь

api key* - токен доступа

Body

var - имя переменной, по которой выполняется поиск val - значение переменной

Получить список значений client_id по значению переменной

GET https://chatter.mavibot.ai/api/#{api_key}/find_all_client_id_by_var?var=&val=

URL запроса: https://chatter.mavibot.ai/api/#{api_key}/find_all_client_id_by_var?var=&val=

Этот метод возвращает список ID клиентов, у которых указана переменная с заданным значением.

Разрешение при создании ключа: "Разрешение на чтение информации о клиентах"

Путь

api key* - токен доступа

Body

var - имя переменной, по которой выполняется поиск val - значение переменной

{
    // Ответ
}

Получить список значений client_id на основе нескольких значений переменных

GET https://chatter.mavibot.ai/api/#{api_key}/find_all_client_id_by_several_vars?var=val

URL запроса: https://chatter.mavibot.ai/api/#{api_key}/find_all_client_id_by_several_vars?var=val

Разрешение при создании ключа: "Разрешение на чтение информации о клиентах".

Путь

api key* - токен доступа

Body

variable1 - Value1

variable2 - Value2

variable3 - Value3

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

Поиск по переменным

POST https://chatter.mavibot.ai/api/#{api_key}/find_clients

URL запроса: https://chatter.mavibot.ai/api/#{api_key}/find_clients

Этот метод выполняет поиск по переменным и возвращает список ID клиентов, соответствующих условиям запроса.

По умолчанию поиск выполняется по переменным клиента (рекомендуется): {"q": {"result": "ok", "var": "home", "var": "60"}} – у клиента должны быть все указанные переменные

Поиск по переменным сделки, должна присутствовать хотя бы одна из указанных переменных: {"q": {"result": "ok", "var": "home", "var": "60"}, "search_in": "order", "include_all": False}

Имя переменной клиента равно одному из значений списка: {"q": {"name": {"_in": ["Joe", "Jane", "Donald"]}}}

Имя переменной клиента НЕ равно ни одному из значений списка: {"q": {"name": {"_not_in": ["Joe", "Jane", "Donald"]}}}

Имя переменной клиента не равно "Joe": {"q": {"name": {"_not": "Joe"}}}

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

Разрешение при создании ключа: "Разрешение на чтение информации о клиентах"

Параметры

Путь

api key* - токен доступа

Body

q – обязательный параметр, содержит условия запроса для поиска переменных

search_in – указывает, переменные какой сущности искать; если не указано, поиск выполняется по переменным клиента. Может принимать значение order.

include_all – должны ли выполняться все условия в q;

False – если совпадает хотя бы одно условие, сущность выбирается

Успешно
{"status":"success","client_ids":[41203, 5622354, 785212]} 
{"status":"success","client_ids":[]} 
{"status": "fail", "message": "Parameter "q" required"} {"status": "fail", "message": "Error in parameter format"}
Ошибка
{"status":"fail","message":"Something went wrong"}

Как работать со сделками

Получить ID текущей сделки

GET https://chatter.mavibot.ai/api/#{api_key}/get_current_order_id

URL запроса: https://chatter.mavibot.ai/api/#{api_key}/get_current_order_id

Разрешение при создании ключа: "Разрешение на чтение информации CRM".

Путь

api key* - токен доступа

Body

client_id - ID клиента

Успешный ответ: {"status":"success","order_id":40632}, где
order_id - ID текущей сделки
Ответ при ошибке: {"status":"client_not_found"}

Получить список сделок

GET https://chatter.mavibot.ai/api/#{api_key}/get_orders

URL запроса: https://chatter.mavibot.ai/api/#{api_key}/get_orders

Разрешение при создании ключа: "Разрешение на чтение информации CRM"

Путь

api key* - токен доступа

Body

client_id - ID клиента

order_status - этап сделки: 0 - активные сделки 1 - успешные сделки 2 - неуспешные сделки

Успешный ответ: {"status":"success","order_id":[40338,40340,40341]} 
Ответ при ошибке: {"status":"client_not_found"}

Перевести сделку на следующий этап в воронке Mavibot

POST https://chatter.mavibot.ai/api/#{api_key}/move_order_to_next_state

URL запроса: https://chatter.mavibot.ai/api/#{api_key}/move_order_to_next_state

Разрешение при создании ключа: "Разрешение на изменение/удаление информации CRM"

Путь

api key* - токен доступа

Body

client_id - ID клиента

order_id - ID сделки

Успешный ответ: 
{"status":"success","state_id":37}, где 
state_id - ID этапа в MavibotCRM 
Ответ при ошибке: 
{"status":"client_not_found"}

Получить данные сделки

POST https://chatter.mavibot.ai/api/#{api_key}/get_order_vars

URL запроса: https://chatter.mavibot.ai/api/#{api_key}/get_order_vars

Разрешение при создании ключа: "Разрешение на чтение информации CRM"

Путь

api key* - токен доступа

Body

client_id - ID клиента

order_id - ID сделки

variables - массив переменных (формат:["var_name1", "var_name2"] )

Успешный ответ: 
{"status":"success","result":{"var_name1":"111","var_name2":"13.04.2023"}} 

Пример ошибки: 
{"status":"client_not_found"}

Добавить переменные сделки

POST https://chatter.mavibot.ai/api/#{api_key}/set_order_vars

URL запроса: https://chatter.mavibot.ai/api/#{api_key}/set_order_vars

Разрешение при создании ключа: "Разрешение на изменение/удаление информации CRM"

Путь

api key* - токен доступа

Body

client_id - ID клиента

order_id - ID сделки

variables - словарь переменных (ключ — имя переменной, а значение — то, что нужно сохранить в этой переменной) (формат:{"var_name": "var_velue"})

Успешный ответ: {"status":"success"} 
Ответ при ошибке: {"status":"order 12345 not found"}

Создать сделку

POST https://chatter.mavibot.ai/api/#{api_key}/create_order

URL запроса: https://chatter.mavibot.ai/api/#{api_key}/create_order

Разрешение при создании ключа: "Разрешение на изменение/удаление информации CRM"

Путь

api key* - токен доступа

Body

client_id - ID клиента

name - название сделки

description - описание сделки

budget - сумма сделки

В запросе необходимо указать один из следующих параметров: client_id, email или phone. Если передано несколько параметров, будет использован только один. Приоритет такой: client_id > phone > email. Если указан phone или email и клиента с таким номером телефона или email не существует, будет создан новый клиент.

Успешный ответ: {"status":"success","order_id":40654}, 
где order_id — ID новой активной сделки.
Ответ при ошибке: {"status":"client_not_found"}

Перевести сделку на этап в MavibotCRM

POST https://chatter.mavibot.ai/api/#{api_key}/set_order_state

URL запроса: https://chatter.mavibot.ai/api/#{api_key}/set_order_state

Разрешение при создании ключа: "Разрешение на изменение/удаление информации CRM"

Путь

api key* - токен доступа

Body

client_id - ID клиента

state_id - номер этапа, на который нужно перевести сделку клиента

Получить ID этапа воронки в Mavibot CRM

GET https://chatter.mavibot.ai/api/#{api_key}/get_order_state

URL запроса: https://chatter.mavibot.ai/api/#{api_key}/get_order_state

Разрешение при создании ключа: "Разрешение на чтение информации CRM"

Путь

api key* - токен доступа

Body

client_id - ID клиента

state_id - ID сделки (если не указан, метод вернёт ID этапа текущей сделки)

Пример успешного ответа:
{'status': 'success', 'state_id': 123456}

Пример неуспешного ответа:
{'status': 'order not found'}

Какие ещё возможности доступны?

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

GET https://chatter.mavibot.ai/api/#{api_key}/check_whatsapp

URL запроса: https://chatter.mavibot.ai/api/#{api_key}/check_whatsapp

Для использования этого метода WhatsApp должен быть подключён к Mavibot.

Права доступа при генерации ключа: "Разрешение на изменение или удаление информации о клиенте".

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

Путь

api key* - токен доступа

Body

phone - номер телефона для проверки

Получить список мессенджеров, подключённых к проекту

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

URL запроса: https://chatter.mavibot.ai/api/<api_key>/connected_channels

Права доступа при генерации ключа: "Разрешение на изменение или удаление информации о клиенте".

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

Для WhatsApp также возвращается status поле, которое может принимать следующие значения:

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

Путь

api key* - токен доступа

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

Получить список блоков из сценария бота

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

URL запроса: https://chatter.mavibot.ai/api/<api_key>/get_messages

Права доступа при генерации ключа: "Разрешение на изменение или удаление информации о клиенте".

Путь

api key* - токен доступа

Получить вложенные данные клиента

delimiter

Чтобы получить client_id и/или номер телефона клиента из вложенных словарей (не на первом уровне), используйте параметр delimiter.

Добавьте следующее в URL запроса:

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

где:

?delimiter=1 – значение разделителя, который отделяет ключи {key1}1{key2}1{key3}

delimiter_value_client_id={key1}1{key2} – для получения ID клиента

delimiter_value_phone={key1}1{key2} – для получения номера телефона клиента

{key1}, {key2}, … – ключи, содержащие значения (могут включать любые символы, кроме разделителя). Количество ключей не ограничено: ?delimiter=1&delimiter_value_client_id={key1}1{key2}1{key3}1{key4}1{key5}1{key6}. Ключи передаются без фигурных скобок.

Используйте разделитель между ключами. Например, если delimiter=2, то {key1}2{key2}2{key3}; если delimiter=5, то {key1}5{key2}5{key3}. Убедитесь, что ключ не содержит символ разделителя.

Пример:

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

Также можно получить только ID или только номер телефона:

https://chatter.salebot.pro/api/<api_key>/callback?delimiter=1&delimiter_value_client_id={key1}1{key2} - только ID клиента;

https://chatter.salebot.pro/api/<api_key>/callback?delimiter=1delimiter_value_phone={key1}1{key2} - только номер телефона;

Методы API:

Запустить бота: https://chatter.mavibotbot.ai/api/<api_key>/callback
Запустить бота по номеру WhatsApp: https://chatter.mavibotbot.ai/api/<api_key>/whatsapp_callback
Запустить бота по Telegram ID: https://chatter.mavibotbot.ai/api/<api_key>/tg_callback
Отправить callback-сообщение клиенту по email: https://chatter.mavibotbot.ai/api/<api_key>/email_callback
Отправить сообщение клиенту: https://chatter.mavibotbot.ai/api/<api_key>/message
Отправить сообщение WhatsApp: https://chatter.mavibotbot.ai/api/<api_key>/whatsapp_message
Массовая рассылка: https://chatter.mavibotbot.ai/api/<api_key>/broadcast
Назначить переменные: https://chatter.mavibotbot.ai/api/<api_key>/save_variables

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

Последнее обновление 6 месяцев назад