В данном разделе описывается работа с виджетами через API.
GET /api/v4/widgets
Метод возвращает агрегированный список публичных виджетов, виджетов установленных в аккаунте, а также загруженным текущим пользователем.
Метод доступен всем пользователям.
| Параметр | Тип данных | Описание |
|---|---|---|
| page | int | Страница выборки |
| limit | int | Количество возвращаемых сущностей за один запрос (Максимум – 250) |
Content-Type: application/hal+json
Content-Type: application/problem+json
| Код ответа | Условие |
|---|---|
| 200 | Запрос выполнен успешно |
| 401 | Пользователь не авторизован |
Метод возвращает коллекцию моделей виджетов, рассмотрим ниже свойства модели.
| Параметр | Тип данных | Описание |
|---|---|---|
| id | int | ID виджета |
| code | string | Код виджета |
| version | string | Версия виджета |
| rating | string/float | Рейтинг виджета |
| settings_template | array | Поля доступные для настройки |
| settings_template[0] | object | Поле для настройки |
| settings_template[0][key] | string | Ключ значения поля в настройках виджета |
| settings_template[0][name] | string | Название поля в настройках виджета |
| settings_template[0][type] | string | Тип данных в настройках виджета (text, pass, custom, users или users_lp) |
| settings_template[0][is_required] | bool | Является ли настройка обязательной |
| is_lead_source | bool | Доступен ли виджет в качестве источника сделок |
| is_work_with_dp | bool | Доступен ли виджет в Digital Pipeline |
| is_crm_template | bool | Является ли виджет отраслевым решением |
| client_uuid | string/null | UUID связанной с виджетом oAuth интеграции |
| is_active_in_account | bool | Установлен ли виджет в аккаунте |
| pipeline_id | int | ID воронки, в котором виджет установлен, как источник сделок |
{
"_page": 1,
"_links": {
"self": {
"href": "https://example.amocrm.ru/api/v4/widgets?limit=2&page=1"
},
"next": {
"href": "https://example.amocrm.ru/api/v4/widgets?limit=2&page=2"
}
},
"_embedded": {
"widgets": [
{
"id": 742,
"code": "amo_dropbox",
"version": "0.0.13",
"rating": "2,8",
"settings_template": [
{
"key": "conf",
"name": "custom",
"type": "custom",
"is_required": false
}
],
"is_lead_source": false,
"is_work_with_dp": false,
"is_crm_template": false,
"client_uuid": null,
"is_active_in_account": false,
"pipeline_id": null,
"_links": {
"self": {
"href": "https://example.amocrm.ru/api/v4/widgets/amo_dropbox"
}
}
},
{
"id": 796,
"code": "amo_mailchimp",
"version": "1.1.12",
"rating": "3,4",
"settings_template": [
{
"key": "api",
"name": "custom",
"type": "custom",
"is_required": false
}
],
"is_lead_source": false,
"is_work_with_dp": false,
"is_crm_template": false,
"client_uuid": null,
"is_active_in_account": false,
"pipeline_id": null,
"_links": {
"self": {
"href": "https://example.amocrm.ru/api/v4/widgets/amo_mailchimp"
}
}
}
]
}
}GET /api/v4/widgets/{widget_code}
Метод позволяет получить информацию о публичном или загруженном текущим пользователем виджете.
Метод доступен всем пользователям
Content-Type: application/hal+json
Content-Type: application/problem+json
| Код ответа | Условие |
|---|---|
| 200 | Запрос выполнен успешно |
| 404 | Виджет не найден или недоступен |
| 401 | Пользователь не авторизован |
Метод возвращает модель виджета, рассмотрим ниже свойства модели.
| Параметр | Тип данных | Описание |
|---|---|---|
| id | int | ID виджета |
| code | string | Код виджета |
| version | string | Версия виджета |
| rating | string/float | Рейтинг виджета |
| settings_template | array | Поля доступные для настройки |
| settings_template[0] | object | Поле для настройки |
| settings_template[0][key] | string | Ключ значения поля в настройках виджета |
| settings_template[0][name] | string | Название поля в настройках виджета |
| settings_template[0][type] | string | Тип данных в настройках виджета (text, pass, custom, users или users_lp) |
| settings_template[0][is_required] | bool | Является ли настройка обязательной |
| is_lead_source | bool | Доступен ли виджет в качестве источника сделок |
| is_work_with_dp | bool | Доступен ли виджет в Digital Pipeline |
| is_crm_template | bool | Является ли виджет отраслевым решением |
| client_uuid | string/null | UUID связанной с виджетом oAuth интеграции |
| is_active_in_account | bool | Установлен ли виджет в аккаунте |
| pipeline_id | int | ID воронки, в котором виджет установлен, как источник сделок |
| settings | array | Настройки виджета. Данный ключ возвращается только при запросе из под ключа, связанной с виджетом интеграции |
{
"id": 742,
"code": "amo_dropbox",
"version": "0.0.13",
"rating": "2,8",
"settings_template": [
{
"key": "conf",
"name": "custom",
"type": "custom",
"is_required": false
}
],
"is_lead_source": false,
"is_work_with_dp": false,
"is_crm_template": false,
"client_uuid": null,
"is_active_in_account": false,
"pipeline_id": null,
"_links": {
"self": {
"href": "https://example.amocrm.ru/api/v4/widgets/amo_dropbox"
}
}
}POST /api/v4/widgets/{widget_code}
Метод позволяет устанавливать виджет в аккаунт.
Метод доступен с правами администратора аккаунта.
Content-Type: application/json
Для установки виджета необходимо передать обязательные параметры в зависимости от доступных настроек виджета. Рассмотрим ниже доступные типы полей и их формат
| Параметр | Тип данных | Описание |
|---|---|---|
| text | string | Значение данного типа передается в виде простой строки |
| pass | string | Значение данного типа передается в виде простой строки |
| users | object | Объект, содержащий ID пользователя amoCRM как ключ и его добавочный номер как значение |
| users_lp | object | Объект, содержащий ID пользователя amoCRM как ключ и объект к логином и паролем как значение |
| users_lp[{user_id}][login] | object | Логин пользователя |
| users_lp[{user_id}][password] | object | Пароль пользователя |
В примере передадим необходимые поля для установки виджета amo_asterisk.
Поле login и script_path имеет тип text.
Поле password имеет тип pass.
Поле phones имеет тип users.
{
"login": "example",
"password": "eXaMp1E",
"phones": {
"504141": "1039"
},
"script_path": "https://example.com/"
}Content-Type: application/hal+json
Content-Type: application/problem+json
| Код ответа | Условие |
|---|---|
| 200 | Виджет был успешно установлен |
| 404 | Виджет не найден |
| 401 | Пользователь не авторизован |
| 400 | Переданы некорректные данные. Подробности доступны в теле ответа |
Метод возвращает объект виджета, который был установлен, а также настройки виджета. Свойства аналогичны тем, что приходят в методе получения виджета.
{
"id": 972,
"code": "amo_asterisk",
"version": "1.1.6",
"rating": "2,7",
"settings_template": [
{
"key": "login",
"name": "Логин",
"type": "text",
"is_required": true
},
{
"key": "password",
"name": "Пароль",
"type": "pass",
"is_required": true
},
{
"key": "phones",
"name": "Список телефонов",
"type": "users",
"is_required": true
},
{
"key": "script_path",
"name": "Путь к скрипту",
"type": "text",
"is_required": true
}
],
"is_lead_source": false,
"is_work_with_dp": false,
"is_crm_template": false,
"client_uuid": null,
"is_active_in_account": true,
"pipeline_id": null,
"settings": {
"login": "example",
"password": "eXaMp1E",
"phones": {
"504141": "1039"
},
"script_path": "https://example.com/"
},
"_links": {
"self": {
"href": "https://example.amocrm.ru/api/v4/widgets/amo_asterisk"
}
}
}DELETE /api/v4/widgets/{widget_code}
Метод позволяет отключить виджет по его коду.
Метод доступен только с правами администратора аккаунта.
Content-Type: application/json
| Код ответа | Условие |
|---|---|
| 204 | Виджет был успешно отключен |
| 404 | Виджет не найден |
| 403 | Не хватает прав для вызова данного метода |
| 401 | Пользователь не авторизован |
Метод не возвращает тело
POST /api/v4/{salesbot|marketingbot}/{bot_id}/continue/{continue_id}
Метод принимает данные после выполнения отработки виджета в Salesbot’е и продолжает работу бота.
Подробней о методе Salesbot widget_request читайте – тут.
Метод доступен только с правами администратора аккаунта.
Максимальное количество переданных хендлеров в параметре execute_handlers: 10.
Если передан в execute_handler, хендлер с типом: show, то параметр value, не должен превышать 80 символов
Максимальное количество переданных кнопок в execute_handler: 25.
Content-Type: application/json
Если виджету требуется передать какие либо данные, их нужно поместить в поле data в виде массива.Если виджету требуется выполнить дейсвтия до того, как бот продолжит работу, то вы можете передать список хендлеров в параметр: execute_handlers. Переданные хендлеры выполняются по очереди.
| Параметр | Тип данных | Описание |
|---|---|---|
| data | array | Данные для виджета, в коде бота можно получить их по ключу {{json.НАЗВАНИЯ_КЛЮЧА_МАССИВА}}, где НАЗВАНИЯ_КЛЮЧА_МАССИВА это имя поля переданного в data. Необязательный параметр. |
| execute_handlers | array | На данный момент поддерживаются хендлеры следующих типов: show, goto. Необязательный параметр. |
В примере передадим виджету поле status, в любом блоке после widget_request по ключу {{json.status}} виджет сможет получить его значение: "success".
Также передадим, чтобы бот виджета отобразил текст, кнопки, кнопки со ссылками и перешёл на 5 шаг бота виджета
{
"data": {
"status": "success"
},
"execute_handlers": [
{
"handler": "show",
"params": {
"type": "text",
"value": "Здесь текст"
}
},
{
"handler": "show",
"params": {
"type": "buttons",
"value": "Нажми на кнопку",
"buttons": [
"1ая кнопка",
"2ая кнопка",
"3ая кнопка",
"4ая кнопка",
...
"25ая кнопка"
]
}
},
{
"handler": "show",
"params": {
"type": "buttons_url",
"value": "Кнопки со ссылками",
"buttons": [
"https://amocrm.ru",
"https://amocrm.com"
]
}
},
{
"handler": "goto",
"params": {
"type": "question|answer|finish",
"step": 5
}
}
]
}| Код ответа | Условие |
|---|---|
| 202 | Виджет был успешно запущен |
| 400 | Переданы неверные данные |
| 404 | Запись о виджете ожидающем результата выполнения не найдена |
| 401 | Пользователь не авторизован |
Метод не возвращает тело