События

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

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

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

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

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