# Обзвоны

Список обзвона собирает контакты или компании CRM для звонков менеджера и хранит статус каждого участника: в работе, успешно, неверный номер, больше не звонить.

Битрикс24 API: `crm.calllist.list`, `crm.calllist.get`, `crm.calllist.add`, `crm.calllist.update`, `crm.calllist.items.get`, `crm.calllist.statuslist`
Скоуп: `crm`

## Операции

- [Создать список](./call-lists/create.md) — `POST /v1/call-lists`
- [Список обзвонов](./call-lists/list.md) — `GET /v1/call-lists`
- [Получить список](./call-lists/get.md) — `GET /v1/call-lists/:id`
- [Заменить состав](./call-lists/replace.md) — `PUT /v1/call-lists/:id`
- [Участники списка](./call-lists/items.md) — `GET /v1/call-lists/:id/items`
- [Статусы участников](./call-lists/statuses.md) — `GET /v1/call-lists/statuses`

## Ключевые поля

| Поле | Описание |
|------|----------|
| `id` | Идентификатор списка обзвона |
| `entityType` | Тип участников. У списка — строка: `CONTACT`, `COMPANY`, у списков, собранных в интерфейсе Битрикс24, также `LEAD` и `DEAL`. У участника в [участниках списка](./call-lists/items.md) — число, тот же код, что `entityTypeId` |
| `entityTypeId` | Тот же тип числом: `1` — лид, `2` — сделка, `3` — контакт, `4` — компания |
| `createdById` | Кто создал список. Список пользователей: [`GET /v1/users`](/docs/entities/users) |
| `webformId` | CRM-форма, привязанная к списку, или `null`. Список форм: [`GET /v1/crm-forms`](/docs/entities/crm-forms) |
| `dateCreate` | Дата создания строкой `YYYY-MM-DD HH:mm:ss` |
| `status` | Статус участника в списке, код из [`GET /v1/call-lists/statuses`](./call-lists/statuses.md) |

Поля самого списка возвращают [список обзвонов](./call-lists/list.md) и [получение списка](./call-lists/get.md), поля участников — [участники списка](./call-lists/items.md).

## Что нужно знать перед работой

1. **Через API создаются списки контактов и компаний.** Создание и замена состава принимают `entityType` только `CONTACT` или `COMPANY`. Чтение работает и со списками лидов и сделок, собранными в интерфейсе Битрикс24.
2. **Каждое создание добавляет дело «Обзвон».** Вместе со списком на портале появляется дело с темой `Обзвон #<id списка>`, ответственный — создатель списка `createdById`. Повторный `POST` с тем же составом создаёт второй список и второе дело. Дело доступно в [Делах](/docs/entities/activities) с фильтром `filter[providerId]=CALL_LIST`.
3. **Замена состава полная.** `PUT /v1/call-lists/:id` оставляет в списке только переданных участников, остальные удаляются. Привязка к CRM-форме тоже переписывается: без `webformId` в теле она сбрасывается в `null`.
4. **Статус участника — код справочника.** Новые участники получают `IN_WORK`. Название статуса для показа человеку берите из [справочника статусов](./call-lists/statuses.md) по совпадению `status` участника и `statusId` статуса.
5. **Дата без часового пояса.** `dateCreate` приходит строкой `YYYY-MM-DD HH:mm:ss` во времени портала, без зоны. Приводите её к нужной зоне по настройкам портала, а не читайте её как UTC.
6. **Страницы по 50 записей.** Список обзвонов и участники отдаются страницами фиксированного размера — 50 записей. `offset` принимает только значения, кратные 50.

## Типичный сценарий

1. Найдите контакты для обзвона: [`GET /v1/contacts`](/docs/entities/contacts) с нужным фильтром.
2. Создайте список из их идентификаторов: [`POST /v1/call-lists`](./call-lists/create.md).
3. Прочитайте участников и их статусы: [`GET /v1/call-lists/:id/items`](./call-lists/items.md).
4. Сопоставьте коды статусов с названиями: [`GET /v1/call-lists/statuses`](./call-lists/statuses.md).
5. Если состав поменялся, передайте новый полный список участников: [`PUT /v1/call-lists/:id`](./call-lists/replace.md).

## Лимиты

| Лимит | Значение |
|-------|----------|
| Записей на странице списка обзвонов | 50, фиксировано |
| Участников на странице | 50, фиксировано |
| `offset` | 0 или кратное 50 |
| Частота запросов | общий лимит API Вайбкод — см. [Лимиты и оптимизация](/docs/optimization) |

## Смотрите также

- [Справочник сущностей](/docs/entity-api)
- [Синтаксис фильтрации](/docs/filtering)
- Связанные сущности: [Контакты](/docs/entities/contacts), [Компании](/docs/entities/companies), [Дела](/docs/entities/activities), [CRM-формы](/docs/entities/crm-forms)