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

В данном разделе описывается работа со списком событий и примечаниями сущностей

Оглавление

Общая информация о событиях

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

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

Метод

GET /api/v4/events

Описание

Метод позволяет получить список событий.

Ограничения

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

GET параметры

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

Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
200 Запрос выполнен успешно
401 Пользователь не авторизован
402 Аккаунт не оплачен

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

Метод возвращает коллекцию моделей событий, рассмотрим ниже свойства события.

Параметр Тип данных Описание
id string ID события
type string Тип события
entity_id int ID сущности события
entity_type string Сущность события
created_by int ID пользователя, создавший событие
created_at int Дата создания события, передается в Unix Timestamp
value_after array Массив с изменениями по событию. Подробней о свойствах изменения читайте тут
value_before array Массив с изменениями по событию. Подробней о свойствах изменения читайте тут
account_id int ID аккаунта, в котором находится событие

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

{
    "_page": 1,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/events?limit=1&page=1"
        },
        "next": {
            "href": "https://example.amocrm.ru/api/v4/events?limit=1&page=2"
        }
    },
    "_embedded": {
        "events": [
            {
                "id": "01pz58t6p04ymgsgfbmfyfy1mf",
                "type": "lead_added",
                "entity_id": 26060763,
                "entity_type": "lead",
                "created_by": 939801,
                "created_at": 1888888888,
                "value_after": [
                    {
                        "note": {
                            "id": 42743871
                        }
                    }
                ],
                "value_before": [],
                "account_id": 17079858,
                "_links": {
                    "self": {
                        "href": https://example.amocrm.ru/api/v4/events/01pz58t6p04ymgsgfbmfyfy1mf"
                    }
                },
                "_embedded": {
                    "entity": {
                        "id": 26060763,
                        "_links": {
                            "self": {
                                "href": "https://example.amocrm.ru/api/v4/leads/26060763"
                            }
                        }
                    }
                }
            }
        ]
    }
}

Параметры для GET-параметра with

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

Получение события по ID

Метод

GET /api/v4/events/{id}

Описание

Метод позволяет получить данные конкретного события по ID.

Ограничения

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

GET параметры

Параметр Тип данных Описание
with string Данный параметр принимает строку, в том числе из нескольких значений, указанных через запятую. Данный метод поддерживает следующие параметры.

Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
200 Запрос выполнен успешно
401 Пользователь не авторизован
402 Аккаунт не оплачен

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

Метод возвращает модель события, рассмотрим ниже свойства события.

Параметр Тип данных Описание
id string ID события
type string Тип события
entity_id int ID сущности события
entity_type string Сущность события
created_by int ID пользователя, создавший событие
created_at int Дата создания события, передается в Unix Timestamp
value_after array Массив с изменениями по событию. Подробней о свойствах изменения читайте тут
value_before array Массив с изменениями по событию. Подробней о свойствах изменения читайте тут
account_id int ID аккаунта, в котором находится событие

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

{
    "id": "01pz58t6p04ymgsgfbmfyfy1mf",
    "type": "lead_added",
    "entity_id": 26060763,
    "entity_type": "lead",
    "created_by": 939801,
    "created_at": 1888888888,
    "value_after": [
        {
            "note": {
                "id": 42743871
            }
        }
    ],
    "value_before": [],
    "account_id": 17079858,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/events/01pz58t6p04ymgsgfbmfyfy1mf"
        }
    },
    "_embedded": {
        "entity": {
            "id": 26060763,
            "_links": {
                "self": {
                    "href": "https://example.amocrm.ru/api/v4/leads/26060763"
                }
            }
        }
    }
}

Параметры для GET-параметра with

Параметр Описание
catalog_elements Добавляет в ответ связанные со сделками элементы списков
is_price_modified_by_robot Добавляет в ответ свойство, показывающее, изменен ли в последний раз бюджет сделки роботом
loss_reason Добавляет в ответ расширенную информацию по причине отказа
contacts Добавляет в ответ информацию о связанных со сделкой контактах
only_deleted Если передать данный параметр, то в ответе на запрос метода, вернутся удаленные сделки, которые еще находятся в корзине. В ответ вы получите модель сделки, у которой доступны дату изменения, ID пользователя сделавшего последнее изменение, её ID и параметр is_deleted = true.

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

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

  • leads_statuses – фильтр по статусу сделки, доступен для события lead_status_changed

  • customers_statuses – фильтр по статусу покупателя, доступен для события customer_status_changed

  • responsible_user_id – фильтр по ответственному пользователю, доступен для события entity_responsible_changed

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

  • 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

Структуры данных в полях 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_replie и 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, entity_direct_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"
        }
      }
    ]
}

Типы событий

Возможные типы событий

Значение Описание
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 Исходящее сообщение
entity_direct_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: Сообщение кассиру
key_action_completed Ключевое действие
entity_merged Выполнено объединение
custom_field_{FIELD_ID}_value_changed Изменение поля c переданным ID. Если вы передаете данный тип, то другие типы не могут быть переданы.

Получение типов событий

Метод

GET /api/v4/events/types

Описание

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

Ограничения

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

GET параметры

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

Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
200 Запрос выполнен успешно
401 Пользователь не авторизован
402 Аккаунт не оплачен

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

Метод возвращает коллекцию моделей типов событий, рассмотрим ниже свойства.

Параметр Тип данных Описание
key string Код типа события
type int Идентификатор типа события
lang string Локализованное название события

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

{
    "_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": "Сделка удалена"
            },
            ...
        ]
    }
}

Общая информация о примечаниях

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

Типы примечаний

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

Тип Название
common Текстовое примечание
call_in Входящий звонок
call_out Исходящий звонок
service_message Системное сообщение (добавляется интеграциями)
message_cashier Сообщение кассиру
geolocation Текстовое примечание с гео-координатами (добавляются мобильным приложением)
sms_in Входящее SMS
sms_out Исходящее SMS
extended_service_message Расширенное системное сообщение (поддерживает больше текста и сворачивается в интерфейсе)
attachment Примечание с файлом

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

"params": {
  "version_uuid": "5e316440-4122-4cad-b121-9709882b4cc1", // версия файла, можно не передавать, будет использована последняя версия
  "file_uuid": "9905db7c-3a29-4d30-8953-bac68c05e8e8",
  "file_name": "изображение.png", // название файла, которое будет отображаться в примечании
}

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

Метод

GET /api/v4/{entity_type}/notes

Описание

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

Ограничения

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

GET параметры

Параметр Тип данных Описание
page int Страница выборки
limit int Количество возвращаемых сущностей за один запрос (Максимум – 250)
filter object Фильтр
filter[id] int|array Фильтр по ID примечаний. Можно передать как один ID, так и массив из нескольких ID
filter[entity_id] array Фильтр по ID сущности. Можно передать массив из нескольких ID
filter[note_type] string|array Фильтр по типу примечания.
filter[updated_at] int|object Фильтр по дате последнего изменения примечания.
Можно передать timestamp, в таком случае будут возвращены примечания, которые были изменены после переданного значения.
Также можно передать массив вида filter[updated_at][from]=… и filter[updated_at][to]=…, для фильтрации по значениям ОТ и ДО.
order object Сортировка результатов списка.
Доступные поля для сортировки: updated_at, id.
Доступные значения для сортировки: asc, desc.
Пример: /api/v4/leads/notes?order[updated_at]=asc

Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
200 Запрос выполнен успешно
401 Пользователь не авторизован
402 Аккаунт не оплачен

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

Метод возвращает коллекцию моделей примечаний, рассмотрим ниже свойства примечаний.

Параметр Тип данных Описание
id int ID примечания
entity_id int ID родительской сущности примечания
created_by int ID пользователя, создавший примечание
updated_by int ID пользователя, изменивший примечание последним
created_at int Дата создания примечания, передается в Unix Timestamp
updated_at int Дата изменения примечания, передается в Unix Timestamp
responsible_user_id int ID пользователя, ответственного за примечание
group_id int ID группы, в которой состоит ответственны пользователь за примечание
note_type string Тип примечания
params object Свойства примечания, зависят от типа примечания. Подробней о свойствах читайте тут
account_id int ID аккаунта, в котором находится примечание

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

{
    "_page": 1,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/leads/notes?filter%5Bid%5D%5B0%5D=42709325&filter%5Bid%5D%5B1%5D=42709842&page=1&limit=50"
        },
        "next": {
            "href": "https://example.amocrm.ru/api/v4/leads/notes?filter%5Bid%5D%5B0%5D=42709325&filter%5Bid%5D%5B1%5D=42709842&page=2&limit=50"
        }
    },
    "_embedded": {
        "notes": [
            {
                "id": 42709325,
                "entity_id": 26050861,
                "created_by": 940088,
                "updated_by": 940088,
                "created_at": 1540407495,
                "updated_at": 1540408317,
                "responsible_user_id": 939801,
                "group_id": 0,
                "note_type": "common",
                "params": {
                    "text": "Текст примечания"
                },
                "account_id": 17079858,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/26050861/notes/42709325"
                    }
                }
            },
            {
                "id": 42709842,
                "entity_id": 26053794,
                "created_by": 939801,
                "updated_by": 939801,
                "created_at": 1548280113,
                "updated_at": 1548280115,
                "responsible_user_id": 939801,
                "group_id": 0,
                "note_type": "attachment",
                "params": {
                    "is_drive_attachment": true,
                    "text": "Снимок экрана 2022-12-12 в 20.11.45 (1).jpg",
                    "original_name": "Снимок экрана 2022-12-12 в 20.11.45 (1).jpg",
                    "file_uuid": "6905db7c-3a29-4d30-8953-bac68c05e8e8",
                    "version_uuid": "4e316440-4122-4cad-b121-9709882b4cc1",
                    "file_name": "Snimok_ekrana_2022-12-12_v_20.11.45_1_.jpg"
                },
                "account_id": 17079858,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/26053794/notes/42709842"
                    }
                }
            }
        ]
    }
}

Список примечаний по конкретной сущности, по ID сущности

Метод

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

Описание

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

Ограничения

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

GET параметры

Параметр Тип данных Описание
page int Страница выборки
limit int Количество возвращаемых сущностей за один запрос (Максимум – 250)
filter object Фильтр
filter[id] int|array Фильтр по ID примечаний. Можно передать как один ID, так и массив из нескольких ID
filter[note_type] string|array Фильтр по типу примечания.
filter[updated_at] int|object Фильтр по дате последнего изменения примечания.
Можно передать timestamp, в таком случае будут возвращены примечания, которые были изменены после переданного значения.
Также можно передать массив вида filter[updated_at][from]=… и filter[updated_at][to]=…, для фильтрации по значениям ОТ и ДО.
order object Сортировка результатов списка.
Доступные поля для сортировки: updated_at, id.
Доступные значения для сортировки: asc, desc.
Пример: /api/v4/leads/notes?order[updated_at]=asc

Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
200 Запрос выполнен успешно
401 Пользователь не авторизован
402 Аккаунт не оплачен

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

Метод возвращает коллекцию моделей примечаний, рассмотрим ниже свойства примечаний.

Параметр Тип данных Описание
id int ID примечания
entity_id int ID родительской сущности примечания
created_by int ID пользователя, создавший примечание
updated_by int ID пользователя, изменивший примечание последним
created_at int Дата создания примечания, передается в Unix Timestamp
updated_at int Дата изменения примечания, передается в Unix Timestamp
responsible_user_id int ID пользователя, ответственного за примечание
group_id int ID группы, в которой состоит ответственны пользователь за примечание
note_type string Тип примечания
params object Свойства примечания, зависят от типа примечания. Подробней о свойствах читайте тут
account_id int ID аккаунта, в котором находится примечание

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

{
    "_page": 1,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/leads/26050861/notes?limit=2&page=1"
        },
        "next": {
            "href": "https://example.amocrm.ru/api/v4/leads/26050861/notes?limit=2&page=2"
        }
    },
    "_embedded": {
        "notes": [
            {
                "id": 42709325,
                "entity_id": 26050861,
                "created_by": 940088,
                "updated_by": 940088,
                "created_at": 1540407495,
                "updated_at": 1540408317,
                "responsible_user_id": 939801,
                "group_id": 0,
                "note_type": "common",
                "params": {
                    "text": "Текст примечания 2"
                },
                "account_id": 17079858,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/26050861/notes/42709325"
                    }
                }
            },
            {
                "id": 42736075,
                "entity_id": 26050861,
                "created_by": 939801,
                "updated_by": 939801,
                "created_at": 1587555198,
                "updated_at": 1587555199,
                "responsible_user_id": 939801,
                "group_id": 0,
                "note_type": "common",
                "params": {
                    "text": "Текст примечания"
                },
                "account_id": 17079858,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/26050861/notes/42736075"
                    }
                }
            }
        ]
    }
}

Получение примечания по ID

Метод

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

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

Описание

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

Ограничения

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

Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
200 Запрос выполнен успешно
401 Пользователь не авторизован
402 Аккаунт не оплачен

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

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

Параметр Тип данных Описание
id int ID примечания
entity_id int ID родительской сущности примечания
created_by int ID пользователя, создавший примечание
updated_by int ID пользователя, изменивший примечание последним
created_at int Дата создания примечания, передается в Unix Timestamp
updated_at int Дата изменения примечания, передается в Unix Timestamp
responsible_user_id int ID пользователя, ответственного за примечание
group_id int ID группы, в которой состоит ответственны пользователь за примечание
note_type string Тип примечания
params object Свойства примечания, зависят от типа примечания. Подробней о свойствах читайте тут
account_id int ID аккаунта, в котором находится примечание

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

{
    "id": 42709325,
    "entity_id": 26050861,
    "created_by": 940088,
    "updated_by": 940088,
    "created_at": 1540407495,
    "updated_at": 1540408317,
    "responsible_user_id": 939801,
    "group_id": 0,
    "note_type": "common",
    "params": {
        "text": "Текст примечания"
    },
    "account_id": 17079858,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/leads/26050861/notes/42709325"
        }
    }
}

Добавление примечаний

Метод

POST /api/v4/{entity_type}/notes

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

Описание

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

Ограничения

Метод доступен всем пользователям аккаунта. Успешность выполнения действия зависит от прав на сущность.

Заголовок запроса

Content-Type: application/json

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

Параметр Тип данных Описание
entity_id int ID сущности, в которую добавляется примечание. Обязателен при использовании метода создания примечания в сущности, если создание идет через метод /api/v4/{entity_type}/{entity_id}/notes, то данный параметр передавать не нужно
created_by int ID пользователя, от имени которого добавляется примечание. При добавлении звонка, в таймлайне карточки, пользователь будет отображен как автор звонка или как принимающий, в зависимости от типа звонка
note_type string Тип примечания. Возможные типы примечаний
responsible_user_id int ID пользователя, ответственного за примечание. Необязательный параметр.
params object Свойства примечания, зависят от типа примечания. Подробней о свойствах читайте тут
request_id string Поле, которое вернется вам в ответе без изменений и не будет сохранено. Необязательный параметр
is_need_to_trigger_digital_pipeline bool Нужно ли отправлять события в Digital Pipeline. Необязательный параметр. Если флаг не передан или передан со значением true, триггеры Digital Pipeline отрабатывать будут, если передано false – не будут. Влияет такие триггеры: счет оплачен, звонок соверешен и другие, которые запускаются при добавлении примечания.

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

[
    {
        "entity_id": 167353,
        "note_type": "call_in",
        "responsible_user_id": 8238874,
        "params": {
            "uniq": "8f52d38a-5fb3-406d-93a3-a4832dc28f8b",
            "duration": 60,
            "source": "onlinePBX",
            "link": "https://example.com",
            "phone": "+79999999999"
        }
    },
    {
        "entity_id": 167353,
        "note_type": "call_out",
        "responsible_user_id": 8238874,
        "params": {
            "uniq": "8f52d38a-5fb3-406d-93a3-a4832dc28f8b",
            "duration": 60,
            "source": "onlinePBX",
            "link": "https://example.com",
            "phone": "+79999999999"
        }
    },
    {
        "entity_id": 167353,
        "note_type": "geolocation",
        "responsible_user_id": 8238874,
        "params": {
            "text": "Примечание с геолокацией",
            "address": "ул. Пушкина, дом Колотушкина, квартира Вольнова",
            "longitude": "53.714816",
            "latitude": "91.423146"
        }
    }
]

Пример запроса для отображения в разделе "Аналитика" для примечаний типа call_in и call_out.

Для того, чтобы в разделе "Аналитика" по указанному user_id отображались звонки, необходимо передавать следующие параметры.
При этом responsible_user_id и created_by должны быть одинаковыми

[
  {
    "note_type": "call_in",
    "created_by": 32321,
    "responsible_user_id": 32321,
    "params": {
      "uniq": "8f52d38a-5fb3-406d-93a3-a4832dc28f8b",
      "duration": 60,
      "source": "onlinePBX",
      "link": "https://example.com",
      "phone": "+79999999999"
    }
  },
  {
    "note_type": "call_out",
    "created_by": 32321,
    "responsible_user_id": 32321,
    "params": {
      "uniq": "8f52d38a-5fb3-406d-93a3-a4832dc28f8b",
      "duration": 60,
      "source": "onlinePBX",
      "link": "https://example.com",
      "phone": "+79999999999"
    }
  }
]

Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
200 Примечания были успешно созданы
403 Не хватает прав для вызова данного метода
401 Пользователь не авторизован
400 Переданы некорректные данные. Подробности доступны в теле ответа

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

Метод возвращает коллекцию примечаний, которые были созданы.

Параметр Тип данных Описание
id int ID примечания
entity_id int ID сущности, в которое было добавлено примечание
request_id string Строка переданная при запросе или порядковый указатель, если параметр не передан

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

{
    "_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"
                    }
                }
            }
        ]
    }
}

Редактирование примечаний

Метод

PATCH /api/v4/{entity_type}/notes

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

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

Описание

Метод позволяет редактировать примечания пакетно.
Также вы можете добавить ID примечания в метод для редактирования конкретного примечания (/api/v4/{entity_type}/{entity_id}/notes/{id}).
При редактировании пакетно передается массив из объектов-примечаний, при редактировании одного примечания, передается просто модель.

Ограничения

Метод доступен всем пользователям аккаунта. Успешность выполнения действия зависит от прав на сущность.

Заголовок запроса

Content-Type: application/json

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

Параметр Тип данных Описание
entity_id int ID сущности, в которую добавляется примечание. Обязателен при использовании метода создания примечания в сущности, если создание идет через метод /api/v4/{entity_type}/{entity_id}/notes, то данный параметр передавать не нужно
note_type string Тип примечания. Возможные типы примечаний
params object Свойства примечания, зависят от типа примечания. Подробней о свойствах читайте тут

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

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

Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
200 Списки были успешно изменены
401 Пользователь не авторизован
400 Переданы некорректные данные. Подробности доступны в теле ответа

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

Метод возвращает коллекцию или модель списка, которые были изменены. Параметры аналогичны тем, что возвращаются при создании примечания.

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

{
    "_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"
                    }
                }
            }
        ]
    }
}