События и Примечания

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

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

Метод для получения списка с возможностью фильтрации и постраничной выборки. Ограничение по возвращаемым на одной странице данным – 100 событий. Валидный http-код ответа 200 и 204, если событий по фильтру не найдено.

URL метода

GET /api/v4/events

Параметры GET

Параметр Описание
limit Кол-во выбираемых строк (системное ограничение 100)
page Страница выборки
with В данном параметре указываются значения (список доступных значений), которые
дополнят ответ от API информацией.
filter[id] Фильтр по ID событий, передаются через запятую, не больше 100 за запрос. Например,
filter[id]=01drbfj5a8k9zd60bgg907a6w9,01drbfj5a8k9zd60bgg907a6w3.
filter[created_at] Фильтр по дате событий, передаются до 2-ух timestamp(int) через запятую. Если передан один параметр, то
список будет отфильтрован от переданного timestamp до текущего времени. Если передано два значения, то
список будет отфильтрован от первого timestamp до второго. Например,
filter[created_at]=1573102261,1573142261.
filter[created_by] Фильтр по пользователю, передаются до 10-ти ID пользователей, состоящих в аккаунте, через запятую.
Например, filter[created_by]=956328,504141.
filter[entity] Фильтр по типу сущности, передаются через запятую. Возможные параметры – lead, contact, company,
customer, task, catalog_{CATALOG_ID}. Например, filter[entity]=lead,contact,catalog_1075.
filter[entity_id] Фильтр по ID сущности, передаются до 10-ти ID через запятую. Для использования данного фильтра
обязательна передача фильтра filter[entity] и не более 1 сущности. Например,
filter[entity]=lead&filter[entity_id]=648533.
filter[type] Фильтр по типу событий. Типы перечисляются через запятую, подробней о возможных типах и ограничениях
читайте – тут.
filter[value_after] Фильтр по значению до. Подробней о возможных значения и ограничениях читайте – тут.
filter[value_after] Фильтр по значению после. Подробней о возможных значения и ограничениях читайте – тут.

Значения для фильтра по типу

Значения для фильтра по типу можно указать в соответствии со списком ниже или запросить через метод API.

Возможные значения

Значение Описание
lead_added Новая сделка
lead_deleted Сделка удалена
lead_restored Сделка восстановлена
lead_status_changed Изменение этапа продажи
lead_linked Прикрепление сделки
lead_unlinked Открепление сделки
contact_added Новый контакт
contact_deleted Контакт удален
contact_restored Контакт восстановлен
contact_linked Прикрепление контакта
contact_unlinked Открепление контакта
company_added Новая компания
company_deleted Компания удалена
company_restored Компания восстановлена
company_linked Прикрепление компании
company_unlinked Открепление компании
customer_added Новый покупатель
customer_deleted Покупатель удален
customer_status_changed Изменение этапа покупателя
customer_linked Прикрепление покупателя
customer_unlinked Открепление покупателя
task_added Новая задача
task_deleted Задача удалена
task_completed Завершение задачи
task_type_changed Изменение типа задачи
task_text_changed Изменение текста задачи
task_deadline_changed Изменение даты исполнения задачи
task_result_added Результат по задаче
incoming_call Входящий звонок
outgoing_call Исходящий звонок
incoming_chat_message Входящее сообщение
outgoing_chat_message Исходящее сообщение
incoming_sms Входящее SMS
outgoing_sms Исходящее SMS
entity_tag_added Теги добавлены
entity_tag_deleted Теги убраны
entity_linked Прикрепление
entity_unlinked Открепление
sale_field_changed Изменение поля “Бюджет”
name_field_changed Изменение поля “Название”
ltv_field_changed Сумма покупок
custom_field_value_changed Изменение поля
entity_responsible_changed Ответственный изменен
robot_replied Ответ робота
intent_identified Тема вопроса определена
nps_rate_added Новая оценка NPS
link_followed Переход по ссылке
transaction_added Добавлена покупка
common_note_added Новое примечание
common_note_deleted Примечание удалено
attachment_note_added Добавлен новый файл
targeting_in_note_added Добавление в ретаргетинг
targeting_out_note_added Удаление из ретаргетинга
geo_note_added Новое примечание с гео-меткой
service_note_added Новое системное примечание
site_visit_note_added Заход на сайт
message_to_cashier_note_added LifePay: Сообщение кассиру
entity_merged Выполнено объединение
custom_field_{FIELD_ID}_value_changed Изменение поля c переданным ID. Если вы передаете данный тип, то другие типы не могут быть переданы.

Значения для параметра with

Указывать можно более одного значения, через “,”.

Пример: https://example.amocrm.ru/api/v4/events?with=contact_name,lead_name

Возможные значения

Значение Описание
contact_name Если сущностью события является контакт, то помимо его ID, вы получите и название.
lead_name Если сущностью события является сделка, то помимо её ID, вы получите и название.
company_name Если сущностью события является компания, то помимо её ID, вы получите и название.
catalog_element_name Если сущностью события является элемент каталога, то помимо его ID, вы получите и название.
customer_name Если сущностью события является покупатель, то помимо его ID, вы получите и название.
catalog_name Если сущностью события является элемент каталога, то помимо ID каталога, к которому он относится, вы
получите и название каталога.

Значения для фильтра по значению до/после

В данный момент для фильтра по значению до/после доступны следующие значения:

  1. leads_statuses – фильтр по статусу сделки, доступен для
    события lead_status_changed
  2. customers_statuses – фильтр по статусу покупателя,
    доступен для события customer_status_changed
  3. responsible_user_id – фильтр по ответственному
    пользователю, доступен для события entity_responsible_changed
  4. custom_field_values – фильтр по enum значению поля,
    доступен для события custom_field_{FIELD_ID}_value_changed, в одном запросе должно передаваться не более 1 типа
    события.
  5. value – фильтр по точному значению, доступен для событий
    nps_rate_added, sale_field_changed, name_field_changed, ltv_field_changed, custom_field_value_changed

Описание фильтра по значению до/после – leads_statuses

Данный фильтр позволяет передать ID статусов и их воронок, чтобы получить только необходимые события смены статуса сделки.

Запрос должен быть составлен следующим образом:


filter[value_after][leads_statuses][0][pipeline_id]=13513&filter[value_after][leads_statuses][0][status_id]=17079863

В примере мы получим все события смены статуса этапа сделки, где сделка перешла в этап 17079863 воронки 13513.

Вы можете передать несколько значений в фильтр. Ниже приведен пример по формированию такого фильтра используя язык PHP:



$filter = [
    'filter' => [
        'value_after' => [
            'leads_statuses' => [
                [
                    'pipeline_id' => 13513,
                    'status_id' => 17079863,
                ],
                [
                    'pipeline_id' => 13513,
                    'status_id' => 17079860,
                ],
            ],
        ],
    ],
];

$filterUri = http_build_query($filter);

//filter%5Bvalue_after%5D%5Bleads_statuses%5D%5B0%5D%5Bpipeline_id%5D=13513&filter%5Bvalue_after%5D%5Bleads_statuses%5D%5B0%5D%5Bstatus_id%5D=17079863&filter%5Bvalue_after%5D%5Bleads_statuses%5D%5B1%5D%5Bpipeline_id%5D=13513&filter%5Bvalue_after%5D%5Bleads_statuses%5D%5B1%5D%5Bstatus_id%5D=17079860

Описание фильтра по значению до/после – customers_statuses

Данный фильтр позволяет передать ID статусов, чтобы получить только необходимые события смены статуса покупателя.

Запрос должен быть составлен следующим образом:


filter[value_after][customers_statuses][0][status_id]=135751

В примере мы получим все события смены статуса этапа покупателя, где покупатель перешел в этап 135751.

Вы можете передать несколько значений в фильтр. Ниже приведен пример по формированию такого фильтра используя язык PHP:



$filter = [
    'filter' => [
        'value_after' => [
            'customers_statuses' => [
                [
                    'status_id' => 135751,
                ],
                [
                    'status_id' => 135754,
                ],
            ],
        ],
    ],
];

$filterUri = http_build_query($filter);

//filter%5Bvalue_after%5D%5Bcustomers_statuses%5D%5B0%5D%5Bstatus_id%5D=135751&filter%5Bvalue_after%5D%5Bcustomers_statuses%5D%5B1%5D%5Bstatus_id%5D=135754

Описание фильтра по значению до/после – responsible_user_id

Данный фильтр позволяет передать ID пользователей, состоящих в аккаунте, через запятую, чтобы получить только необходимые события смены ответственного пользователя.

Запрос должен быть составлен следующим образом:


filter[value_after][responsible_user_id]=32321

В примере мы получим все события смены ответственного пользователя, где ID пользователя 448292.

Вы можете передать несколько значений в фильтр. Ниже приведен пример по формированию такого фильтра используя язык PHP:



$filter = [
    'filter' => [
        'value_after' => [
            'responsible_user_id' => '3231,412314',
        ],
    ],
];

$filterUri = http_build_query($filter);

//filter%5Bvalue_after%5D%5Bresponsible_user_id%5D=3221%2C412314

Описание фильтра по значению до/после – custom_field_values

Фильтр по enum значению поля, доступен для события custom_field_{FIELD_ID}_value_changed, в одном запросе должно
передаваться не более 1 типа события.

Данный фильтр позволяет передать enum значений поля, чтобы получить только необходимые события изменения значения поля.

Запрос должен быть составлен следующим образом:


filter[value_after][custom_field_values]=145&filter[type]=custom_field_57832_value_changed

В примере мы получим все события смены значения поля с ID 57832, где ID enum равен 145.

Вы можете передать несколько значений в фильтр. Ниже приведен пример по формированию такого фильтра используя язык PHP:



$filter = [
    'filter' => [
        'value_after' => [
            'custom_field_values' => '145,157,202',
        ],
        'type' => 'custom_field_57832_value_changed',
    ],
];

$filterUri = http_build_query($filter);

filter%5Bvalue_after%5D%5Bcustom_field_values%5D=145%2C157%2C202&filter%5Btype%5D=custom_field_57832_value_changed

Описание фильтра по значению до/после – value

Данный фильтр позволяет передать значение до/после. Он работает только со следующими типами событий: nps_rate_added,
sale_field_changed, name_field_changed, ltv_field_changed, custom_field_value_changed.

Запрос должен быть составлен следующим образом:


filter[value_after][value]=155&filter[type]=sale_field_changed&filter[entity]=lead

В примере мы получим все события смены изменения бюджета, где бюджет сделок стал равен 155.

Ниже приведен пример по формированию такого фильтра используя язык PHP:



$filter = [
    'filter' => [
        'value_after' => [
            'value' => '155',
        ],
        'type' => 'sale_field_changed',
        'entity' => 'lead',
    ],
];

$filterUri = http_build_query($filter);

//filter%5Bvalue_after%5D%5Bvalue%5D=155&filter%5Btype%5D=sale_field_changed&filter%5Bentity%5D=lead

Описание параметров ответа

Параметр Тип Описание
_links object Объект содержащий информацию о запросе
_embedded object Объект содержащий информацию прилегающую к запросу
_embedded[events] array Массив содержащий информацию по каждому отдельному элементу
_embedded/events/id string ID события
_embedded/events/type string Тип события
_embedded/events/entity_id int ID сущности события
_embedded/events/entity_type string Тип сущности события
_embedded/events/name string Название сущности события (возвращается, если передать необходимые with параметры)
_embedded/events/created_by int ID пользователя, который произвел событие
_embedded/events/created_at int Timestamp даты создания события
_embedded/events/value_before array Значение ДО (Возможные структуры данных)
_embedded/events/value_after array Значение ПОСЛЕ (Возможные структуры данных)
_embedded/events/_links object Объект содержащий ссылки на связанные с событием объекты

Возможные структуры данных в полях value_after и value_before

Структура данных в полях value_after и value_before зависит от типа события и может принимать разные значения.

  • Тип событий: lead_deleted, lead_restored, contact_deleted, contact_restored, company_deleted, company_restored, customer_deleted, entity_merged, task_added, task_deleted, task_completed
    Параметр Тип Описание
    value_after|value_before array Пустой массив
    
    {
        "value_after": [],
        "value_before": []
    }
    

  • Тип события: task_text_changed
    Параметр Тип Описание
    value_after|value_before array Массив с изменениями по событию (у данного типа всегда только одно изменение в массиве)
    value_after|value_before/0 object Объект с данными изменения
    value_after|value_before/0/task object Объект с данными изменения задачи
    value_after|value_before/0/task/text string Текст задачи
    
    {
        "value_after": [
              {
                "task": {
                  "text": "задача"
                }
              }
            ],
        "value_before": [
              {
                "task": {
                  "text": "задача old"
                }
              }
            ],
    }
    

  • Тип событий: robot_replied и intent_identified
    Параметр Тип Описание
    value_after array Массив с изменениями по событию (у данного типа всегда только одно изменение в массиве)
    value_after/0 object Объект с данными изменения
    value_after/0/helpbot object Объект с данными интента, который сработал
    value_after/0/helpbot/id int ID интента
    
    {
        "value_after": [
              {
                "helpbot": {
                  "id": 145
                }
              }
            ]
    }
    

  • Тип события: transaction_added
    Параметр Тип Описание
    value_after array Массив с изменениями по событию (у данного типа всегда только одно изменение в массиве)
    value_after/0 object Объект с данными изменения
    value_after/0/transaction object Объект с данными транзакции
    value_after/0/transaction/id int ID транзакции
    
    {
        "value_after": [
              {
                "transaction": {
                  "id": 33675
                }
              }
            ]
    }
    

  • Тип событий: lead_added, contact_added, company_added, customer_added, common_note_added, common_note_deleted, attachment_note_added, targeting_in_note_added, targeting_out_note_added, geo_note_added, service_note_added, site_visit_note_added, message_to_cashier_note_added, incoming_call, outgoing_call, incoming_sms, outgoing_sms, link_followed, task_result_added
    Параметр Тип Описание
    value_after array Массив с изменениями по событию (у данного типа всегда только одно изменение в массиве)
    value_after/0 object Объект с данными изменения
    value_after/0/note object Объект с данными примечания
    value_after/0/note/id int ID примечания
    
    {
        "value_after": [
              {
                "note": {
                  "id": 7422564
                }
              }
            ]
    }
    

  • Тип события: nps_rate_added
    Параметр Тип Описание
    value_after array Массив с изменениями по событию (у данного типа всегда только одно изменение в массиве)
    value_after/0 object Объект с данными изменения
    value_after/0/nps object Объект с данными оценки
    value_after/0/nps/rate int Оценка от 0 до 10
    
    {
        "value_after": [
              {
                "nps": {
                  "rate": 7
                }
              }
            ]
    }
    

  • Тип событий: incoming_chat_message и outgoing_chat_message
    Параметр Тип Описание
    value_after array Массив с изменениями по событию (у данного типа всегда только одно изменение в массиве)
    value_after/0 object Объект с данными изменения
    value_after/0/message object Объект с данными сообщения
    value_after/0/message/id string ID сообщения
    
    {
        "value_after": [
              {
                "message": {
                  "id": "1508b51c-aab0-428e-9322-611d847ae747"
                }
              }
            ]
    }
    

  • Тип событий: entity_tag_added и entity_tag_deleted
    Параметр Тип Описание
    value_after|value_before array Массив с изменениями по событию
    value_after|value_before/0 object Объект с данными изменения
    value_after|value_before/0/tag object Объект с данными тега
    value_after|value_before/0/tag/name string Название тега
    
    {
        "value_after": [
              {
                "tag": {
                  "name": "тег1"
                }
              }
            ],
        "value_before": [
              {
                "tag": {
                  "name": "тег2"
                }
              },
              {
                "tag": {
                  "name": "тег2"
                }
              }
            ]
    }
    

  • Тип события: lead_status_changed
    Параметр Тип Описание
    value_after|value_before array Массив с изменениями по событию
    value_after|value_before/0 object Объект с данными изменения (у данного типа всегда только одно изменение в массиве)
    value_after|value_before/0/lead_status object Объект с данными статуса
    value_after|value_before/0/lead_status/id int ID статуса
    value_after|value_before/0/lead_status/pipeline_id int ID воронки
    
    {
        "value_after": [
              {
                "lead_status": {
                  "id": 5233224,
                  "pipeline_id": 437642,
                }
              }
            ],
        "value_before": [
              {
                "lead_status": {
                  "id": 5233224,
                  "pipeline_id": 437642,
                }
              }
            ]
    }
    

  • Тип события: customer_status_changed
    Параметр Тип Описание
    value_after|value_before array Массив с изменениями по событию
    value_after|value_before/0 object Объект с данными изменения (у данного типа всегда только одно изменение в массиве)
    value_after|value_before/0/customer_status object Объект с данными статуса
    value_after|value_before/0/customer_status/id int ID статуса
    
    {
        "value_after": [
              {
                "customer_status": {
                  "id": 43832
                }
              }
            ],
        "value_before": [
              {
                "customer_status": {
                  "id": 53791
                }
              }
            ]
    }
    

  • Тип событий: customer_linked, customer_unlinked, company_linked, company_unlinked, contact_linked, contact_unlinked, lead_linked, lead_unlinked, entity_linked, entity_unlinked
    Параметр Тип Описание
    value_after|value_before array Массив с изменениями по событию (у данного типа всегда только одно изменение в массиве)
    value_after|value_before/0 object Объект с данными изменения
    value_after|value_before/0/link|unlink object Объект с данными cобытия
    value_after|value_before/0/link|unlink/entity object Объект с сущностью
    value_after|value_before/0/link|unlink/entity/type string Тип сущности
    value_after|value_before/0/link|unlink/entity/id int ID сущности
    
    {
        "value_after": [
              {
                "link": {
                  "entity": {
                    "type": "lead",
                    "id": 6232965
                  }
                }
              }
            ],
        "value_before": []
    }
    

  • Тип события: entity_responsible_changed
    Параметр Тип Описание
    value_after|value_before array Массив с изменениями по событию
    value_after|value_before/0 object Объект с данными изменения (у данного типа всегда только одно изменение в массиве)
    value_after|value_before/0/responsible_user object Объект с данными пользователя
    value_after|value_before/0/responsible_user/id int ID пользователя
    
    {
        "value_after": [
              {
                "responsible_user": {
                  "id": 504329
                }
              }
            ],
        "value_before": [
              {
                "responsible_user": {
                  "id": 37268
                }
              }
            ]
    }
    

  • Тип события: task_deadline_changed
    Параметр Тип Описание
    value_after|value_before array Массив с изменениями по событию
    value_after|value_before/0 object Объект с данными изменения (у данного типа всегда только одно изменение в массиве)
    value_after|value_before/0/task_deadline object Объект с данными срока выполнения задачи
    value_after|value_before/0/task_deadline/timestamp int Timestamp срока выполнения задачи
    
    {
        "value_after": [
              {
                "task_deadline": {
                  "timestamp": 1573595900
                }
              }
            ],
        "value_before": [
              {
                "task_deadline": {
                  "timestamp": 1573578700
                }
              }
            ]
    }
    

  • Тип события: task_type_changed
    Параметр Тип Описание
    value_after|value_before array Массив с изменениями по событию
    value_after|value_before/0 object Объект с данными изменения (у данного типа всегда только одно изменение в массиве)
    value_after|value_before/0/task_type object Объект с данными типа задачи
    value_after|value_before/0/task_type/id int ID типа задачи
    
    {
        "value_after": [
              {
                "task_type": {
                  "id": 504329
                }
              }
            ],
        "value_before": [
              {
                "task_type": {
                  "id": 37268
                }
              }
            ]
    }
    

  • Тип события: custom_field_value_changed
    Параметр Тип Описание
    value_after|value_before array Массив с изменениями по событию
    value_after|value_before/0 object Объект с данными изменения
    value_after|value_before/0/custom_field_value object Объект с данными изменения поля
    value_after|value_before/0/custom_field_value/field_id int ID измененого поля
    value_after|value_before/0/custom_field_value/field_type int Тип измененного поля
    value_after|value_before/0/custom_field_value/enum_id int|null ID enum значения поля, null, если у поля нет enum значений
    value_after|value_before/0/custom_field_value/text string Текст значения поля
    
    {
      "value_after": [
        {
          "custom_field_value": {
            "field_id": 53728,
            "field_type": 8,
            "enum_id": 2352876,
            "text": "example1@test.com"
          }
        },
        {
          "custom_field_value": {
            "field_id": 53728,
            "field_type": 8,
            "enum_id": 2352876,
            "text": "example@test.com"
          }
        }
      ],
      "value_before": [
        {
          "custom_field_value": {
            "field_id": 53728,
            "field_type": 8,
            "enum_id": 193200,
            "text": "example@test.com"
          }
        }
      ]
    }
    

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


Content-Type:application/hal+json

{
    "_page": 1,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/events?limit=3&page=1&offset=0"
        },
        "next": {
            "href": "https://example.amocrm.ru/api/v4/events?limit=3&page=2&offset=0"
        }
    },
    "_embedded": {
        "events": [
            {
                "id": "01e7t8ktqqy98edq62cxt2wtsm",
                "type": "custom_field_13485_value_changed",
                "entity_id": 14487933,
                "entity_type": "contact",
                "created_by": 0,
                "created_at": 1588945611,
                "value_after": [
                    {
                        "custom_field_value": {
                            "field_id": 13485,
                            "field_type": 8,
                            "enum_id": 19151,
                            "text": "New examle text"
                        }
                    }
                ],
                "value_before": [],
                "account_id": 321312,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/events/01e7t8ktqqy98edq62cxt2wtsm"
                    }
                }
            },
            {
                "id": "01e7t8ktqkbnjkb199ewrckdn1",
                "type": "contact_added",
                "entity_id": 16487933,
                "entity_type": "contact",
                "created_by": 0,
                "created_at": 1588945611,
                "value_after": [
                    {
                        "note": {
                            "id": 77161073
                        }
                    }
                ],
                "value_before": [],
                "account_id": 321312,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/events/01e7t8ktqkbnjkb199ewrckdn1"
                    }
                }
            },
            {
                "id": "01e7t8ktqg2ng9xjnnbhp0re4t",
                "type": "entity_linked",
                "entity_id": 165517933,
                "entity_type": "contact",
                "created_by": 261002,
                "created_at": 1588945611,
                "value_after": [
                    {
                        "link": {
                            "entity": {
                                "type": "lead",
                                "id": 9908375
                            }
                        }
                    }
                ],
                "value_before": [],
                "account_id": 312312,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/events/01e7t8ktqg2ng9xjnnbhp0re4t"
                    }
                }
            }
        ]
    }
}

Типы списка событий

Метод для получения типов событий с их переводом.

URL метода

GET /api/v4/events/types

Параметры GET

Параметр Описание
language_code Код языка, в котором вернутся названия типов событий. Если не передан, то вернется в языке пользователя,
под которым происходит запрос. Возможные параметры – en, es, ru.

Описание параметров ответа:

Параметр Тип Описание
_links array Массив содержащий информацию о запросе
_links/self array Массив содержащий информацию о текущем запросе
_embedded array Массив содержащий информацию прилегающую к запросу
_embedded/events_types array Массив содержащий информацию по каждому отдельному типу
_embedded/events_types/key string Тип события
_embedded/events_types/type int Числовое значение типа
_embedded/events_types/lang string Локализированное название события

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


Content-Type:application/hal+json

{
    "_total_items": 35,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/events/types?limit=6"
        }
    },
    "_embedded": {
        "events_types": [
            {
                "key": "lead_added",
                "type": 1,
                "lang": "Новая сделка"
            },
            {
                "key": "lead_deleted",
                "type": 7,
                "lang": "Сделка удалена"
            },
            {
                "key": "lead_restored",
                "type": 10,
                "lang": "Сделка восстановлена"
            },
            {
                "key": "lead_status_changed",
                "type": 14,
                "lang": "Изменение этапа продажи"
            },
            {
                "key": "lead_linked",
                "type": 80,
                "lang": "Прикрепление сделки"
            },
            {
                "key": "lead_unlinked",
                "type": 84,
                "lang": "Открепление сделки"
            },
            {
                "key": "contact_added",
                "type": 2,
                "lang": "Новый контакт"
            },
            {
                "key": "contact_deleted",
                "type": 8,
                "lang": "Контакт удален"
            },
            {
                "key": "contact_restored",
                "type": 11,
                "lang": "Контакт восстановлен"
            },
            {
                "key": "contact_linked",
                "type": 81,
                "lang": "Прикрепление контакта"
            },
            {
                "key": "contact_unlinked",
                "type": 85,
                "lang": "Открепление контакта"
            },
            {
                "key": "company_added",
                "type": 3,
                "lang": "Новая компания"
            },
            {
                "key": "company_deleted",
                "type": 9,
                "lang": "Компания удалена"
            },
            {
                "key": "company_restored",
                "type": 12,
                "lang": "Компания восстановлена"
            },
            {
                "key": "company_linked",
                "type": 82,
                "lang": "Прикрепление компании"
            },
            {
                "key": "company_unlinked",
                "type": 86,
                "lang": "Открепление компании"
            },
            {
                "key": "customer_added",
                "type": 20,
                "lang": "Новый покупатель"
            },
            {
                "key": "customer_deleted",
                "type": 53,
                "lang": "Покупатель удален"
            },
            {
                "key": "customer_status_changed",
                "type": 57,
                "lang": "Изменение этапа покупателя"
            },
            {
                "key": "customer_linked",
                "type": 83,
                "lang": "Прикрепление покупателя"
            },
            {
                "key": "customer_unlinked",
                "type": 87,
                "lang": "Открепление покупателя"
            },
            {
                "key": "task_added",
                "type": 49,
                "lang": "Новая задача"
            },
            {
                "key": "task_deleted",
                "type": 51,
                "lang": "Задача удалена"
            },
            {
                "key": "task_completed",
                "type": 29,
                "lang": "Завершение задачи"
            },
            {
                "key": "task_type_changed",
                "type": 76,
                "lang": "Изменение типа задачи"
            },
            {
                "key": "task_text_changed",
                "type": 77,
                "lang": "Изменение текста задачи"
            },
            {
                "key": "task_deadline_changed",
                "type": 78,
                "lang": "Изменение даты исполнения задачи"
            },
            {
                "key": "task_result_added",
                "type": 33,
                "lang": "Результат по задаче"
            },
            {
                "key": "incoming_call",
                "type": 17,
                "lang": "Входящий звонок"
            },
            {
                "key": "outgoing_call",
                "type": 30,
                "lang": "Исходящий звонок"
            },
            {
                "key": "incoming_chat_message",
                "type": 89,
                "lang": "Входящее сообщение"
            },
            {
                "key": "outgoing_chat_message",
                "type": 90,
                "lang": "Исходящее сообщение"
            },
            {
                "key": "incoming_sms",
                "type": 41,
                "lang": "Входящее SMS"
            },
            {
                "key": "outgoing_sms",
                "type": 42,
                "lang": "Исходящее SMS"
            },
            {
                "key": "entity_tag_added",
                "type": 63,
                "lang": "Теги добавлены"
            },
            {
                "key": "entity_tag_deleted",
                "type": 64,
                "lang": "Теги убраны"
            },
            {
                "key": "entity_segment_attached",
                "type": 94,
                "lang": "Добавлен в сегмент"
            },
            {
                "key": "entity_segment_detached",
                "type": 95,
                "lang": "Удалён из сегмента"
            },
            {
                "key": "entity_linked",
                "type": 72,
                "lang": "Прикрепление"
            }
        ]
    }
}

Примечания

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

Примечания бывают системные (исходящее/входящее смс,исходящий/входящий звонок,оплата счета, контакт создан и т.д.),а также созданные пользователем (текстовые примечания, файлы). Примечания в карточках отображаются на ряду с задачами, т.к. не имеют ответственного и не прикреплены к дате. В amoCRM существует 10 типов таких примечаний, которые можно редактировать.

Получение примечания по идентификатору

Метод позволяет получить примечание по ее идентификатору.

URL метода

GET /api/v4/{entity_type}/{entity_id}/notes/{id}

Параметры GET

Параметр Тип Описание
entity_type string Тип сущности к которой относится примечание: leads, contacts, companies, customers
entity_id int Уникальный идентификатор сущности
id int Уникальный идентификатор примечания

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


GET https://example.amocrm.ru/api/v4/leads/167749/notes/634999

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


{
    "id": 634999,
    "entity_id": 167749,
    "created_by": 3987910,
    "updated_by": 3987910,
    "created_at": 1575365541,
    "updated_at": 1575365548,
    "responsible_user_id": 123123,
    "group_id": 0,
    "note_type": "common",
    "params": {
        "text": "Отправили коммерческое предложение, нужно встречаться"
    },
    "account_id": 321312,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/leads/167749/notes/634999"
        }
    }
}

Возможные параметры примечания:

Параметр Тип Описание
id int Уникальный идентификатор примечания
account_id int Уникальный идентификатор аккаунта
entity_id int Уникальный идентификатор сущности
created_by int Кем создано примечание
created_at timestamp Когда была создана примечание
updated_by int Кем было обновлено примечание
updated_at timestamp Когда была обновлено примечание
responsible_user_id int ID ответственного
note_type string Тип добавляемого примечания. Доступные типы см. здесь
params object Объект с описанием передаваемой информацией для определенных типов примечаний. См. здесь
_links object Объект, содержащий информацию о текущем запросе

Типы примечания:

Тип Описание
common Обычное примечание
call_in Входящий звонок
call_out Исходящий звонок
service_message Системное сообщение
message_cashier Сообщение кассиру
invoice_paid Оплата счета
geolocation Геолокация
sms_in Входящее сообщение
sms_out Исходящее сообщение
extended_service_message Системное примечание

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


Тип примечания - common

"params": {
   "text": "Обычное примечание"
}

Тип примечания - call_in

"params": {
   "uniq": "8f52d38a-5fb3-406d-93a3-a4832dc28f8b",
   "duration": 60,
   "source": "onlinePBX",
   "link": "https://example.com",
   "phone": "+79999999999"
}

Тип примечания - call_out

"params": {
   "uniq": "8f52d38a-5fb3-406d-93a3-a4832dc28f8b",
   "duration": 60,
   "source": "onlinePBX",
   "link": "https://example.com", 
   "phone": "+79999999999"
}

Тип примечания - service_message

"params": {
   "service": "Сервис для примера",
   "text": "Текст для примечания"
}

Тип примечания - message_cashier

"params": {
    // Статус может быть один из следующих:
    // - created
    // - shown
    // - canceled
    "status": "created",
    "text": "Текст для примечания"
}

Тип примечания - invoice_paid

"params": {
   "icon_url": "https://example.com/icon.png",
   "service": "Netflix",
   "text": "Счет оплачен"
}

Тип примечания - geolocation

"params": {
   "text": "Геолокация",
   "address": "ул. Пушкина, дом Колотушкина",
   // долгота
   "longitude": "-13",
   // широта
   "latitude": "32"
}

Тип примечания - sms_in

"params": {
  "text": "Новое входящие сообщение",
  "phone": "+79999999999"
}

Тип примечания - sms_out

"params": {
   "text": "Новое исходящие сообщение",
   "phone": "+79999999999"
}

Получение примечаний по идентификатору сущности

Метод позволяет получить все примечания по ID сущности.

URL метода

GET /api/v4/{entity_type}/{entity_id}/notes

Параметры GET

Параметр Тип Описание
entity_type string Тип сущности к которой относится примечание: leads, contacts, companies, customers
entity_id int Уникальный идентификатор сущности

Возможные query параметры запроса:

Параметр Описание
page Страница выборки
limit Кол-во сущностей возвращаемых за один запрос (Системное ограничение – 250)
filter[note_type] Тип примечания. Можно перечислять через запятую. Доступные типы см. здесь

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


GET https://example.amocrm.ru/api/v4/leads/167749/notes?filter[note_type][]=common&limit=2

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


{
    "_page": 1,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/leads/notes?page=1&limit=50&offset=0"
        },
        "next": {
            "href": "https://example.amocrm.ru/api/v4/leads/notes?page=2&limit=50&offset=0"
        }
    },
    "_embedded": {
        "notes": [
            {
                "id": 634999,
                "entity_id": 167749,
                "created_by": 3987910,
                "updated_by": 3987910,
                "created_at": 1575365541,
                "updated_at": 1575365548,
                "responsible_user_id": 123123,
                "group_id": 0,
                "note_type": "common",
                "params": {
                    "text": "Отправили коммерческое предложение, нужно встречаться"
                },
                "account_id": 321321,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/167749/notes/634999"
                    }
                }
            },
            {
                "id": 635001,
                "entity_id": 167749,
                "created_by": 3987910,
                "updated_by": 3987910,
                "created_at": 1575365542,
                "updated_at": 1575365548,
                "responsible_user_id": 123123,
                "group_id": 0,
                "note_type": "common",
                "params": {
                    "text": "Большой тендер, участвуют почти все наши конкуренты. Нужно сделать интересное предложение"
                },
                "account_id": 321321,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/167749/notes/635001"
                    }
                }
            }
        ]
    }
}

Получение примечаний по типу сущности

Метод позволяет получить все примечания по типу сущности.

URL метода

GET /api/v4/{entity_type}/notes

Параметры GET

Параметр Тип Описание
entity_type string Тип сущности к которой относится примечание: leads, contacts, companies, customers

Возможные query параметры запроса описаны здесь

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


GET https://example.amocrm.ru/api/v4/leads/notes?filter[note_type][]=common&limit=2

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


{
    "_page": 1,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/leads/notes?limit=2&page=1&offset=0"
        },
        "next": {
            "href": "https://example.amocrm.ru/api/v4/leads/notes?limit=2&page=2&offset=0"
        }
    },
    "_embedded": {
        "notes": [
            {
                "id": 632661,
                "entity_id": 167353,
                "created_by": 3987910,
                "updated_by": 3987910,
                "created_at": 1575364048,
                "updated_at": 1575364220,
                "responsible_user_id": 123123,
                "group_id": 0,
                "note_type": "common",
                "params": {
                    "text": "20000 руб."
                },
                "account_id": 321321,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/167353/notes/632661"
                    }
                }
            },
            {
                "id": 633407,
                "entity_id": 167637,
                "created_by": 3987910,
                "updated_by": 3987910,
                "created_at": 1575364943,
                "updated_at": 1575364949,
                "responsible_user_id": 123123,
                "group_id": 0,
                "note_type": "common",
                "params": {
                    "text": "Примечание для примера"
                },
                "account_id": 321321,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/167637/notes/633407"
                    }
                }
            }
        ]
    }
}

Создание примечаний по типу сущности

Метод позволяет создавать примечания для сделок, контактов, компаний или покупателей.

URL метода

POST /api/v4/{entity_type}/notes

Параметры GET

Параметр Тип Описание
entity_type string Тип сущности к которой относится примечание: leads, contacts, companies, customers

Для создания примечания/примечаний необходимо передать массив, содержащий JSON с параметрами описанными здесь

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


В данном примере мы создадим несколько примечаний типов: invoice_paid, call_in, call_out, geolocation и привяжем их к сделке.

POST https://example.amocrm.ru/api/v4/leads/notes
Content-Type: application/json

[
    {
        "entity_id": 167353,
        "note_type": "invoice_paid",
        "params": {
            "icon_url": "https://example.com/icon.png",
            "service": "Netflix",
            "text": "Счет оплачен"
        }
    },
    {
        "entity_id": 167353,
        "note_type": "call_in",
        "params": {
            "uniq": "8f52d38a-5fb3-406d-93a3-a4832dc28f8b",
            "duration": 60,
            "source": "onlinePBX",
            "link": "https://example.com",
            "phone": "+79999999999"
        }
    },
    {
        "entity_id": 167353,
        "note_type": "call_out",
        "params": {
            "uniq": "8f52d38a-5fb3-406d-93a3-a4832dc28f8b",
            "duration": 60,
            "source": "onlinePBX",
            "link": "https://example.com",
            "phone": "+79999999999"
        }
    },
    {
        "entity_id": 167353,
        "note_type": "geolocation",
        "params": {
            "text": "Гео локация",
            "address": "ул. Пушкина, дом Колотушкина",
            "longitude": "-13",
            "latitude": "32"
        }
    }
]

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


{
    "_links": {
        "self": {
            "href": "http://example.amocrm.ru/api/v4/leads/notes"
        }
    },
    "_embedded": {
        "notes": [
            {
                "id": 76787983,
                "entity_id": 167353,
                "request_id": 0,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/167353/notes/76787983"
                    }
                }
            },
            {
                "id": 76787985,
                "entity_id": 167353,
                "request_id": 1,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/167353/notes/76787985"
                    }
                }
            },
            {
                "id": 76787987,
                "entity_id": 167353,
                "request_id": 2,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/167353/notes/76787987"
                    }
                }
            },
            {
                "id": 76787989,
                "entity_id": 167353,
                "request_id": 3,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/167353/notes/76787989"
                    }
                }
            }
        ]
    }
}

Создание примечаний по идентификатору сущности

Метод позволяет создавать примечания по ID сущности.

URL метода

POST /api/v4/{entity_type}/{entity_id}/notes

Параметры GET

Параметр Тип Описание
entity_type string Тип сущности к которой относится примечание: leads, contacts, companies, customers
entity_id int ID сущности к которой относится примечание.

Параметры доступные при создании примечаний описаны здесь

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


POST https://example.amocrm.ru/api/v4/leads/167353/notes
Content-Type: application/json

[
    {
        "note_type": "service_message",
        "params": {
            "service": "Сервис для примера",
            "text": "Системное примечание"
        }
    },
    {
        "note_type": "message_cashier",
        "params": {
            "status": "created",
            "text": "Сообщение кассиру"
        }
    }
]

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


{
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/leads/notes"
        }
    },
    "_embedded": {
        "notes": [
            {
                "id": 76582573,
                "entity_id": 167353,
                "request_id": 0,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/167353/notes/76582573"
                    }
                }
            },
            {
                "id": 76582575,
                "entity_id": 167353,
                "request_id": 1,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/167353/notes/76582575"
                    }
                }
            }
        ]
    }
}

Изменения примечаний

Метод позволяет изменять примечания для сделок, контактов, компаний или покупателей.

URL метода

PATCH /api/v4/{entity_type}/notes – для изменения по типу сущности

PATCH /api/v4/{entity_type}/{entity_id}/notes – для изменения по id сущности

PATCH /api/v4/{entity_type}/{entity_id}/notes/{id} – для изменения по id примечания

Возможные параметры GET

Параметр Тип Описание
entity_type string Тип сущности к которой относится примечание: leads, contacts, companies, customers
entity_id int Уникальный идентификатор сущности
id int Уникальный идентификатор примечания

Для изменения примечания/примечаний по типу/id сущности необходимо передать массив, содержащий JSON с параметрами описанными здесь

Пример изменения примечаний по типу сущности:


PATCH https://example.amocrm.ru/api/v4/leads/167353/notes
Content-Type: application/json

[
    {
        "id": 76610421,
        "note_type": "sms_in",
        "params": {
            "text": "Новое входящие сообщение",
            "phone": "+79999999999"
        }
    },
    {
        "id": 76610423,
        "note_type": "sms_out",
        "params": {
            "text": "Новое исходящие сообщение",
            "phone": "+79999999999"
        }
    }
]

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


{
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/leads/notes"
        }
    },
    "_embedded": {
        "notes": [
            {
                "id": 76610421,
                "entity_id": 167353,
                "updated_at": 1588841241,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/167353/notes/76610421"
                    }
                }
            },
            {
                "id": 76610423,
                "entity_id": 167353,
                "updated_at": 1588841241,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/167353/notes/76610423"
                    }
                }
            }
        ]
    }
}

Пример изменения примечания по идентификатору:


PATCH https://example.amocrm.ru/api/v4/leads/167353/notes/3110431
Content-Type: application/json

{
    "note_type": "common",
    "params": {
        "text": "Новый текст для примечания"
    }
}

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


{
    "id": 76610421,
    "entity_id": 167353,
    "updated_at": 1588841398,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/leads/167353/notes/3110431"
        }
    }
}