Виджеты

Виджет – это архив, содержащий набор файлов, которые будут подключаться в amoCRM всем аккаунтам, включившим виджет. Виджет позволяет получить дополнительный функционал, если необходимо:

  • Отображать дополнительные данные в интерфесах amoCRM. Для виджетов предусмотрены специальные области, где вы можете вывести информацию. Например, вывести статистику обращений по контакту из внутренней системы;
  • Взаимодействовать с пользователем, с введенными им данными. Вы можете подключать JS-скрипты практически в любом интерфейсе системы. Например, можно показывать всплывающую карточку при поступающем звонке;
  • Чтобы администратор аккаунта amoCRM ввел индивидуальные настройки для вашего сервиса. Например, ключ авторизации в вашем API.

Настроить виджеты может администратор аккаунт на странице Настройки->Интеграции.

Методы для работы с виджетами аккаунта

Эти методы доступны только администратору аккаунта

Метод API Описание
GET api/v2/widgets Метод для получения списка виджетов.
POST api/v2/widgets Метод позволяет включать или выключать виджеты по одному или пакетно.

Методы для работы с виджетами аккаунта

URL метода

GET /api/v2/widgets

Параметры GET

Параметр Описание
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'];

Включение и выключение виджетов

Метод позволяет включил и выключать виджеты по одному или пакетно, а также обновлять данные включённых и выключенных виджетов.

URL метода

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;