Беседы

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

Список бесед

Метод

GET /api/v4/talks

Описание

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

Ограничения

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

GET параметры

Параметр	Тип данных	Описание
page	int	Страница выборки
limit	int	Количество возвращаемых сущностей за один запрос (Максимум – 250)
filter	object	Фильтр
filter[talk_id]	int\|array	Фильтр по ID беседы. Можно передать как один ID, так и массив из нескольких ID
filter[contact_id]	int\|array	Фильтр по ID контакта. Можно передать как один ID, так и массив из нескольких ID
filter[entity_id]	int\|array	Фильтр по ID сущности (сделки или покупателя). Можно передать как один ID, так и массив из нескольких ID. Необходимо передавать вместе с filter[entity_type]
filter[entity_type]	string	Тип сущности для фильтра по entity_id. Возможные значения: lead, customer
filter[only_in_work]	any	Если параметр передан, возвращаются только открытые беседы

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

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

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

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

Параметр	Тип данных	Описание
talk_id	int	ID беседы
created_at	int	Дата создания беседы, передается в Unix Timestamp
updated_at	int	Дата изменения беседы, передается в Unix Timestamp
rate	int	Оценка беседы клиентом, выставляется в результате работы NPS-бота
contact_id	int	ID контакта, к которому принадлежит беседа
chat_id	string	ID чата, к которому принадлежит беседа
entity_id	int null	ID сущности, по которой ведется беседа
entity_type	string null	Тип сущности, по которой ведется беседа (lead, customer)
status	string	Статус беседы. Возможные значения: in_work – беседа в работе; closed – беседа закрыта; nps_scheduled – отправка NPS-опроса клиенту запланирована; nps_in_progress – NPS-опрос отправлен клиенту, ожидается оценка; with_error – беседа в работе, в процессе работы NPS-бота возникла ошибка
is_in_work	bool	В работе ли беседа (не закрыта)
is_read	bool	Прочитана ли беседа
origin	string	Тип источника, по которому была создана беседа (telegram, viber, и т.д.)
source_id	int null	ID источника беседы
account_id	int	ID аккаунта
_embedded	object	Данные вложенных сущностей
_embedded[contacts]	array	Данные контактов, к которым принадлежит беседа (не больше одного)
_embedded[contacts][0]	object	Модель контакта, к которому принадлежит беседа
_embedded[contacts][0][id]	int	ID контакта, к которому принадлежит беседа
_embedded[leads]	array	Данные сделок, по которым ведется беседа (не больше одной)
_embedded[leads][0]	object	Модель сделки, по которой ведется беседа
_embedded[leads][0][id]	int	ID сделки, по которой ведется беседа
_embedded[customers]	array	Данные покупателей, по которым ведется беседа (не больше одного)
_embedded[customers][0]	object	Модель покупателя, по которому ведется беседа
_embedded[customers][0][id]	int	ID покупателя, по которому ведется беседа

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

{
    "_page": 1,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/talks?page=1&limit=50"
        },
        "next": {
            "href": "https://example.amocrm.ru/api/v4/talks?page=2&limit=50"
        }
    },
    "_embedded": {
        "talks": [
            {
                "talk_id": 117,
                "created_at": 1631018291,
                "updated_at": 1631035929,
                "rate": 0,
                "contact_id": 3372695,
                "chat_id": "88278e98-2b8d-4ae2-a5f0-bfab511cd621",
                "entity_id": 667999637,
                "entity_type": "lead",
                "status": "in_work",
                "is_in_work": true,
                "is_read": true,
                "origin": "telegram",
                "source_id": 13302025,
                "account_id": 17029541,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/talks/117"
                    }
                },
                "_embedded": {
                    "contacts": [
                        {
                            "id": 3372695,
                            "_links": {
                                "self": {
                                    "href": "https://example.amocrm.ru/api/v4/contacts/3372695"
                                }
                            }
                        }
                    ],
                    "leads": [
                        {
                            "id": 667999637,
                            "_links": {
                                "self": {
                                    "href": "https://example.amocrm.ru/api/v4/leads/667999637"
                                }
                            }
                        }
                    ],
                    "customers": []
                }
            }
        ]
    }
}

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

Метод

GET /api/v4/talks/{id}

Описание

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

Ограничения

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

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

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

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

Параметр	Тип данных	Описание
talk_id	int	ID беседы
created_at	int	Дата создания беседы, передается в Unix Timestamp
updated_at	int	Дата изменения беседы, передается в Unix Timestamp
rate	int	Оценка беседы клиентом, выставляется в результате работы NPS-бота
contact_id	int	ID контакта, к которому принадлежит беседа
chat_id	string	ID чата, к которому принадлежит беседа
entity_id	int null	ID сущности, по которой ведется беседа
entity_type	string null	Тип сущности, по которой ведется беседа (lead, customer)
status	string	Статус беседы. Возможные значения: in_work – беседа в работе; closed – беседа закрыта; nps_scheduled – отправка NPS-опроса клиенту запланирована; nps_in_progress – NPS-опрос отправлен клиенту, ожидается оценка; with_error – беседа в работе, в процессе работы NPS-бота возникла ошибка
is_in_work	bool	В работе ли беседа (не закрыта)
is_read	bool	Прочитана ли беседа
origin	string	Тип источника, по которому была создана беседа (telegram, viber, и т.д.)
source_id	int null	ID источника беседы
account_id	int	ID аккаунта
_embedded	object	Данные вложенных сущностей
_embedded[contacts]	array	Данные контактов, к которым принадлежит беседа (не больше одного)
_embedded[contacts][0]	object	Модель контакта, к которому принадлежит беседа
_embedded[contacts][0][id]	int	ID контакта, к которому принадлежит беседа
_embedded[leads]	array	Данные сделок, по которым ведется беседа (не больше одной)
_embedded[leads][0]	object	Модель сделки, по которой ведется беседа
_embedded[leads][0][id]	int	ID сделки, по которой ведется беседа
_embedded[customers]	array	Данные покупателей, по которым ведется беседа (не больше одного)
_embedded[customers][0]	object	Модель покупателя, по которому ведется беседа
_embedded[customers][0][id]	int	ID покупателя, по которому ведется беседа

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

{
    "talk_id": 117,
    "created_at": 1631018291,
    "updated_at": 1631035929,
    "rate": 0,
    "contact_id": 3372695,
    "chat_id": "88278e98-2b8d-4ae2-a5f0-bfab511cd621",
    "entity_id": 667999637,
    "entity_type": "lead",
    "status": "in_work",
    "is_in_work": true,
    "is_read": true,
    "origin": "telegram",
    "source_id": 13302025,
    "account_id": 17029541,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/talks/117"
        }
    },
    "_embedded": {
        "contacts": [
            {
                "id": 3372695,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/contacts/3372695"
                    }
                }
            }
        ],
        "leads": [
            {
                "id": 667999637,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/667999637"
                    }
                }
            }
        ],
        "customers": []
    }
}

Закрытие беседы по ID

Метод

POST /api/v4/talks/{id}/close

Описание

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

Ограничения

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

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

Content-Type: application/json

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

Для закрытия беседы без запуска NPS-бота необходимо передать свойство force_close со значением true.

Параметр	Тип данных	Описание
force_close	bool	Принудительно закрыть беседу, необязательный параметр, по-умолчанию – false

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

В данном примере мы принудительно закроем беседу.

{
    "force_close": true
}

HTTP коды ответа

Код ответа	Условие
202	Запрос выполнен успешно
401	Пользователь не авторизован
402	Аккаунт не оплачен
403	Недостаточно прав
404	Беседа не найдена
422	Беседа уже закрыта или находится в процессе закрытия

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

Метод не возвращает тело

Оглавление

Список бесед

Метод

Описание

Ограничения

GET параметры

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

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

HTTP коды ответа

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

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

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

Метод

Описание

Ограничения

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

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

HTTP коды ответа

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

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

Закрытие беседы по ID

Метод

Описание

Ограничения

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

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

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

HTTP коды ответа

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