В данном разделе описываются доступные методы для работы с API источников.
Через методы API источников интеграция может управлять только своими источниками.
Интеграция идентифицируется посредством проверки переданного Access Token.
Каждый источник обладает уникальным кодом (external_id) и двух источников с одинаковым кодом быть не может.
Одна интеграция может создать не более 50 активных источников.
API источников позволяет интеграции сообщить amoCRM в какой воронке должно быть создано неразобранное.
На данный момент созданные интеграцией источники учитываются:
_embedded[source][external_id]
Также через API источников интеграция может добавить варианты выбора номеров WhatsApp,
которые используются при настройке кнопки на сайт – СRM Plugin
Источнику можно указать свойство waba если интеграция работает с белым WhatsApp и настроено временное окно. Параметр даёт возможность управления шаблонами WhatsApp и использовании их в новом шаге "Отправить сообщение" в salesbot. После указания данного параметра следует подписаться на события отправки шаблона на утверждение. Получив такое событие интеграция может передать шаблон на одобрение в WhatsApp и в зависимости от результата изменить статус шаблона WhatsApp через API
Источники, создаваемые интеграцией отображаются в разделе настроек Digital Pipeline.
Пользователь может взаимодействовать с источником и интеграцией через интерфейс,
поэтому интеграции для работы с источниками требуется загруженный архив.
Таким образом с API источников могут взаимодействовать все интеграции за исключением типа "Внешняя интеграция".
Перед началом работы с API источников нужно удостоверится что интеграция соответствует следующим критериям:
"locations":["lead_sources"]
Также у интеграции появляется новое свойство – "Поддерживается ли работа с множественными источниками".
Данный флаг стоит включить, когда интеграция полностью управляет источниками через API со своего бэкенда и создание источника со стороны amoCRM больше не требуется.
Если флаг не стоит – при установке интеграции будет создан источник на стороне amoCRM.
GET /api/v4/sources
Метод позволяет получить список источников интеграции.
Метод доступен с правами администратора. Возвращает не более 50 источников
Параметр | Тип данных | Описание |
---|---|---|
filter | object | Доступные поля фильтра смотрите ниже |
filter[external_id] | string|array | Фильтр по внешнему идентификатору источника |
Content-Type: application/hal+json
Content-Type: application/problem+json
Код ответа | Условие |
---|---|
200 | Список источников интеграций |
204 | У интеграции нет подконтрольных источников или поиск по фильтру не дал результатов |
403 | Интеграция не авторизована |
Метод возвращает коллекцию моделей источников
Параметр | Тип данных | Описание |
---|---|---|
id | int | ID источника |
name | string | Название источника |
pipeline_id | int | ID воронки, воронка может быть архивной |
external_id | string | Внешний идентификатор источника на стороне интеграции |
default | bool | Является ли данный источник источником по-умолчанию. Поле не является обязательным |
origin_code | string null |
Код основного канала источника. Данный канал чата будет использоваться при инициализации общения. Поле не является обязательным. |
services | array | Массив сервисов которые связаны с источником. На данный момент поддерживается только whatsapp. Данные из этого массива используются для отображения в CRM Plugin (кнопки на сайт). Поле не является обязательным. |
services[0][type] | string | тип сервиса, на данный момент поддерживается только один тип: "whatsapp" |
services[0][params] | object | Объект с настройками источника. Поле не является обязательным. |
services[0][params][waba] | bool | Является ли источник белым whatsapp. Следует добавить для возможности работы с одобренными шаблонами whatsapp в salesbot в новом шаге отправки сообщения. Поле не является обязательным. |
services[0][pages] | string | Для whatsapp сервиса содержит список элементов, которые можно выбрать при настройке CRM Plugin (кнопки на сайт) |
services[0][pages][0][name] | string | Отображаемое пользователю название пункта в выпадающем списке при настройке кнопки на сайте |
services[0][pages][0][id] | string | Идентификатор пункта в выпадающем списке (не отображается клиенту и пользователю) |
services[0][pages][0][link] | string | Номер телефона, который будет указан в кнопке whatsapp и которому будет писать клиент на странице сайта. В CRM Plugin ссылка будет сформирована следующим образов: https://wa.me/{Указанный номер телефона} |
{
"_total_items": 2,
"_links": {
"self": {
"href": "https://example.amocrm.ru/api/v4/sources"
}
},
"_embedded": {
"sources": [
{
"id": 9619,
"name": "Номер отдела продаж",
"pipeline_id": 1300,
"external_id": "+17 912 100 00 00",
"default": true,
"origin_code": null,
"services": [],
"_links": {
"self": {
"href": "https://example.amocrm.ru/api/v4/sources/9619"
}
}
},
{
"id": 4460,
"name": "Лендинг",
"pipeline_id": 1301,
"external_id": "65bd500b-fd52-4599-ab58-943ce3dd058c",
"default": false,
"origin_code": "amo.ext.30490163_v2",
"services": [],
"_links": {
"self": {
"href": "https://example.amocrm.ru/api/v4/sources/4460"
}
}
}
]
}
}
GET /api/v4/sources/{id}
Метод позволяет получить список источников интеграции.
Метод доступен с правами администратора.
Content-Type: application/hal+json
Content-Type: application/problem+json
Код ответа | Условие |
---|---|
200 | Источник найден |
204 | У интеграции нет подконтрольных источников или источник удален |
403 | Интеграция не авторизована |
Метод возвращает коллекцию моделей источников
Параметр | Тип данных | Описание |
---|---|---|
id | int | ID источника |
name | string | Название источника |
pipeline_id | int | ID воронки, воронка может быть архивной |
external_id | string | Внешний идентификатор источника на стороне интеграции |
default | bool | Является ли данный источник источником по-умолчанию. Поле не является обязательным |
origin_code | string null |
Код основного канала источника. Данный канал чата будет использоваться при инициализации общения. Поле не является обязательным. |
services | array | Массив сервисов которые связаны с источником. На данный момент поддерживается только whatsapp. Данные из этого массива используются для отображения в CRM Plugin (кнопки на сайт). Поле не является обязательным. |
services[0][type] | string | тип сервиса, на данный момент поддерживается только один тип: "whatsapp" |
services[0][params] | object | Объект с настройками источника. Поле не является обязательным. |
services[0][params][waba] | bool | Является ли источник белым whatsapp. Следует добавить для возможности работы с одобренными шаблонами whatsapp в salesbot в новом шаге отправки сообщения. Поле не является обязательным. |
services[0][pages] | string | Для whatsapp сервиса содержит список элементов, которые можно выбрать при настройке CRM Plugin (кнопки на сайт) |
services[0][pages][0][name] | string | Отображаемое пользователю название пункта в выпадающем списке при настройке кнопки на сайте |
services[0][pages][0][id] | string | Идентификатор пункта в выпадающем списке (не отображается клиенту и пользователю) |
services[0][pages][0][link] | string | Номер телефона, который будет указан в кнопке whatsapp и которому будет писать клиент на странице сайта. В CRM Plugin ссылка будет сформирована следующим образов: https://wa.me/{Указанный номер телефона} |
{
"id": 9619,
"name": "Номер отдела продаж",
"pipeline_id": 1300,
"external_id": "+17 912 100 00 00",
"default": true,
"origin_code": null,
"services": [],
"_links": {
"self": {
"href": "https://example.amocrm.ru/api/v4/sources/9619"
}
}
}
POST /api/v4/sources
Метод позволяет добавлять источники пакетно.
Метод доступен с правами администратора. Добавить одновременно можно не более 50 источников.
Content-Type: application/json
Внешний идентификатор источника должен быть уникальным для интеграции в рамках одного аккаунта.
Параметр | Тип данных | Описание |
---|---|---|
name | string | Название источника. Поле является обязательным |
external_id | string | Внешний идентификатор источника, не может быть изменен после создания. Длина поля 36 символов, можно использовать любые печатные ascii символы и пробел |
pipeline_id | int | ID воронки, к которой относится источник. Поле не является обязательным |
default | bool | Является ли данный источник источником по-умолчанию. Поле не является обязательным |
origin_code | string | Код основного канала источника. Данный канал чата будет использоваться при инициализации общения. Поле не является обязательным. |
services | array | Массив сервисов которые связаны с источником. На данный момент поддерживается только whatsapp. Данные из этого массива используются для отображения в CRM Plugin (кнопки на сайт). Поле не является обязательным. |
services[0][type] | string | тип сервиса, на данный момент поддерживается только один тип: "whatsapp" |
services[0][params] | object | Объект с настройками источника. Поле не является обязательным. |
services[0][params][waba] | bool | Является ли источник белым whatsapp. Следует добавить для возможности работы с одобренными шаблонами whatsapp в salesbot в новом шаге отправки сообщения. Поле не является обязательным. |
services[0][pages] | string | Для whatsapp сервиса содержит список элементов, которые можно выбрать при настройке CRM Plugin (кнопки на сайт) |
services[0][pages][0][name] | string | Отображаемое пользователю название пункта в выпадающем списке при настройке кнопки на сайте |
services[0][pages][0][id] | string | Идентификатор пункта в выпадающем списке (не отображается клиенту и пользователю) |
services[0][pages][0][link] | string | Номер телефона, который будет указан в кнопке whatsapp и которому будет писать клиент на странице сайта. В CRM Plugin ссылка будет сформирована следующим образов: https://wa.me/{Указанный номер телефона} |
[
{
"name": "Номер отдела продаж",
"pipeline_id": 1300,
"external_id": "+17 912 100 00 00",
"default": true,
"services": [
{
"type": "whatsapp",
"params": {
"waba": true
},
"pages": [
{
"id": "9121234565",
"name": "WhatsApp +9121234567",
"link": "+9121234567"
}
]
}
]
},
{
"name": "Лендинг",
"external_id": "65bd500b-fd52-4599-ab58-943ce3dd058c",
"origin_code": "amo.ext.30490163_v2"
}
]
Content-Type: application/hal+json
Content-Type: application/problem+json
Код ответа | Условие |
---|---|
200 | Источники были успешно созданы |
401 | Интеграция не авторизована |
400 | Переданы некорректные данные. Подробности доступны в теле ответа |
Метод возвращает коллекцию источников, которые были добавлены.
Параметр | Тип данных | Описание |
---|---|---|
id | int | ID источника |
name | string | Название источника |
pipeline_id | int | ID воронки, воронка может быть архивной |
external_id | string | Внешний идентификатор источника на стороне интеграции |
default | bool | Является ли данный источник источником по-умолчанию. Поле не является обязательным |
origin_code | string | Код основного канала источника. Данный канал чата будет использоваться при инициализации общения. Поле не является обязательным. |
services | array | Массив сервисов которые связаны с источником. На данный момент поддерживается только whatsapp. Данные из этого массива используются для отображения в CRM Plugin (кнопки на сайт). Поле не является обязательным. |
services[0][type] | string | тип сервиса, на данный момент поддерживается только один тип: "whatsapp" |
services[0][params] | object | Объект с настройками источника. Поле не является обязательным. |
services[0][params][waba] | bool | Является ли источник белым whatsapp. Следует добавить для возможности работы с одобренными шаблонами whatsapp в salesbot в новом шаге отправки сообщения. Поле не является обязательным. |
services[0][pages] | string | Для whatsapp сервиса содержит список элементов, которые можно выбрать при настройке CRM Plugin (кнопки на сайт) |
services[0][pages][0][name] | string | Отображаемое пользователю название пункта в выпадающем списке при настройке кнопки на сайте |
services[0][pages][0][id] | string | Идентификатор пункта в выпадающем списке (не отображается клиенту и пользователю) |
services[0][pages][0][link] | string | Номер телефона, который будет указан в кнопке whatsapp и которому будет писать клиент на странице сайта. В CRM Plugin ссылка будет сформирована следующим образов: https://wa.me/{Указанный номер телефона} |
request_id | string | Строка переданная при запросе или порядковый указатель, если параметр не передан |
{
"_total_items": 2,
"_links": {
"self": {
"href": "https://example.amocrm.ru/api/v4/sources"
}
},
"_embedded": {
"sources": [
{
"id": 9619,
"name": "Номер отдела продаж",
"pipeline_id": 1300,
"external_id": "+17 912 100 00 00",
"default": true,
"origin_code": null,
"services": [
{
"type": "whatsapp",
"params": {
"waba": true
},
"pages": [
{
"id": "9121234565",
"name": "WhatsApp +9121234567",
"link": "+9121234567"
}
]
}
],
"_links": {
"self": {
"href": "https://example.amocrm.ru/api/v4/sources/9619"
}
}
},
{
"id": 4460,
"name": "Лендинг",
"pipeline_id": 1307,
"external_id": "65bd500b-fd52-4599-ab58-943ce3dd058c",
"default": false,
"origin_code": "amo.ext.30490163_v2",
"services": [],
"_links": {
"self": {
"href": "https://example.amocrm.ru/api/v4/sources/4460"
}
}
}
]
}
}
PATCH /api/v4/sources
Метод позволяет редактировать источники пакетно.
Также вы можете добавить ID источника в метод для редактирования конкретного источника (/api/v4/sources/{id}).
При пакетном редактировании передается массив из объектов-источников, при редактировании одного источника, передается просто модель источника.
Метод доступен с правами администратора. Обновить одновременно можно не более 50 источников
Content-Type: application/json
Внешний идентификатор источника (external_id) изменить нельзя, можно только создать новый источник с таким идентификатором
Параметр | Тип данных | Описание |
---|---|---|
id | int | ID источника, обязателен при пакетном обновлении |
name | string | Название источника. Поле не является обязательным |
pipeline_id | int | ID воронки, к которой относится источник. Поле не является обязательным |
default | bool | Является ли данный источник источником по-умолчанию. Поле не является обязательным |
origin_code | string | Код основного канала источника. Данный канал чата будет использоваться при инициализации общения. Поле не является обязательным. |
services | array | Массив сервисов которые связаны с источником. На данный момент поддерживается только whatsapp. Данные из этого массива используются для отображения в CRM Plugin (кнопки на сайт). Поле не является обязательным. |
services[0][type] | string | тип сервиса, на данный момент поддерживается только один тип: "whatsapp" |
services[0][params] | object | Объект с настройками источника. Поле не является обязательным. |
services[0][params][waba] | bool | Является ли источник белым whatsapp. Следует добавить для возможности работы с одобренными шаблонами whatsapp в salesbot в новом шаге отправки сообщения. Поле не является обязательным. |
services[0][pages] | string | Для whatsapp сервиса содержит список элементов, которые можно выбрать при настройке CRM Plugin (кнопки на сайт) |
services[0][pages][0][name] | string | Отображаемое пользователю название пункта в выпадающем списке при настройке кнопки на сайте |
services[0][pages][0][id] | string | Идентификатор пункта в выпадающем списке (не отображается клиенту и пользователю) |
services[0][pages][0][link] | string | Номер телефона, который будет указан в кнопке whatsapp и которому будет писать клиент на странице сайта. В CRM Plugin ссылка будет сформирована следующим образов: https://wa.me/{Указанный номер телефона} |
В данном примере мы обновим 2 источника.
У одного изменим имя, у другого сменим воронку
[
{
"id": 9619,
"name": "Номер отдела продаж"
},
{
"id": 4460,
"name": "Лендинг",
"pipeline_id": 1307
}
]
Content-Type: application/hal+json
Content-Type: application/problem+json
Код ответа | Условие |
---|---|
200 | Источники были успешно изменены |
401 | Интеграция не авторизована |
400 | Переданы некорректные данные. Подробности доступны в теле ответа |
Метод возвращает коллекцию источников, которые были изменены.
Параметр | Тип данных | Описание |
---|---|---|
id | int | ID источника |
name | string | Название источника |
pipeline_id | int | ID воронки, воронка может быть архивной |
external_id | string | Внешний идентификатор источника на стороне интеграции |
default | bool | Является ли данный источник источником по-умолчанию. Поле не является обязательным |
origin_code | string | Код основного канала источника. Данный канал чата будет использоваться при инициализации общения. Поле не является обязательным. |
services | array | Массив сервисов которые связаны с источником. На данный момент поддерживается только whatsapp. Данные из этого массива используются для отображения в CRM Plugin (кнопки на сайт). Поле не является обязательным. |
services[0][type] | string | тип сервиса, на данный момент поддерживается только один тип: "whatsapp" |
services[0][params] | object | Объект с настройками источника. Поле не является обязательным. |
services[0][params][waba] | bool | Является ли источник белым whatsapp. Следует добавить для возможности работы с одобренными шаблонами whatsapp в salesbot в новом шаге отправки сообщения. Поле не является обязательным. |
services[0][pages] | string | Для whatsapp сервиса содержит список элементов, которые можно выбрать при настройке CRM Plugin (кнопки на сайт) |
services[0][pages][0][name] | string | Отображаемое пользователю название пункта в выпадающем списке при настройке кнопки на сайте |
services[0][pages][0][id] | string | Идентификатор пункта в выпадающем списке (не отображается клиенту и пользователю) |
services[0][pages][0][link] | string | Номер телефона, который будет указан в кнопке whatsapp и которому будет писать клиент на странице сайта. В CRM Plugin ссылка будет сформирована следующим образов: https://wa.me/{Указанный номер телефона} |
request_id | string | Строка переданная при запросе или порядковый указатель, если параметр не передан |
{
"_total_items": 2,
"_links": {
"self": {
"href": "https://example.amocrm.ru/api/v4/sources"
}
},
"_embedded": {
"sources": [
{
"id": 9619,
"name": "Номер отдела продаж",
"pipeline_id": 1300,
"external_id": "+17 912 100 00 00",
"default": true,
"origin_code": null,
"services": [],
"_links": {
"self": {
"href": "https://example.amocrm.ru/api/v4/sources/9619"
}
}
},
{
"id": 4460,
"name": "Лендинг",
"pipeline_id": 1307,
"external_id": "65bd500b-fd52-4599-ab58-943ce3dd058c",
"origin_code": "amo.ext.30490163_v2",
"default": false,
"services": [],
"_links": {
"self": {
"href": "https://example.amocrm.ru/api/v4/sources/4460"
}
}
}
]
}
}
DELETE /api/v4/sources
Метод позволяет удалить источники пакетно.
Также вы можете добавить ID источника в метод для удаления конкретного источника (/api/v4/sources/{id}).
При пакетном удалении передается массив из объектов-источников, при удалении одного источника, тело запроса передавать не требуется.
Метод доступен с правами администратора.
Content-Type: application/json
Параметр | Тип данных | Описание |
---|---|---|
id | int | ID источника, обязателен при пакетном удалении |
[
{
"id": 9619
},
{
"id": 4460
}
]
Код ответа | Условие |
---|---|
204 | Источники были успешно удалены |
401 | Интеграция не авторизована |
400 | Не удалось найти источники при пакетном удалении. Подробности доступны в теле ответа |
404 | У интеграции нет подконтрольных источников или источник не найден (при указании конкретного источника) |
Метод возвращает данные, если источники не были найдены при пакетном удалении
Параметр | Тип данных | Описание |
---|---|---|
request_id | string | Строка переданная при запросе или порядковый указатель, если параметр не передан |
{
"errors": [
{
"request_id": "0",
"errors": {
"code": "EntityNotFound",
"path": "id",
"detail": "source with id = 31075178 not found"
}
}
],
"title": "Bad Request",
"type": "https://httpstatus.es/400",
"status": 400,
"detail": "Invalid request items"
}