События

События предоставляют возможность добавлять дополнительную структурированную или неструктурированную информацию к элементу сущности. События бывают системные (звонки, СМС-сообщения и т.д.), созданные пользоваталем (примечания, файлы). События в карточках отображаются на ряду с задачами, т.к. не имеют ответственного и не прикреплены к дате.

Зачастую события используются виджетами для добавления дополнительной информации к сделке или контакту, когда не очень удобно использовать дополнительные поля. События очень удобно использовать как лог, т.к. они всегда отображаются в хронологическом порядке в ленте и, если ваша информация привязана к дате (хронологии), то желательно использовать именно события.

Добавление и обновление событий

Метод позволяет добавлять новые или обновлять уже существующие события.

URL метода
POST /api/v2/notes

Параметры

Параметр Тип Описание
add array Список добавляемых событий
update array Обновление существующих событий. Все параметры, которые описанны в add действуют также и в update
add/element_id
require
int id элемента, в карточку которого будет добавлено событие
add/element_type
require
int Тип сущности элемента, в карточку которого будет добавлено событие. Доступные типы см. здесь
add/text
require
string Текст события
add/note_type
require
int Тип добавляемого события. Доступные типы см. здесь
add/created_at timestamp Дата и время создания события
add/updated_at timestamp Дата и время изменения события
add/responsible_user_id int id пользователя ответственного за событие. При ограничении прав доступа, только этому пользователю будут доступны внесения изменений в данное событие в карточке сущности.
add/params int Массив с передаваемой информацией для определённых типов событий. См. здесь.
update/id
require
int id изменяемого события
update/updated_at
require
timestamp Дата и время изменения события

Типы сущностей

Код Описание
1 Контакт
2 Сделка
3 Компания
4 Задача. Для задачи доступен только тип события TASK_RESULT
12 Покупатель

Типы событий

Код Тип Описание
1 DEAL_CREATED Сделка создана
2 CONTACT_CREATED Контакт создан
3 DEAL_STATUS_CHANGED Статус сделки изменен
4 COMMON Обычное примечание
10 CALL_IN Входящий звонок
11 CALL_OUT Исходящий звонок
12 COMPANY_CREATED Компания создана
13 TASK_RESULT Результат по задаче
25 SYSTEM Системное сообщение
102 SMS_IN Входящее смс
103 SMS_OUT Исходящее смс

Типы событий, для которых обязателен массив params

Тип Структура Описание
10-11 'params' => [
'UNIQ' =>'676sdfs7fsdf',
'LINK' => 'www.testweb.ru/test_call.mp3',
'PHONE' => '84950000001',
'DURATION' => 58,
'SRC' => 'asterisk'
]
Параметры для создания события типа "звонок". Массив params передаётся вместо параметра text.
25 'params' => [
'text' => 'Текст системного сообщения',
'service' => 'Название сервиса',
]
Для типа события "системное сообщение", текст передаётся с помощью массива params, вместо параметра text.
102-103 'params' => [
'text' => 'Текст cмс сообщения'
]
Для типа события "cмс сообщение", текст передаётся с помощью массива params, вместо параметра text.

Пример запроса

  1. {
  2.    add: [
  3.       {
  4.          element_id: "1099238",
  5.          element_type: "1",
  6.          text: "Примечание",
  7.          note_type: "4",
  8.          created_at: "1509570000",
  9.          responsible_user_id: "504141",
  10.          created_by: "504141"
  11.       }
  12.    ],
  13.    update: [
  14.       {
  15.          id: "3323256",
  16.          updated_at: "1509656400",
  17.          text: "Изменение примечания"
  18.       }
  19.    ]
  20. }

Параметры ответа

Параметр Описание
id Уникальный идентификатор новой сущности
request_id Уникальный идентификатор сущности в клиентской программе, если request_id не передан в запросе, то он генерируется автоматически
_links Массив, содержащий информацию о запросе
_links/self Массив, содержащий информацию о текущем запросе
_links/self/href Относительный URL текущего запроса
_links/self/method Метод текущего запроса
_embedded Массив, содержащий информацию прилегающую к запросу
_embedded/items Массив, содержащий информацию по каждому отдельному элементу

Пример ответа

  1. {
  2.    _links: {
  3.       self: {
  4.          href: "/api/v2/notes",
  5.          method: "post"
  6.       }
  7.    },
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 3323255,
  12.             request_id: 0,
  13.             _links: {
  14.                self: {
  15.                   href: "/api/v2/notes?id=3323255",
  16.                   method: "get"
  17.                }
  18.             }
  19.          }
  20.       ]
  21.    }
  22. }

Пример интеграции

  1. $data = array (
  2.   'add' =>
  3.   array (
  4.     0 =>
  5.     array (
  6.       'element_id' => '1099238',
  7.       'element_type' => '1',
  8.       'text' => 'Примечание',
  9.       'note_type' => '4',
  10.       'created_at' => '1509570000',
  11.       'responsible_user_id' => '504141',
  12.       'created_by' => '504141',
  13.     ),
  14.   ),
  15. );
  16. $subdomain='test'; #Наш аккаунт - поддомен
  17. #Формируем ссылку для запроса
  18. $link='https://'.$subdomain.'.amocrm.ru/api/v2/notes';
  19. /* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой cURL (поставляется в составе PHP). Подробнее о
  20. работе с этой
  21. библиотекой Вы можете прочитать в мануале. */
  22. $curl=curl_init(); #Сохраняем дескриптор сеанса cURL
  23. #Устанавливаем необходимые опции для сеанса cURL
  24. curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
  25. curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
  26. curl_setopt($curl,CURLOPT_URL,$link);
  27. curl_setopt($curl,CURLOPT_CUSTOMREQUEST,'POST');
  28. curl_setopt($curl,CURLOPT_POSTFIELDS,json_encode($data));
  29. curl_setopt($curl,CURLOPT_HTTPHEADER,array('Content-Type: application/json'));
  30. curl_setopt($curl,CURLOPT_HEADER,false);
  31. curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  32. curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  33. curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
  34. curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
  35. $out=curl_exec($curl); #Инициируем запрос к API и сохраняем ответ в переменную
  36. $code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
  37. /* Теперь мы можем обработать ответ, полученный от сервера. Это пример. Вы можете обработать данные своим способом. */
  38. $code=(int)$code;
  39. $errors=array(
  40.   301=>'Moved permanently',
  41.   400=>'Bad request',
  42.   401=>'Unauthorized',
  43.   403=>'Forbidden',
  44.   404=>'Not found',
  45.   500=>'Internal server error',
  46.   502=>'Bad gateway',
  47.   503=>'Service unavailable'
  48. );
  49. try
  50. {
  51.   #Если код ответа не равен 200 или 204 - возвращаем сообщение об ошибке
  52.  if($code!=200 && $code!=204)
  53.     throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
  54. }
  55. catch(Exception $E)
  56. {
  57.   die('Ошибка: '.$E->getMessage().PHP_EOL.'Код ошибки: '.$E->getCode());
  58. }

Добавление звонков через событие

При указании соответствующих типов и параметров событие можно записать в карточку сущности как звонок.

Статусы звонка

Тип Описание
1 Оставил голосовое сообщение
2 Перезвонить позже
3 Нет на месте
4 Разговор состоялся
5 Неверный номер
6 Не дозвонился
7 Номер занят

Пример интеграции

  1. $notes['add'] = array(
  2.    array(
  3.      'element_id' => 2342344,
  4.      'element_type' => 2,
  5.      'note_type' => 10,
  6.      'params' => array(
  7.         'UNIQ' =>'676sdfs7fsdf',
  8.         'LINK' => 'www.testweb.ru/test_call.mp3',
  9.         'PHONE' => '84950000001',
  10.         'DURATION' => 58,
  11.         'SRC' => 'asterisk'
  12.         'call_status' => '3', //статус
  13.         'call_result' => 'Поговорили' //результат (необязательно)
  14.       )
  15.    )
  16. );
  17. $subdomain='test'; #Наш аккаунт - поддомен
  18. #Формируем ссылку для запроса
  19. $link='https://'.$subdomain.'.amocrm.ru/api/v2/notes';
  20. /* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой cURL (поставляется в составе PHP). Подробнее о
  21. работе с этой
  22. библиотекой Вы можете прочитать в мануале. */
  23. $curl=curl_init(); #Сохраняем дескриптор сеанса cURL
  24. #Устанавливаем необходимые опции для сеанса cURL
  25. curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
  26. curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
  27. curl_setopt($curl,CURLOPT_URL,$link);
  28. curl_setopt($curl,CURLOPT_CUSTOMREQUEST,'POST');
  29. curl_setopt($curl,CURLOPT_POSTFIELDS,json_encode($notes));
  30. curl_setopt($curl,CURLOPT_HTTPHEADER,array('Content-Type: application/json'));
  31. curl_setopt($curl,CURLOPT_HEADER,false);
  32. curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  33. curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  34. curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
  35. curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
  36. $out=curl_exec($curl); #Инициируем запрос к API и сохраняем ответ в переменную
  37. $code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
  38. /* Теперь мы можем обработать ответ, полученный от сервера. Это пример. Вы можете обработать данные своим способом. */
  39. $code=(int)$code;
  40. $errors=array(
  41.   301=>'Moved permanently',
  42.   400=>'Bad request',
  43.   401=>'Unauthorized',
  44.   403=>'Forbidden',
  45.   404=>'Not found',
  46.   500=>'Internal server error',
  47.   502=>'Bad gateway',
  48.   503=>'Service unavailable'
  49. );
  50. try
  51. {
  52.   #Если код ответа не равен 200 или 204 - возвращаем сообщение об ошибке
  53.  if($code!=200 && $code!=204)
  54.     throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',(int)$code);
  55. }
  56. catch(Exception $E)
  57. {
  58.   die('Ошибка: '.$E->getMessage().PHP_EOL.'Код ошибки: '.$E->getCode());
  59. }

Список событий

Метод для получения списка примечаний с возможностью фильтрации и постраничной выборки. Ограничение по возвращаемым на одной странице (offset) данным - 500 записей.

URL метода
GET /api/v2/notes

Параметры запроса

Тип Описание
type
require
contact/lead/company/task
Получение данных только для указанной сущности
id Выбрать элемент с заданным ID (Если указан этот параметр, все остальные игнорируются). Можно передавать в виде массива состоящий из нескольких ID.
limit_rows Кол-во выбираемых строк (системное ограничение 500)
limit_offset Оффсет выборки (с какой строки выбирать). Работает, только при условии, если limit_rows тоже указан.
element_id Уникальный идентификатор элемента сущности
note_type Уникальный идентификатор контакта или сделки. Таблицу типов см. здесь.
if-modified-since Выбрать события, изменённые от определённой даты. Данные нужно передавать в формате D, d M Y H:i:s через HTTP- заголовок.

Параметры ответа

Параметр Тип Описание
id int Уникальный идентификатор примечания
created_by int id пользователя, создавшего примечание
account_id int Уникальный идентификатор аккаунта
group_id int id группы, в которой состоит пользователь, имеющий отношение к событию
is_editable bool Можно ли изменять данное событие
element_id int id элемента, в карточку которого будет добавлено событие
element_type int Тип сущности элемента, в карточку которого будет добавлено событие. Доступные типы см. здесь
text string Текст события
note_type int Тип добавляемого события. Доступные типы см. здесь
created_at timestamp Дата и время создания события
updated_at timestamp Дата и время изменения события
responsible_user_id int id пользователя ответственного за событие. При ограничении прав доступа, только этому пользователю будут доступны внесения изменений в данное событие в карточке сущности.
params array Массив, содержащий параметры, обязателен для определённого типа событий. Типы событий см. здесь.
params/UNIQ string Уникальный код звонка
params/LINK string Ссылка на запись звонка
params/PHONE string Внешний номер телефона
params/DURATION string Продолжительность звонка
params/SRC string Код виджета или сервиса, через который был совершён звонок
params/call_status string Статус звонка. Подробное описание статусов здесь.
params/call_result string Результат звонка
_links array Массив, содержащий информацию о запросе
_links/self array Массив, содержащий информацию о текущем запросе
_links/self/href string Относительный URL текущего запроса
_links/self/method string Метод текущего запроса
_embedded array Массив, содержащий информацию прилегающую к запросу
_embedded/items array Массив, содержащий информацию по каждому отдельному элементу

Пример ответа

  1. {
  2.    _links: {
  3.       self: {
  4.          href: "/api/v2/notes?type=lead",
  5.          method: "get"
  6.       }
  7.    },
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 3321308,
  12.             responsible_user_id: 504141,
  13.             created_by: 504141,
  14.             created_at: 1508675473,
  15.             updated_at: 1508675473,
  16.             account_id: 13667499,
  17.             group_id: 0,
  18.             is_editable: false,
  19.             element_id: 1090344,
  20.             element_type: 2,
  21.             attachment: "",
  22.             note_type: 1,
  23.             text: "Добавлен новый объект",
  24.             _links: {
  25.                self: {
  26.                   href: "/api/v2/notes?id=3321308&type=lead",
  27.                   method: "get"
  28.                }
  29.             }
  30.          },
  31.          {
  32.             id: 3321625,
  33.             responsible_user_id: 504141,
  34.             created_by: 504141,
  35.             created_at: 1509016950,
  36.             updated_at: 1509016950,
  37.             account_id: 13667499,
  38.             group_id: 0,
  39.             is_editable: false,
  40.             element_id: 1090391,
  41.             element_type: 2,
  42.             attachment: "",
  43.             note_type: 1,
  44.             text: "Добавлен новый объект",
  45.             _links: {
  46.                self: {
  47.                   href: "/api/v2/notes?id=3321625&type=lead",
  48.                   method: "get"
  49.                }
  50.             }
  51.          },
  52.          {
  53.             id: 3322827,
  54.             responsible_user_id: 504141,
  55.             created_by: 504141,
  56.             created_at: 1509447477,
  57.             updated_at: 1509447477,
  58.             account_id: 13667499,
  59.             group_id: 0,
  60.             is_editable: false,
  61.             element_id: 1090571,
  62.             element_type: 2,
  63.             attachment: "",
  64.             note_type: 10,
  65.             params: {
  66.                UNIQ: "1564655648655485",
  67.                LINK: "example.com/record/18456.mp3",
  68.                PHONE: "84951563241",
  69.                DURATION: "153",
  70.                SRC: "2das256d25fc56s56v159b6"
  71.             },
  72.             _links: {
  73.                self: {
  74.                   href: "/api/v2/notes?id=3322827&type=lead",
  75.                   method: "get"
  76.                }
  77.             }
  78.          }
  79.       ]
  80.    }
  81. }

Пример интеграции

  1. $subdomain='test'; #Наш аккаунт - поддомен
  2. #Формируем ссылку для запроса
  3. $link='https://'.$subdomain.'.amocrm.ru/api/v2/notes?type=contact';
  4. /* Заметим, что в ссылке можно передавать и другие параметры, которые влияют на выходной результат (смотрите
  5. документацию).
  6. Следовательно, мы можем заменить ссылку, приведённую выше на одну из следующих, либо скомбинировать параметры так, как
  7. Вам
  8. необходимо. */
  9. $link='https://'.$subdomain.'.amocrm.ru/api/v2/notes?limit_rows=50';
  10. $link='https://'.$subdomain.'.amocrm.ru/api/v2/notes?type=contact&limit_rows=50';
  11. $link='https://'.$subdomain.'.amocrm.ru/api/v2/notes?limit_offset=2';
  12. $link='https://'.$subdomain.'.amocrm.ru/api/v2/notes?type=lead&limit_rows=50&limit_offset=2';
  13. /* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой cURL (поставляется в составе PHP). Подробнее о
  14. работе с этой
  15. библиотекой Вы можете прочитать в мануале. */
  16. $curl=curl_init(); #Сохраняем дескриптор сеанса cURL
  17. #Устанавливаем необходимые опции для сеанса cURL
  18. curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
  19. curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
  20. curl_setopt($curl,CURLOPT_URL,$link);
  21. curl_setopt($curl,CURLOPT_HEADER,false);
  22. curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  23. curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  24. curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
  25. curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
  26. /* Вы также можете передать дополнительный HTTP-заголовок IF-MODIFIED-SINCE, в котором указывается дата в формате D, d M
  27. Y
  28. H:i:s. При
  29. передаче этого заголовка, будут возвращены примечания, изменённые позже этой даты. */
  30. curl_setopt($curl,CURLOPT_HTTPHEADER,array('IF-MODIFIED-SINCE: Mon, 01 Aug 2017 08:12:22'));
  31. /* Выполняем запрос к серверу. */
  32. $out=curl_exec($curl); #Инициируем запрос к API и сохраняем ответ в переменную
  33. $code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
  34. curl_close($curl);
  35. /* Теперь мы можем обработать ответ, полученный от сервера. Это пример. Вы можете обработать данные своим способом. */
  36. $code=(int)$code;
  37. $errors=array(
  38.   301=>'Moved permanently',
  39.   400=>'Bad request',
  40.   401=>'Unauthorized',
  41.   403=>'Forbidden',
  42.   404=>'Not found',
  43.   500=>'Internal server error',
  44.   502=>'Bad gateway',
  45.   503=>'Service unavailable'
  46. );
  47. try
  48. {
  49.   #Если код ответа не равен 200 или 204 - возвращаем сообщение об ошибке
  50.  if($code!=200 && $code!=204)
  51.     throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
  52. }
  53. catch(Exception $E)
  54. {
  55.   die('Ошибка: '.$E->getMessage().PHP_EOL.'Код ошибки: '.$E->getCode());
  56. }