Виджеты

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

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

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

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

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

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

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

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;

Обновление списка доступных чатов

Метод позволяет обновлять список доступных каналов получения сообщений для указанного виджета

URL метода

POST /api/v2/widgets/sources

Параметры

Параметр Тип Описание
code string Символьный код виджета
services object Список доступных сервисов

Список доступных сервисов c описанием параметра link

Сервис Link
VK ID страницы
Facebook ID страницы
Telegram Username бота
Viber ID публичной страницы
Instagram Username профиля (instagram.com/username)
Whatsapp Номер телефона
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"
        }
    }
}