Запити виконуються методом 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 можна запустити, передавши електронну пошту (client_email) та номер телефону клієнта (client_phone).

Методи callback та whatsapp_callback не прив'язані до назв параметрів. Ви можете вказати, який параметр міститиме номер телефону, електронну пошту та 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

Метод можна використовувати для запуску робочого процесу для клієнта або для підтвердження дії на сторонньому сервісі. Це повідомлення не буде видимим для клієнта.
Додатково передані параметри зберігаються у змінних.
Метод надсилання зворотного виклику тепер можна ввімкнути, поділившись електронною поштою (client_email) або номером телефону клієнта (client_phone)

Параметри шляху

Назва Тип Опис
api_key рядок токен доступу

Тіло запиту

Назва Тип Опис
client_phone рядок номер телефону, за яким знаходиться клієнт
client_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 після того, як клієнт зареєструється через сайт або залишить заявку зі своїм номером телефону
Додатково передані параметри зберігаються у змінних

Параметри шляху

Назва Тип Опис
api_key рядок токен доступу

Тіло запиту

Назва Тип Опис
name рядок ім'я клієнта
message рядок текст повідомлення
phone рядок номер телефону клієнта
bot_id рядок id бота

**200: OK **

{
    // Відповідь
}

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

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

Метод можна використовувати для запуску робочого процесу або підтвердження дій на сторонньому сайті. Це повідомлення не буде видимим для клієнта.

Додатково передані параметри зберігаються у змінних

Параметри шляху

Назва Тип Опис
api_key рядок токен доступу

Тіло запиту

Назва Тип Опис
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 є обов'язковим, якщо ви не надсилаєте файл. Якщо ви надсилаєте файл, то текст не потрібен

Параметри шляху

Назва Тип Опис
api_key рядок ключ доступу

Тіло запиту

Назва Тип Опис
message_id рядок номер блоку надсилання
message рядок текст повідомлення
client_id рядок id клієнта в редакторі
attachment_type рядок тип відображення файлу
attachment_url рядок URL файлу
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 отримує унікальну ідентифікацію

Параметри шляху

Назва Тип Опис
api_key рядок ключ доступу

Тіло запиту

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

Параметри шляху

Назва Тип Опис
api_key string ключ доступу

Тіло запиту

Назва Тип Опис
message_id string номер блоку надсилання
list string список номерів отримувачів
shift string кількість секунд між повідомленнями. 0.2 за замовчуванням
message string текст повідомлення
clients array ідентифікатори отримувачів
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 ідентифікатор клієнта

**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 ідентифікатор клієнта

**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 ідентифікатор клієнта
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 в кінці або без нього.

Ви можете отримати ідентифікатор групи (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 ідентифікатор групи
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)
# у разі успіху функція повертає для кожного елемента його ідентифікатор та статус додавання
# приклад відповіді
# {"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 **

{
    // Відповідь
}

Видалення клієнтів зі списку

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

Параметри шляху

Назва Тип Опис
api_key string ключ доступу

Тіло запиту

Назва Тип Опис
list_id integer номер списку
clients array масив номерів клієнтів

**200: OK **

{
    // Відповідь
}

Отримання списку клієнтів

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 ідентифікатор групи, до якої прив'язаний підписник
date_from integer мітка часу дати, після якої вони підписалися
date_to integer мітка часу дати, до якої вони підписалися
client_type integer ідентифікатор месенджера, для якого потрібен список підписників. якщо нічого не змінювати, відображаються всі клієнти

**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 — список ідентифікаторів клієнтів для видалення. Максимум 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 масив ідентифікаторів клієнтів для присвоєння змінних
client_id string ідентифікатор клієнта
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 ідентифікатор клієнта

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

Метод повертає ідентифікатор клієнта для виконання запитів до API

Приклад параметрів: {"platform_ids": ["571830542", "256865200"]}

Параметри шляху

Ім'я Тип Опис
string ключ доступу

Тіло запиту

Ім'я Тип Опис
platform_ids string масив ідентифікаторів у месенджері

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

Як отримати ідентифікатор клієнта в онлайн-чаті

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

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

Параметри шляху

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

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

Ім'я Тип Опис
tag string тег клієнта
name string ім'я клієнта
recipient string ідентифікатор діалогу на сайті

**200: OK **

{ "client_id": 36553 }

Звідки взяти отримувача? На сайті, який використовує онлайн-чат "Mavibot.ai", потрібно отримати функцію MaviBotPro.recipient_id за допомогою JS.

Як отримати ідентифікатор клієнта за номером WhatsApp

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

Метод повертає ідентифікатор клієнта для виконання запитів до API, якщо ви знаєте номер телефону клієнта у WhatsApp.
Якщо такого клієнта з цим номером не існує, ви отримаєте 404.

Параметри шляху

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

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

Ім'я Тип Опис
phone string номер телефону

**200: OK **

{
    // Відповідь
}

Отримання ідентифікатора клієнта за номером телефону

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

Метод повертає ідентифікатор клієнта для виконання запитів до API.
Пошук відбувається серед клієнтів WhatsApp, а також через змінні.

Параметри шляху

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

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

Ім'я Тип Опис
phone string номер телефону

**200: OK **

{
    // Відповідь
}

Отримання ідентифікатора клієнта через електронну пошту

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

Метод повертає ідентифікатор клієнта для виконання запитів до API. Пошук відбувається через змінні.

Параметри шляху

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

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

Ім'я Тип Опис
email string електронна пошта для пошуку

**200: OK **

{
    // Відповідь
}

Отримання ідентифікатора клієнта за значенням змінної

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

Метод повертає ідентифікатор клієнта для виконання запитів до API

Параметри шляху

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

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

Ім'я Тип Опис
var string назва змінної, за якою буде здійснюватися пошук
val string значення змінної

**200: OK **

{
    // Відповідь
}

Які ще є можливості

Переведення транзакції в стан MavibotCRM

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

Номер транзакції можна отримати у вікні редагування робочого процесу MavibotCRM.

Параметри шляху

Ім'я Тип Опис
api_key string ключ доступу

Тіло запиту

Ім'я Тип Опис
client_id string ідентифікатор клієнта
state_id string номер стану, в який потрібно перевести транзакцію клієнта

**200: OK **

{
    // Відповідь
}

Перевірка, чи підписана людина на обліковий запис 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 **

{
    // Відповідь
}

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

{
    // Відповідь
}

Якщо вам потрібні додаткові методи, зверніться до служби підтримки