Виджет – это архив, содержащий набор файлов, которые будут подключаться в amoCRM всем аккаунтам, включившим виджет. Виджет позволяет получить дополнительный функционал, если необходимо:
Настроить виджеты может администратор аккаунт на странице Настройки->Интеграции.
Эти методы доступны только администратору аккаунта
Метод API | Описание |
---|---|
GET api/v2/widgets | Метод для получения списка виджетов. |
POST api/v2/widgets | Метод позволяет включать или выключать виджеты по одному или пакетно. |
POST api/v2/widgets/sources | Метод позволяет передавать данные о доступных в виджете каналах связи, которые доступны для подключения в кнопку обратной связи |
GET /api/v2/widgets
Параметр | Описание |
---|---|
widget_id | Выбрать виджеты с заданным ID (можно передавать в виде массива из нескольких ID) |
widget_code | Выбрать виджеты с заданным кодом (можно передавать в виде массива из нескольких кодов) |
Описание параметров ответа
Параметр | Тип | Описание |
---|---|---|
widget_id | int | Уникальный идентификатор виджета |
widget_code | string | Уникальный код виджета |
settings_template | array | Массив доступных настроек виджета. Ключок массива является код поля FIELD_CODE |
settings_template/FIELD_CODE /name | string | Название поля (ссылка на элемент в lang файле) |
settings_template/FIELD_CODE /type | string | Тип поля |
settings_template/FIELD_CODE /required | bool | Обязательность заполнения поля |
dp | array | Массив настройки виджета в digital pipeline |
salebot_designer | array | Поля для отображения интерфейса настроек виджета в Salesbot. Подробнее в статье |
rating | float | Рейтинг виджета |
settings | array | Если в аккаунте есть настройки для виджета, то они будут перечислены в этом массиве |
active | bool | Включён ли виджет в аккаунте |
path | string | Путь к виджету |
new_design | bool | Включен ли новый дизайн модального окна виджета. Данный параметр является устаревшим |
is_lead_source | bool | Включен ли данный виджет в источниках сделки |
dp_ready | bool | Включен ли данный виджет в digital pipeline |
Приведём пример ответа на получение данных существующего виджета.
{
"widgets": [
{
"widget_id": 424111,
"widget_code": "amo_widget",
"settings_template": {
"sid": {
"name": "settings.sid",
"type": "text",
"required": false
},
"token": {
"name": "settings.token",
"type": "text",
"required": false
},
"conf": {
"name": "settings.custom",
"type": "custom",
"required": false
}
},
"dp": [],
"salesbot_designer": [],
"rating": 0,
"settings": {
"sid": "AC8d97fh6n40t8403nfesdf8580hj9cb2e",
"token": "07ds5fp934ujo4i4ferfgj7n5po9c97e",
"conf": {
"out_number": {
"sid": "PNc8eb0gjt89gj5748983hg6jd8ee45fc6",
"type": "number"
},
"application_sid": "APf98fuh9s048hf493hv35o9e47120555f",
"call_forward": {
"active": "N"
}
}
},
"active": 1,
"path": "widgets/amo_widget",
"new_design": true,
"is_lead_source": false,
"dp_ready": false
}
],
}
/* Для начала нам необходимо инициализировать данные, необходимые для составления запроса. */
$subdomain = 'test'; #Наш аккаунт - поддомен
#Формируем ссылку для запроса
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/widgets?';
$link .= http_build_query(['widget_code' => 'amo_widget', 'widget_id' => [123, 456, 789]]);
/* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой cURL (поставляется в составе PHP).
Подробнее о работе с этой библиотекой Вы можете прочитать в мануале . */
$curl = curl_init(); #Сохраняем дескриптор сеанса cURL
#Устанавливаем необходимые опции для сеанса cURL
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_USERAGENT, 'amoCRM-API-client/1.0');
curl_setopt($curl, CURLOPT_HTTPHEADER, ['Accept: application/json']);
curl_setopt($curl, CURLOPT_URL, $link);
curl_setopt($curl, CURLOPT_HEADER, FALSE);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
$out = curl_exec($curl); #Инициируем запрос к API и сохраняем ответ в переменную
$code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
Теперь мы можем обработать ответ, полученный от сервера. Это пример. Вы можете обработать данные своим способом.
$code = (int)$code;
$errors = array(
301 => 'Moved permanently',
400 => 'Bad request',
401 => 'Unauthorized',
403 => 'Forbidden',
404 => 'Not found',
500 => 'Internal server error',
502 => 'Bad gateway',
503 => 'Service unavailable',
);
try {
#Если код ответа не равен 200 или 204 - возвращаем сообщение об ошибке
if ($code != 200 && $code != 204) {
throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error', $code);
}
} catch (Exception $E) {
die('Ошибка: ' . $E->getMessage() . PHP_EOL . 'Код ошибки: ' . $E->getCode());
}
/**
* Данные получаем в формате JSON, поэтому, для получения читаемых данных,
* нам придётся перевести ответ в формат, понятный PHP
*/
$Response = json_decode($out, TRUE);
$Response = $Response['response'];
Метод позволяет включил и выключать виджеты по одному или пакетно, а также обновлять данные включённых и выключенных виджетов.
POST /api/v2/widgets
Все параметры, которые описаны в install действуют также и в uninstall.
Параметр | Тип | Описание |
---|---|---|
install | int | Уникальный идентификатор виджета |
uninstall | string | Уникальный код виджета |
install/widget_id require | int | Уникальный идентификатор виджета, который указывается с его установки или деинсталяции |
install/widget_code require | string | Уникальный символьный код виджета, который указывается с его установки или деинсталяции |
install/settings | array | Массив настроек виджета |
Приведём пример запроса на включения виджета.
{
"widgets": {
"install": [
{
"widget_code": "amo_widget",
"settings": {
"sid": "AC1022547836070ad31fbb1ff77ff9cb2e",
"token": "07c6a54b2bdd3cgd03c1882fb76bc97e",
"conf": {
"out_number": {
"sid": "PNc8eb06f3b2081829cc516ebd8eeeafc6",
"type": "number"
},
"application_sid": "APf9d9bc8302f247d28bcc69e47120555f",
"call_forward": {
"active": "N"
}
}
}
}
]
}
}
Приведём пример ответа на получение данных существующего виджета.
{
"widgets": [
{
"widget_id": 424111,
"widget_code": "amo_widget",
"settings_template": {
"sid": {
"name": "settings.sid",
"type": "text",
"required": false
},
"token": {
"name": "settings.token",
"type": "text",
"required": false
},
"conf": {
"name": "settings.custom",
"type": "custom",
"required": false
}
},
"dp": [],
"salesbot_designer": [],
"rating": 0,
"settings": {
"sid": "AC8d97fh6n40tds03ng6j908580hj9cb2e",
"token": "07ds5fp934ujo4dfts38gj7n5po9c97e",
"conf": {
"out_number": {
"sid": "PNc8eb0gjt89gjds48983hg6jd8ee45fc6",
"type": "number"
},
"application_sid": "APf98ffr9s048hf493hv35o9e47120555f",
"call_forward": {
"active": "N"
}
}
},
"active": 1,
"path": "widgets/amo_widget",
"new_design": true,
"is_lead_source": false,
"dp_ready": false
}
],
}
Для установки виджета необходимо описать массив, содержащий информацию о настройках виджета и поместить его в массив следующего вида: $widgets[‘widgets’][‘install’]. Наше API также поддерживает одновременное включение сразу нескольких виджетов. Для этого мы помещаем в массив $widgets[‘widgets’][‘install’] несколько массивов, каждый из которых описывает необходимые данные настроек соответсnвующего виджета.
{
$widgets['widgets']['install'] = array(
array(
'widget_code' => 'amo_widget',
'settings' => array(
'sid' => '123321',
'token' => '123321',
'conf' => array(
'out_number' => '123321',
'application_sid' => '123321',
),
),
),
);
/* Теперь подготовим данные, необходимые для запроса к серверу */
$subdomain = 'test'; #Наш аккаунт - поддомен
#Формируем ссылку для запроса
$link = 'https://'.$subdomain.'.amocrm.ru/api/v2/widgets';
/* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой cURL (поставляется в составе PHP). Подробнее о работе с этой библиотекой Вы можете прочитать в мануале . */
$curl=curl_init(); #Сохраняем дескриптор сеанса cURL
#Устанавливаем необходимые опции для сеанса cURL
curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
curl_setopt($curl,CURLOPT_URL,$link);
curl_setopt($curl,CURLOPT_CUSTOMREQUEST,'POST');
curl_setopt($curl,CURLOPT_POSTFIELDS,json_encode($widgets));
curl_setopt($curl,CURLOPT_HTTPHEADER,array('Content-Type: application/json'));
curl_setopt($curl,CURLOPT_HEADER,false);
curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
$out=curl_exec($curl); #Инициируем запрос к API и сохраняем ответ в переменную
$code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
*/ Теперь мы можем обработать ответ, полученный от сервера. Это пример. Вы можете обработать данные своим способом. */
$code=(int)$code;
$errors=array(
301=>'Moved permanently',
400=>'Bad request',
401=>'Unauthorized',
403=>'Forbidden',
404=>'Not found',
500=>'Internal server error',
502=>'Bad gateway',
503=>'Service unavailable'
);
try
{
#Если код ответа не равен 200 или 204 - возвращаем сообщение об ошибке
if($code!=200 && $code!=204) {
throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
}
catch(Exception $E)
{
die('Ошибка: '.$E->getMessage().PHP_EOL.'Код ошибки: '.$E->getCode());
}
/**
* Данные получаем в формате JSON, поэтому, для получения читаемых данных,
* нам придётся перевести ответ в формат, понятный PHP
*/
$Response=json_decode($out,true);
$Response=$Response['response']['widgets']['install'];
$output='ID включённых виджетов:'.PHP_EOL;
foreach ($Response as $widget) {
$output .= $widget['widget_id'] . PHP_EOL;
}
return $output;
Для выключения виджета необходимо описать массив, содержащий информацию о настройках виджета и поместить его в массив следующего вида: $widgets[‘widgets’][‘uninstall’] Наше API также поддерживает одновременное выключение сразу нескольких виджетов. Для этого мы помещаем в массив $widgets[‘widgets’][‘uninstall’] несколько массивов, каждый из которых описывает необходимые данные настроек соответсвующего виджета.
{
$widgets['widgets']['uninstall'] = array(
array(
'widget_code' => 'amo_widget',
'settings' => array(
'sid' => '123321',
'token' => '123321',
'conf' => array(
'out_number' => '123321',
'application_sid' => '123321',
),
),
),
);
/* Теперь подготовим данные, необходимые для запроса к серверу */
$subdomain = 'test'; #Наш аккаунт - поддомен
#Формируем ссылку для запроса
$link = 'https://'.$subdomain.'.amocrm.ru/api/v2/widgets';
/* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой cURL (поставляется в составе PHP). Подробнее о работе с этой библиотекой Вы можете прочитать в мануале . */
$curl=curl_init(); #Сохраняем дескриптор сеанса cURL
#Устанавливаем необходимые опции для сеанса cURL
curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
curl_setopt($curl,CURLOPT_URL,$link);
curl_setopt($curl,CURLOPT_CUSTOMREQUEST,'POST');
curl_setopt($curl,CURLOPT_POSTFIELDS,json_encode($widgets));
curl_setopt($curl,CURLOPT_HTTPHEADER,array('Content-Type: application/json'));
curl_setopt($curl,CURLOPT_HEADER,false);
curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
$out=curl_exec($curl); #Инициируем запрос к API и сохраняем ответ в переменную
$code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
/* Теперь мы можем обработать ответ, полученный от сервера. Это пример. Вы можете обработать данные своим способом. */
$code=(int)$code;
$errors=array(
301=>'Moved permanently',
400=>'Bad request',
401=>'Unauthorized',
403=>'Forbidden',
404=>'Not found',
500=>'Internal server error',
502=>'Bad gateway',
503=>'Service unavailable'
);
try
{
#Если код ответа не равен 200 или 204 - возвращаем сообщение об ошибке
if($code!=200 && $code!=204) {
throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
}
catch(Exception $E)
{
die('Ошибка: '.$E->getMessage().PHP_EOL.'Код ошибки: '.$E->getCode());
}
}
/**
* Данные получаем в формате JSON, поэтому, для получения читаемых данных,
* нам придётся перевести ответ в формат, понятный PHP
*/
$Response=json_decode($out,true);
$Response=$Response['response']['widgets']['uninstall'];
$output='ID выключённых виджетов:' . PHP_EOL;
foreach ($Response as $widget) {
$output .= $widget['widget_id'] . PHP_EOL;
}
return $output;
Метод позволяет обновлять список доступных каналов получения сообщений для указанного виджета
POST /api/v2/widgets/sources
Параметр | Тип | Описание |
---|---|---|
code | string | Символьный код виджета |
services | object | Список доступных сервисов |
Сервис | Link |
---|---|
VK | ID страницы |
ID страницы | |
Telegram | Username бота |
Viber | ID публичной страницы |
Username профиля (instagram.com/username) | |
Номер телефона | |
Skype | ID бота |
Приведём пример запроса
{
"code": "amo_example_widget",
"services": {
"whatsapp": {
"pages": [
{
"id": "79999999999",
"link": "+79999999999",
"name": "Darth Vader"
}
]
},
"instagram": {
"pages": [
{
"id": "skywalker",
"link": "skywalker",
"name": "Luke"
}
]
},
}
}
Результат операции отражен в параметре success
{
"success": true,
"_links": {
"self": {
"_self": "/api/v2/widgets/sources",
"method": "get"
}
}
}