| Поле | Описание |
| Флаг активности | Если убрать флаг, то при обращению через API к данному endpoint будет возвращена ошибка. |
| Алиас | Дополнительный уникальный идентификатор. Используется как часть URL-адреса для обращения к конечной точке через API, а также для вызова в JavaScript функциях. Разрешенные символы: буква, цифра, подчеркивание, дефис, слэш (косая черта) Шаблон URL-адреса конечной точки: https://адресплатформы/api/v1/bots/**{bot\_id}**/call/**{alias}** Для каждого бота создается свое пространство имен для API, что означает Алиас должен быть уникален в пределах бота. |
| JavaScript для вычисления API ответа (Response Body) | JavaScript для вычисления содержимого API ответа. Данный JS код будет выполнен при обращении к внутреннему API (по алиасу), результат выполнения кода будет являться телом ответа на API запрос. Это значит, что API ответ вычисляется на основе JavaScript. В JavaScript должен присутствовать ключевой оператор return для возврата значения из JS. Выражение которое указывается после return является ответом (Response Body) на API запрос. Можно возвращать: - Строку (будет сконвертирована в json, если формат валидный); - Массив; - Объект (в том числе JSON-объект). Пример: ```JavaScript return { "key": "value", "lead_name": lead.getData('name'), "request_param_name": request.json.name }; ``` В JS можно выполнять любой код, например обращаться к пользователям, или устанавливать переменные в memory, планировать задания бота (триггеры, рассылки, скрипты), а также вызывать внешнее API c помощью api.callEndpoint или другие методов объекта api: post/get/postJson/getJson/request. |
| Комментарий | Любой текст. Доступно указание любых HTML-тэгов. |
На данный момент доступен вызов кастомного внутреннего API только с методом POST и в формате JSON. Методы GET, PUT, PATCH, DELETE не поддерживаются.
[](https://docs.metabot24.ru/uploads/images/gallery/2022-11/ftwxa6XXu4o6Fvpg-2.png)Список всех конечных точек внутреннего API сортируется по следующим полям: наименование, алиас, id. Поэтому вы можете управлять сортировкой записей изменяя наименование или алиас. В будущем будет добавлена произвольная сортировка.
#### Вызов внутреннего API Узнать структуру запроса и проверить работу внутреннего API можно c помощью Swagger, доступного по адресу платформы. Если платформа устанавливается в контуре вашей сети, то адрес сервера нужно узнать у вашей ИТ службы. [API публичного сервиса](https://app.metabot24.com/api/docs.) под управлением нашей команды можно посмотреть по ссылке.Чтобы получить доступ к Swagger к публичному серверу, нужно **[зарегистрировать аккаунт](https://app.metabot24.com/register)** на платформе по ссылке, затем подтвердить электронную почту и авторизоваться на платформе.
**Внимание!** При работе в Swagger платформы будут выполняться реальные API запросы, а не эмуляция API.
[](https://docs.metabot24.ru/uploads/images/gallery/2022-11/MohapVGZvUKxJZKJ-3.png) Также проверить работу внутреннего API можно c помощью Postman или любого другого софта для тестирования API.  ##### Параметры запроса В URL запроса нужно указать идентификатор бота **botId** на платформе и **alias** внутреннего эндпоинта в боте. В теле запроса размещаются данные запроса, например: ```JSON { "lead_id": 135, "ticket_id": 7, "trigger_id": 1, "trigger_code": "trigger_short_code", "script_request_params": { "first_param": 7, "second_param": { "any_key": "any_value" } } } ``` С параметрами тела запроса к внутреннему эндпоинту можно ознакомиться в таблице ниже.| Поле | Обязательность заполнения | Описание |
| lead\_id | - | В JS будет подготовлен и доступен полноценный объект lead, если у лида есть персона, то также будет доступен объект person. |
| ticket\_id | - | В JS будет подготовлен и доступен полноценный объект ticket. |
| trigger\_id или trigger\_code | - | В JS будут доступны переменные triggerId, triggerName. |
| script\_request\_params | - | В JS будет подготовлены и доступны полноценные объекты request и last\_request. |
Если вдруг не найдете опцию создания API токена в вашем аккаунте, запросите токен в поддержке.
### Внешнее API [](https://docs.metabot24.ru/uploads/images/gallery/2022-11/iTmbNhJvBOIImY87-5.png) При создании новой конечной точки открывается окно создания со следующими параметрами: [](https://docs.metabot24.ru/uploads/images/gallery/2022-11/WUSUpqPVTdfeTzS4-6.png) [](https://docs.metabot24.ru/uploads/images/gallery/2022-11/gT3v2Uc0wp2st5Wu-7.png) #### Вызов внешнего API из чат-бота Метод для вызова внешнего API из JavaScript: ```JavaScript api.callEndpoint( string $externalApiEndpointCode, string|null $uri = null, string|null $method = null, string|null $format = null, array|object|string|null $body = null, array|object|string|null $headers = [], array|object|string|null $requestOptions = [], array|object|string|null $httpClientConfig = [], string|null $proxyUrl = null ): array|string|null ``` ##### Пример №1 вызова внешнего API из JavaScript ```JavaScript response = api.callEndpoint("endpoint_1"); ``` Параметры переданные в аргументах функции callEndpoint обладают наивысшим приоритетом, т.е. при подготовке параметров они идут перед теми, которые заданы другим способом, например, в настройках конечной точки или с помощью api сеттеров setHeaders / setRequestOptions / и т.д., или системными атрибутами бота. При этом, все параметры суммируются в порядке приоритетов, за исключением тела запроса $body. Если аргумент $body указан в функции, то JS код из настроек конечной точки не учитывается, и в API в качестве тела запроса будет передано то, что указано в аргументе $body функции callEndpoint. Таким образом, $body можно вычислить заранее (или хранить где-то в атрибутах или таблице) и передавать в аргументе функции или вычислять его в скрипте который вызывает api.callEndpoint, а не вычислять во вложенном JS самого эндпоинта. Если перекрываем $body — то JS из эндпоита вызываться не будет для вычисления тела запроса, т.к. тело перекрыто аргументом обладающим наивысшим приоритетом. ##### Пример №2 вызова внешнего API из JavaScript с перекрытием $body и других параметров ``` api.setHeaders({"Token": "my token"}); response = api.callEndpoint("endpoint_2", null, 'POST', 'TEXT', "MY BODY TEXT"); ``` URL конечной точки заданный в настройках внешнего API (в интерфейсе) будет задействован, только если не указан $uri в аргументах функции (для второго по счету аргумента функции callEndpoint задан параметр null). Таким образом пустая строка в аргументе для URL перекрывает параметры указанные в настройках точки. #### Структура конечной точки внешнего API Описание полей внешнего эндпоинта представлена в таблице ниже.| Поле | Описание |
| Флаг активности | Если убрать флаг, то вызов данного Endpoint не будет выполняться и метод api.callEndpoint(...) вернет null. |
| Код | Дополнительный уникальный идентификатор. Используется для указания объекта, например, в JavaScript функциях. В этом случае Код, используется как первый аргумент ($externalApiEndpointCode) метода api.callEndpoint(...). Для каждого бота создается свое пространство имен для внешнего API, это значит что Код должен быть уникален в пределах бота. |
| URL конечной точки (Endpoint URL) | Допустимо использование макропеременных. |
| JavaScript для вычисления API запроса (Request Body) | JavaScript для вычисления содержимого API запроса. Данный скрипт будет выполнен перед обращением к внешнему API, результат выполнения скрипта будет являться телом запроса к внешнему API. Это значит, что тело API запроса вычисляется на основе JavaScript. В JavaScript должен присутствовать ключевой оператор return для возврата значения из JS. Выражение которое указывается после return является телом API запроса (Request Body). Можно возвращать: - Строку (будет сконвертирована в json, если формат валидный); - Массив; - Объект (в том числе JSON-объект); - Любое другое выражение (если в конечной точке указан формат TEXT), для результата вычисления которого возможна автоматическая конвертация в строку (например число или булево). Пример (если формат запроса JSON): ```JavaScript return { "key": "value", "lead_name": lead.getData('name'), "request_param_name": request.json.name }; ``` Другой пример (если формат запроса TEXT): ``` let a = false; return a; ``` В JS можно выполнять любой код, например обращаться к пользователям, или устанавливать переменные в memory, планировать задания бота (триггеры, рассылки, скрипты), а также вызывать внешнее API c помощью api.callEndpoint или другие методов объекта api: post/get/postJson/getJson/request. |
| Метод(тип) HTTP запроса | POST / GET / PATCH / и т.д. |
| Формат HTTP запроса | JSON / TEXT |
| Заголовки HTTP запроса (HTTP Headers) | Заголовки, которые будут переданы в HTTP запросе. В данном поле указывается JSON объект или массив. Допустимо использование макропеременных. Также, можно воспользоваться JS методом api.setHeaders(...) или передать заголовки HTTP запроса прямо в аргументах функции api.callEndpoint(...). Также доступна установка заголовков HTTP запроса с помощью атрибута бота **sys\_api\_headers**. ##### Пример 1 для HTTP Headers[](https://docs.metabot24.ru/uploads/images/gallery/2022-11/jwcxMvQOrm5th6xo-8.png) В JavaScript устанавливаем memory атрибут: ```JavaScript memory.setJsonAttr("my_headers", {"token": "my_token"}); ``` Далее используем этот атрибут в поле Headers с помощью макроподстановки: ```JavaScript {{ &$$my_headers }} ``` Обратите внимание, в данном примере выполняется полное заполнение JSON с помощью макроподстановки. ##### Пример 2 для HTTP Headers [](https://docs.metabot24.ru/uploads/images/gallery/2022-11/ALPD46LO07CSkQ5A-11.png) JavaScript: ```JavaScript memory.setAttr('someValue', 'my value'); ``` Headers: ```JSON { "some_param": "{{ &$someValue }}", "other_param": 11 } ``` Обратите внимание, в данном примере выполняется частичная замена JSON с помощью макроподстановки. ##### Пример 3 для HTTP Headers [](https://docs.metabot24.ru/uploads/images/gallery/2022-11/ySw5mkyQ1bXW9Uaw-12.png) JavaScript: ```JavaScript memory.setAttr('anyJsonString', ', "param_3": "my new param"'); ``` Headers: ```JSON { "some_param": "lead.getAttr('any_lead_param')", "other_param": 11 {{ &$anyJsonString }} } ``` Обратите внимание, в данном примере выполняется частичная замена JSON с помощью макроподстановки c атрибутом лида, а также подход похожий на конкатенацию строк, где к JSON клеится строка записанная в атрибут anyJsonString. |
| Параметры HTTP запроса (HTTP Request Options) | Параметры HTTP запроса. В данном поле указывается JSON объект или массив. Допустимо использование макропеременных. Также, можно воспользоваться v8 методом api.setRequestOptions(...) или передать параметры HTTP запроса в аргументах функции api.callEndpoint(...) Также доступна установка параметров HTTP запроса помощью переменной бота **sys\_api\_request\_options**. ##### Пример 1 для HTTP Request Options [](https://docs.metabot24.ru/uploads/images/gallery/2022-11/ntkjaJQBDijTLreV-13.png) JavaScript: ```JavaScript memory.setAttr('leadName', lead.getData('name')); memory.setAttr('addQueryParams', ', "lead_id":' + lead.getData('id')); ``` HTTP Request Options: ```JSON { "query": { "lead_name": "{{ &$leadName }}", "new_param": 11 {{ &$addQueryParams }} } } ``` Пример 2 для HTTP Request Options [](https://docs.metabot24.ru/uploads/images/gallery/2022-11/GDc5baqwamhQAlWF-14.png) JavaScript: ```JavaScript memory.setJsonAttr('headers', { "token": "aasdsad#$%^&*()" }); memory.setJsonAttr('request_options', { "query": { "lead_id": lead.getData('id'), "lead_name": lead.getData('name'), "new_param": 11, } }); ``` HTTP Request Options: ``` {{ &$$request_options }} ``` |
| Конфиг HTTP клиента (HTTP Client Config) | Параметры HTTP клиента. В данном поле указывается JSON объект или массив. Допустимо использование макропеременных. Также, можно воспользоваться v8 методом api.setHttpConfig(...) или передать конфиг HTTP клиента в аргументах функции api.callEndpoint(...) Также доступна установка конфига HTTP клиента с помощью переменной бота **sys\_api\_http\_client\_config**. Пример 1 для HTTP Client Config [](https://docs.metabot24.ru/uploads/images/gallery/2022-11/YjfZ3BQBsdBeid2M-15.png) |
| Настройки прокси (Proxy URL) | Используется для того, чтобы обращаться к определенному ресурсу с помощью прокси сервера. Шаблон для указания прокси: ``` socks5://login:passwd@www.host.com:port ``` Также, можно воспользоваться v8 методом api.setProxyUrl(...) или передать Proxy URL для HTTP запроса в аргументах функции api.callEndpoint(...). Также доступна установка прокси с помощью переменной бота **sys\_api\_proxy\_url**. |
| Комментарий | Любой текст. Доступно указание любых HTML-тэгов. |
Список всех конечных точек внешнего API сортируется по следующим полям: наименование, алиас, id. Поэтому вы можете управлять сортировкой записей изменяя наименование или алиас. В будущем будет добавлена произвольная сортировка.
#### Проверка работы внешнего API Для тестирования внешнего API можно воспользоваться любым онлайн сервисом для отладки вебхуков (или развернуть аналогичный локально): - [https://stackoverflow.com/questions/5725430/http-test-server-accepting-get-post-requests](https://stackoverflow.com/questions/5725430/http-test-server-accepting-get-post-requests) - [https://webhook.site](https://webhook.site/) - [https://pipedream.com/requestbin](https://pipedream.com/requestbin) - [http://ptsv2.com](http://ptsv2.com/) Пример: [](https://docs.metabot24.ru/uploads/images/gallery/2022-11/JzPDqZ6saUf54EAH-10.png)С API так же можно работать с помощью JS методов. Все методы и их описание вы можете посмотреть в **[Справочнике по функциям JS](https://docs.metabot24.ru/books/07-spravocnik-po-funkciyam-js/page/spravocnik-vsex-funkcii-Cgt#bkmrk-%D0%A0%D0%B0%D0%B1%D0%BE%D1%82%D0%B0-%D1%81-api:~:text=D1%2581%2Dapi-,%D0%A0%D0%B0%D0%B1%D0%BE%D1%82%D0%B0%20%D1%81%20API,-%D0%9C%D0%B5%D1%82%D0%BE%D0%B4%D1%8B%20bot "Справочник всех функций")**