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

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

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

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

Где:

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

<figure><img src="/files/df182f4d74bfbcf796ba07afbabe979885d5be17" alt=""><figcaption></figcaption></figure>

{% hint style="success" %}
Чтобы использовать токен в URL-запросе, сначала нужно сгенерировать ключ API.

Инструкция по этому приведена в разделе «Генерация ключа API». <mark style="color:красный;">**ссылка**</mark>
{% endhint %}

{% hint style="danger" %}
При копировании URL с этой страницы может появиться пробел, его нужно удалить.

Пример некорректной ссылки:
&#x20;<https://chatter.mavibot.pro> /api/callback

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

{% hint style="warning" %}
Не используйте запрещённые символы при отправке GET-запроса.

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

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

{% hint style="success" %}
Старая функция генерации ключа API по-прежнему работает как прежде, но недоступна для новых проектов.

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

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

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

<figure><img src="/files/5b2db39e4fd102588b4b923a4f068368e2438bca" alt="" width="301"><figcaption></figcaption></figure>

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

<figure><img src="/files/c1ef7e6f49fad11fafec758051c978f5f336514c" alt="" width="563"><figcaption></figcaption></figure>

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

<figure><img src="/files/3acb64a06a73740dc33a5d436b16aeb27b92663a" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/783914d3dcf2c85d66bdd27f2e29f576fc6859af" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/8246d82b11fe8f48c53f60990ba5682b17146d4e" alt=""><figcaption></figcaption></figure>

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

{% hint style="warning" %}
Обратите внимание!

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

<img src="/files/ec81f6f00042771fd932118eb2bd7ec5f76c31d8" alt="" data-size="original">
{% endhint %}

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

<figure><img src="/files/b04b20d9d147428a444785cf7f5fd990a24bbe44" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/1f2c70c9a7b583f3eeac4e0eff9de8aee06bf74c" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/8169779cd7eda2e2b530ce68e589f6fe4e384d2d" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/66114ce81a99b0696231c0551dde4c420d475ca9" alt=""><figcaption></figcaption></figure>

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

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

<figure><img src="/files/5709557fa45858b5326d87e0e96869aa37e08474" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/661f6219ac181927797ebaca104ed192da2ae3ef" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/41a32bf9c74df8aa75e11576a4b258fd7c440b22" alt=""><figcaption><p>URL запроса</p></figcaption></figure>

<figure><img src="/files/f174459a1bcbfda67656344cf9f461a4cafb66de" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/56c0ec1833534fbaadff6449f603b44024b4c765" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/60876eadc40e687471a1452c33a9223e36fb7b55" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Ключ API, созданный старым способом, по умолчанию назначается основным ключом проекта и имеет полные права.
{% endhint %}

{% hint style="danger" %}
Примечание!&#x20;

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

{% hint style="success" %}
Обратите внимание!&#x20;

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

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

![Настройки проекта](/files/63fae05699d422a403520d36ab34ac326144768e)

Каждое входящее или исходящее сообщение будет отправляться как следующий 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-запрос

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

<figure><img src="/files/fd7d93de34bbb20bbe404cf5f4f82d79ae6d5f9f" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/640a7fecb20690a17882b17303347b0dbd54766f" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/0079cafe7474ec7dda4b4322ee49e908329c1fbd" alt=""><figcaption></figcaption></figure>

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

> **request\_parameter -> your\_variable**
>
> Если ответ содержит параметры со сложной структурой, разбирайте их следующим образом:
>
> * > "cell\_number":{"row":4,"col":2}\
>   > \
>   > \
>   > cell\_number|row ->String; \
>   > cell\_number|col -> Column<br>

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

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

**{"client\_id": "#{recipient\_id\_in\_builder}", "message":"Hello!"}**

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

<figure><img src="/files/7aea92fd07d05d273510d06e6c757ea1626adbe1" alt=""><figcaption><p>Получение результата API-запроса в виде сообщения</p></figcaption></figure>

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

<figure><img src="/files/ee9fbfe6ec95a2bb1480198ef18770ed4c6be2d3" alt="" width="551"><figcaption></figcaption></figure>

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

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

* [callback](#zapusk-bota)
* [whatsapp\_callback](#zapusk-bota)
* [message](#otpravka-soobshenii)
* [whatsapp\_message](#otpravka-soobshenii)

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

Теперь вы можете указать, по какому параметру запроса SaleBot должен искать ID пользователя. Используйте параметр с префиксом **value\_**&#x43D;апример, **value\_user\_id** или **value\_group\_id**.

Кроме того, метод отправки callback теперь можно запускать также по email клиента (**client\_email**) или номеру телефона (**client\_phone**).

{% hint style="success" %}
Текст **callback**, **fb\_callback**, и **whatsapp\_callback** методы не привязаны к конкретным именам параметров. Вы можете указать, какой параметр содержит номер телефона, email или ID клиента.
{% endhint %}

Это полезно при настройке получения 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\_**.

{% hint style="warning" %}
Обратите внимание!&#x20;

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

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

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

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

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

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

<details>

<summary><mark style="color:зелёный;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/callback</summary>

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

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

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

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

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

<img src="/files/8bb2a03ea85a66622da5aaef5c001207aacb8581" alt="" data-size="original">

Путь

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

Body

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

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

client\_id - ID клиента в конструкторе

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

resume\_bot - True (необязательный параметр). Если бот приостановлен, это используется для его возобновления.&#x20;

Пример: 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)
```

</details>

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

<details>

<summary><mark style="color:зелёный;">POST</mark> https://chatter.mavibot.ai/api/&#x3C;api_key>/whatsapp_callback</summary>

URL запроса: <https://chatter.mavibot.ai/api/\\>\<api\_key>/whatsapp\_callback

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

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

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

<img src="/files/8bb2a03ea85a66622da5aaef5c001207aacb8581" alt="" data-size="original">

Путь

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

Body

name - имя клиента\
message - текст сообщения\
phone - номер телефона клиента\
bot\_id - ID бота\
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.

</details>

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

<details>

<summary><mark style="color:зелёный;">POST</mark> https://chatter.mavibot.pro/api/#{api_key}/tg_callback</summary>

URL запроса: <https://chatter.mavibot.pro/api/#{api\\_key}/tg\\_callback>

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

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

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

<img src="/files/8bb2a03ea85a66622da5aaef5c001207aacb8581" alt="" data-size="original">

Путь

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

Body

message - текст сообщения\
user\_id - Telegram ID пользователя\
group\_id - имя бота (оканчивается на bot)\
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.

</details>

### Отправка callback-сообщений списку клиентов по platform\_id

<details>

<summary><mark style="color:зелёный;">POST</mark>  https://chatter.mavibot.ai/api/#{api_key}/send_callback_by_platform_id</summary>

URL запроса: <https://chatter.mavibot.ai/api/#{api\\_key}/send\\_callback\\_by\\_platform\\_id>

Когда в проекте найдены клиенты с platform\_id из списка, будет отправлен callback с текстом из поля callback\_text.\
\ <mark style="color:красный;">**Лимит: 1 запрос = максимум 300 отправок**</mark>&#x20;

Пример параметров запроса:\
{"platform\_ids":\[407184121, "79609879898", "2rwewefw"], "callback\_text": "test\_callback"}

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

<img src="/files/8bb2a03ea85a66622da5aaef5c001207aacb8581" alt="" data-size="original">

Путь

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

Body

platform\_ids - список ID клиентов в мессенджере\
callback\_text - текст callback\
group\_id - ID бота

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

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

</details>

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

<details>

<summary><mark style="color:зелёный;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/email_callback</summary>

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

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

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

<img src="/files/8bb2a03ea85a66622da5aaef5c001207aacb8581" alt="" data-size="original">

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

Путь

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

Body

name - имя клиента\
message - текст сообщения\
email - адрес электронной почты\
email\_id\_bot - email бота\
resume\_bot - True (необязательный параметр).&#x20;

Если бот приостановлен, используйте это для его возобновления. Пример: 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.

</details>

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

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

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

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

<details>

<summary><mark style="color:зелёный;">POST</mark>  https://chatter.mavibot.ai/api/#{api_key}/message</summary>

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

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

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

<img src="/files/8bb2a03ea85a66622da5aaef5c001207aacb8581" alt="" data-size="original">

Путь

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

Body

message\_id - номер блока для отправки\
message - текст сообщения\
client\_id - ID клиента в конструкторе\
attachment\_type - тип отображения файла. Обязателен, если указан attachment\_url.\
attachment\_url - URL файла\
buttons - кнопки

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.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'
# в зависимости от типа вложения: видео, изображение или документ.
```

</details>

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

<details>

<summary><mark style="color:зелёный;">POST</mark> https://chatter.salebot.pro/api/&#x3C;api_key>/whatsapp_message</summary>

URL запроса: <https://chatter.mavibot.pro/api/\\>\<api\_key>/whatsapp\_message

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

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

<img src="/files/8bb2a03ea85a66622da5aaef5c001207aacb8581" alt="" data-size="original">

Путь

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

Body

message\_id - номер блока для отправки\
whatsapp\_bot\_id - ID WhatsApp-бота, от имени которого должно быть отправлено сообщение\
attachment\_url - URL файла\
attachment\_type - тип отображения файла. Обязателен, если указан attachment\_url.\
message - текст сообщения\
phone - номер телефона получателя

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", "phone": "79875146788"}
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/whatsapp_message'
requests.post(url, json=params)
```

</details>

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

<details>

<summary><mark style="color:зелёный;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/broadcast</summary>

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

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

Вы можете использовать <mark style="color:красный;">**один из следующих взаимоисключающих вариантов**</mark>:

1. параметр list — рассылка будет отправлена в указанный список клиентов.
2. параметр clients — рассылка будет отправлена массиву ID клиентов.
3. параметры platform\_ids и group\_id — рассылка будет отправлена массиву platform\_ids (ID в мессенджере) для указанного бота (group\_id).
4. Если ни один из перечисленных выше параметров не указан, рассылка отправлена не будет.

Обязательные параметры: message (и/или attachment\_type и attachment\_url) или message\_id.

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

<img src="/files/8bb2a03ea85a66622da5aaef5c001207aacb8581" alt="" data-size="original">

**Путь**

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.

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", "clients": ["5", "58", "110"]}
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/broadcast'
requests.post(url, json=params)
```

</details>

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

<details>

<summary><mark style="color:синий;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/get_history?client_id=</summary>

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

Параметр client\_id можно получить здесь. <mark style="color:красный;">**ссылка**</mark>

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

<img src="/files/7bc523f54f7b5ec28fe885b4110247f3d87138d9" alt="" data-size="original">

**Путь**

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

**Body**

client\_id - ID клиента

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

start\_date - начальная дата периода выборки (обязательно, если указан stop\_date), формат: dd.mm.yyyy&#x20;

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": "example@mail.com"
    },
  ]
}
```

</details>

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

<details>

<summary><mark style="color:синий;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/clear_history?client_id=</summary>

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

Удаляет историю чата&#x20;

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

<img src="/files/8bb2a03ea85a66622da5aaef5c001207aacb8581" alt="" data-size="original">

**Путь**

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

</details>

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

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

<details>

<summary><mark style="color:зелёный;">POST</mark>  https://chatter.mavibot.ai/api/#{api_key}/assign_to_user</summary>

URL запроса: <https://chatter.mavibot.ai/api/#{api\\_key}/assign\\_to\\_user>

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

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

<img src="/files/8bb2a03ea85a66622da5aaef5c001207aacb8581" alt="" data-size="original">

**Путь**

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

**Body**

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

```
import requests
import json

params = {"client_id":"#{client_id}","email":"xxxxx@mail.ru"}
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/broadcast'
requests.post(url, json=params)
```

</details>

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

<details>

<summary><mark style="color:зелёный;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/load_clients</summary>

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 — пустая строка: ""). <mark style="color:красный;">**ссылка**</mark>

Тип мессенджера, из которого пришёл клиент (client\_type), можно найти ЗДЕСЬ. <mark style="color:красный;">**ссылка**</mark>

Пример: \[{"platform\_id":"79875555555","group\_id":34810,"client\_type":6}]

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

<img src="/files/8bb2a03ea85a66622da5aaef5c001207aacb8581" alt="" data-size="original">

**Путь**

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":"79538550785@s.whatsapp.net", "group_id": "1hwF7lwEjv4SKYIGFhQnBw==", "client_type": 6}]
requests.post(url, json=params)
# если операция успешна, функция вернёт ID и статус добавления для каждого элемента
# пример ответа
# {"status":"success","items":[{"platform_id":"700000000@s.whatsapp.net","group_id":"5kqchxwyvdvFZOsp80q2qw==","client_type":6,"status":"success","id":1469409}]}
```

</details>

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

<details>

<summary><mark style="color:зелёный;">POST</mark> https://chatter.mavibot.ai/api/&#x3C;api_key>/add_to_list</summary>

URL запроса: <https://chatter.mavibot.ai/api/\\>\<api\_key>/add\_to\_list

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

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

<img src="/files/8bb2a03ea85a66622da5aaef5c001207aacb8581" alt="" data-size="original">

**Путь**

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

**Body**

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

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

</details>

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

<details>

<summary><mark style="color:зелёный;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/remove_from_list</summary>

URL запроса: <https://chatter.mavibot.ai/api/#{api\\_key}/remove\\_from\\_list>

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

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

<img src="/files/8bb2a03ea85a66622da5aaef5c001207aacb8581" alt="" data-size="original">

**Путь**

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

**Body**

list\_id - номер списка\
clients - массив номеров клиентов в конструкторе Mavibot (значения client\_id)

</details>

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

<details>

<summary><mark style="color:синий;">GET</mark> https://chatter.mavibot.ai/api/&#x3C;api_key>/get_clients</summary>

**URL запроса:** <https://chatter.mavibot.a/aipi/\\>\<api\_key>/get\_clients

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

<img src="/files/7bc523f54f7b5ec28fe885b4110247f3d87138d9" alt="" data-size="original">

**Путь**

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

</details>

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

<details>

<summary><mark style="color:синий;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/subscribers</summary>

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

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

*<mark style="color:красный;">Примечание!</mark>* Этот метод не возвращает переменные.

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

<img src="/files/7bc523f54f7b5ec28fe885b4110247f3d87138d9" alt="" data-size="original">

**Путь**

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

</details>

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

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

<details>

<summary><mark style="color:зелёный;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/save_variables</summary>

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

&#x20;<mark style="color:зелёный;">**!**</mark>**&#x20;**<mark style="color:$success;">**На этот запрос ограничение не распространяется.**</mark>&#x20;

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

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

<img src="/files/7bc523f54f7b5ec28fe885b4110247f3d87138d9" alt="" data-size="original">

**Обновить**: Параметр 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)
```

</details>

### Получить переменные

<details>

<summary><mark style="color:синий;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/get_variables?client_id=</summary>

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

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

<img src="/files/7bc523f54f7b5ec28fe885b4110247f3d87138d9" alt="" data-size="original">

Пример: <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)
```

</details>

## Как получить ID клиента (client\_id)

### Получить client\_id по значению platform\_id

<details>

<summary><mark style="color:зелёный;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/find_client_id_by_platform_id</summary>

**URL запроса:** <https://chatter.mavibot.ai/api/#{api\\_key}/find\\_client\\_id\\_by\\_platform\\_id>

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

<img src="/files/7bc523f54f7b5ec28fe885b4110247f3d87138d9" alt="" data-size="original">

**Путь**

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

</details>

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

<details>

<summary><mark style="color:синий;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/online_chat_client_id?recipient=</summary>

URL запроса: <https://chatter.mavibot.ai/api/#{api\\_key}/online\\_chat\\_client\\_id?recipient=>

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

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

<img src="/files/8bb2a03ea85a66622da5aaef5c001207aacb8581" alt="" data-size="original">

**Путь**

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

**Body**

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

#### Где взять **recipient?**&#x20;

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

<img src="/files/5123ad7bc2f5cb2fc39b620c7271f8707671e1da" alt="" data-size="original">

```
{ "client_id": 36553 }
```

</details>

### Получить client\_id по номеру WhatsApp

<details>

<summary><mark style="color:синий;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/whatsapp_client_id?phone=</summary>

URL запроса: <https://chatter.mavibot.ai/api/#{api\\_key}/whatsapp\\_client\\_id?phone=>

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

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

<img src="/files/7bc523f54f7b5ec28fe885b4110247f3d87138d9" alt="" data-size="original">

**Путь**

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

**Body**

phone - номер телефона\
group\_id - ID бота

</details>

### Получить client\_id по номеру телефона

<details>

<summary><mark style="color:синий;">GET</mark> https://chatter.mavibot.ai/api/&#x3C;api_key>/find_client_id_by_phone?phone= </summary>

URL запроса: <https://chatter.mavibot.ai/api/\\>\<api\_key>/find\_client\_id\_by\_phone?phone=&#x20;

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

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

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

<img src="/files/7bc523f54f7b5ec28fe885b4110247f3d87138d9" alt="" data-size="original">

**Путь**

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

**Body**

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

</details>

### Получить client\_id по email

<details>

<summary><mark style="color:синий;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/find_client_id_by_email?email= </summary>

URL запроса: <https://chatter.mavibot.ai/api/#{api\\_key}/find\\_client\\_id\\_by\\_email?email=&#x20>;

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

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

<img src="/files/7bc523f54f7b5ec28fe885b4110247f3d87138d9" alt="" data-size="original">

**Путь**

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

**Body**

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

</details>

### Получить client\_id по значению переменной

<details>

<summary><mark style="color:синий;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/find_client_id_by_var?var=&#x26;val=</summary>

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

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

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

<img src="/files/7bc523f54f7b5ec28fe885b4110247f3d87138d9" alt="" data-size="original">

**Путь**

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

**Body**

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

</details>

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

<details>

<summary><mark style="color:синий;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/find_latest_client_id_by_var?var=&#x26;val=</summary>

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

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

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

<img src="/files/7bc523f54f7b5ec28fe885b4110247f3d87138d9" alt="" data-size="original">

**Путь**

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

**Body**

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

</details>

### Получить список значений client\_id по значению переменной

<details>

<summary><mark style="color:синий;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/find_all_client_id_by_var?var=&#x26;val=</summary>

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

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

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

<img src="/files/7bc523f54f7b5ec28fe885b4110247f3d87138d9" alt="" data-size="original">

**Путь**

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

**Body**

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

```
{
    // Ответ
}
```

</details>

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

<details>

<summary><mark style="color:синий;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/find_all_client_id_by_several_vars?var=val</summary>

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

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

<img src="/files/7bc523f54f7b5ec28fe885b4110247f3d87138d9" alt="" data-size="original">

**Путь**

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

**Body**

variable1 - Value1

variable2 - Value2

variable3 - Value3

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

</details>

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

<details>

<summary><mark style="color:зелёный;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/find_clients</summary>

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

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

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

<img src="/files/7bc523f54f7b5ec28fe885b4110247f3d87138d9" alt="" data-size="original">

Параметры

**Путь**

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

</details>

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

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

<details>

<summary><mark style="color:синий;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/get_current_order_id</summary>

**URL запроса:** <https://chatter.mavibot.ai/api/#{api\\_key}/get\\_current\\_order\\_id>

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

<img src="/files/bfdbd22785651e0e757c69669598976e9c9b82b1" alt="" data-size="original">

**Путь**

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

**Body**

client\_id - ID клиента

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

</details>

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

<details>

<summary><mark style="color:синий;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/get_orders</summary>

**URL запроса:** <https://chatter.mavibot.ai/api/#{api\\_key}/get\\_orders>

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

<img src="/files/bfdbd22785651e0e757c69669598976e9c9b82b1" alt="" data-size="original">

**Путь**

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

**Body**

client\_id - ID клиента

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

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

</details>

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

<details>

<summary><mark style="color:зелёный;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/move_order_to_next_state</summary>

**URL запроса:** <https://chatter.mavibot.ai/api/#{api\\_key}/move\\_order\\_to\\_next\\_state>

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

<img src="/files/b5fcabc01c10b028a94b911f10d6322e0d2f1864" alt="" data-size="original">

**Путь**

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

**Body**

client\_id - ID клиента

**order\_id** - ID сделки

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

</details>

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

<details>

<summary><mark style="color:зелёный;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/get_order_vars</summary>

**URL запроса:** <https://chatter.mavibot.ai/api/#{api\\_key}/get\\_order\\_vars>

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

<img src="/files/bfdbd22785651e0e757c69669598976e9c9b82b1" alt="" data-size="original">

**Путь**

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

</details>

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

<details>

<summary><mark style="color:зелёный;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/set_order_vars</summary>

**URL запроса:** <https://chatter.mavibot.ai/api/#{api\\_key}/set\\_order\\_vars>

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

<img src="/files/b5fcabc01c10b028a94b911f10d6322e0d2f1864" alt="" data-size="original">

**Путь**

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

**Body**

client\_id - ID клиента

**order\_id** - ID сделки

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

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

</details>

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

<details>

<summary><mark style="color:зелёный;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/create_order</summary>

**URL запроса:** <https://chatter.mavibot.ai/api/#{api\\_key}/create\\_order>

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

<img src="/files/b5fcabc01c10b028a94b911f10d6322e0d2f1864" alt="" data-size="original">

**Путь**

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

</details>

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

<details>

<summary><mark style="color:зелёный;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/set_order_state</summary>

**URL запроса:** <https://chatter.mavibot.ai/api/#{api\\_key}/set\\_order\\_state>

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

<img src="/files/b5fcabc01c10b028a94b911f10d6322e0d2f1864" alt="" data-size="original">

**Путь**

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

**Body**

client\_id - ID клиента

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

</details>

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

<details>

<summary><mark style="color:синий;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/get_order_state</summary>

**URL запроса:** <https://chatter.mavibot.ai/api/#{api\\_key}/get\\_order\\_state>

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

<img src="/files/bfdbd22785651e0e757c69669598976e9c9b82b1" alt="" data-size="original">

**Путь**

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

**Body**

client\_id - ID клиента

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

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

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

</details>

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

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

<details>

<summary><mark style="color:синий;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/check_whatsapp</summary>

**URL запроса:** <https://chatter.mavibot.ai/api/#{api\\_key}/check\\_whatsapp>

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

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

<img src="/files/7bc523f54f7b5ec28fe885b4110247f3d87138d9" alt="" data-size="original">

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

**Путь**

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

**Body**

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

</details>

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

<details>

<summary><mark style="color:синий;">GET</mark> https://chatter.mavibot.ai/api/&#x3C;api_key>/connected_channels</summary>

URL запроса: <https://chatter.mavibot.ai/api/\\>\<api\_key>/connected\_channels

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

<img src="/files/7bc523f54f7b5ec28fe885b4110247f3d87138d9" alt="" data-size="original">

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

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

**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'}]
}
```

</details>

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

<details>

<summary><mark style="color:синий;">GET</mark> https://chatter.mavibot.ai/api/&#x3C;api_key>/get_messages</summary>

**URL запроса:** <https://chatter.mavibot.ai/api/\\>\<api\_key>/get\_messages

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

<img src="/files/7bc523f54f7b5ec28fe885b4110247f3d87138d9" alt="" data-size="original">

**Путь**

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

</details>

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

<details>

<summary>delimiter</summary>

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

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

?delimiter=1\&delimiter\_value\_client\_id={key1}1{key2}\&delimiter\_value\_phone={key1}1{key2}&#x20;

где:

?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<mark style="color:жёлтый;">**?delimiter=1\&delimiter\_value\_client\_id={key1}1{key2}\&delimiter\_value\_phone={key1}1{key2}**</mark>&#x20;

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

<https://chatter.salebot.pro/api/\\>\<api\_key>/callback<mark style="color:зелёный;">**?delimiter=1\&delimiter\_value\_client\_id={key1}1{key2} -**</mark> только ID клиента;

<https://chatter.salebot.pro/api/\\>\<api\_key>/callback<mark style="color:зелёный;">**?delimiter=1delimiter\_value\_phone={key1}1{key2}**</mark> - только номер телефона;

Методы API:

1. Запустить бота: <https://chatter.mavibotbot.ai/api/\\>\<api\_key>/callback
2. Запустить бота по номеру WhatsApp: <https://chatter.mavibotbot.ai/api/\\>\<api\_key>/whatsapp\_callback
3. Запустить бота по Telegram ID: <https://chatter.mavibotbot.ai/api/\\>\<api\_key>/tg\_callback
4. Отправить callback-сообщение клиенту по email: <https://chatter.mavibotbot.ai/api/\\>\<api\_key>/email\_callback
5. Отправить сообщение клиенту: <https://chatter.mavibotbot.ai/api/\\>\<api\_key>/message
6. Отправить сообщение WhatsApp: <https://chatter.mavibotbot.ai/api/\\>\<api\_key>/whatsapp\_message
7. Массовая рассылка: <https://chatter.mavibotbot.ai/api/\\>\<api\_key>/broadcast
8. Назначить переменные: <https://chatter.mavibotbot.ai/api/\\>\<api\_key>/save\_variables
   \\

</details>

{% hint style="success" %}
Если вам нужны дополнительные методы, пожалуйста, свяжитесь со службой поддержки.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mavibot.ai/doc/ru/rabota-s-api/konstruktor-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.