# Bot API

### Концепция

Бот представляет из себя независимое приложение со собственной бизнес-логикой, моделью данных и состоянием диалога.

Для того чтобы управлять поведением бота из внешних систем вам необходимо запланировать работу (job) с помощью Bot API.

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

Гибкость достигается это за счет использования встроенного языка программирования JavaScript и системы триггеров.

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

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

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

### Доступ к API

Swagger доступен по адресу: <https://app.metabot24.com/api/docs>

Чтобы получить доступ, достаточно зарегистрировать любой аккаунт на платформе <https://app.metabot24.com>, затем создать бот и перейти в раздел пользователей бота <https://app.metabot24.com/user> и там создать API пользователя.

Ниже описан основной метод работы с ботом.

## Schedule

<mark style="color:green;">`POST`</mark> `https://test.cakes.com/bots/{botId}/jobs/schedule`

Основной метод для планирования в боте работы.

#### Path Parameters

| Name  | Type   | Description    |
| ----- | ------ | -------------- |
| botId | number | ID вашего бота |

#### Headers

| Name           | Type   | Description                                                                                       |
| -------------- | ------ | ------------------------------------------------------------------------------------------------- |
| Authentication | string | Ваш токен аутентификации. Настраивается в панели администратора в разделе "Пользователи бизнеса". |

#### Request Body

| Name                    | Type    | Description                                                                                                                                                                                                         |
| ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| script\_id              | integer | ID скрипта (сценария диалога) для запуска, например, 1                                                                                                                                                              |
| trigger\_id             | integer | ID триггера для запуска, например, 1                                                                                                                                                                                |
| broadcast\_id           | integer | ID рассылки для запуска, например, 1                                                                                                                                                                                |
| script\_code            | string  | Кодовое имя сценария диалога для запуска, например, "script\_short\_code"                                                                                                                                           |
| trigger\_code           | string  | Кодовое имя триггера для запуска, например, "script\_short\_code"                                                                                                                                                   |
| broadcast\_code         | string  | Кодовое имя рассылки для запуска, например, "broadcast\_short\_code"                                                                                                                                                |
| lead\_id                | integer | ID лида/пользователя для которого выполняем работу, например, 135                                                                                                                                                   |
| ticket\_id              | integer | ID тикета/таблицы в модели данных для которой выполняем работу, например, 7                                                                                                                                         |
| run\_at                 | string  | Время выполнения в формате "ГГГГ-ММ-ДД чч:мм:сс", например,  "2021-01-21 21:00:00"                                                                                                                                  |
| run\_after\_sec         | integer | Отсрочка выполнения в секундах, например, 300                                                                                                                                                                       |
| is\_periodic            | boolean | Необходимо ли повторять работу, например, false                                                                                                                                                                     |
| condition\_script\_code | string  | <p>Условие выполнения работы в виде JavaScript кода, например "if (leadId == 135) return true;"<br><br>Работа будет запланирована и выполнена только при условии, что код условия вернет истину (true).</p>         |
| script\_request\_params | object  | <p>JSON-объект с входными параметрами к которым можно обратиться из триггера, скрипта или рассылки, например:<br>{ <br>  "first\_param": 7,<br>  "second\_param": {<br>    "any\_key": "any\_value"<br>  }<br>}</p> |
| add\_tags               | string  | Список тэгов, которыми необходимо пометить пользователя, например, 'tag1,tag2'                                                                                                                                      |
| remove\_tags            | string  | Cписок тэгов, которые необходимо удалить у пользователя 'tag1,tag2'                                                                                                                                                 |

{% tabs %}
{% tab title="200 Cake successfully retrieved." %}

```
{    "name": "Cake's name",    "recipe": "Cake's recipe name",    "cake": "Binary cake"}
```

{% endtab %}

{% tab title="404 Could not find a cake matching this query." %}

```
{    "message": "Ain't no cake like that."}
```

{% endtab %}
{% endtabs %}


---

# 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://metabot.gitbook.io/documentation/integracionnye-vozmozhnosti/bot-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.