> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hubtalk.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# create: загрузка контактов

> Строки запроса, проверки, ответ с идентификаторами, часы, день кампании, переменные агента, повторы и сбои.

# create: загрузка контактов

`create` загружает строки с номерами в кампанию V4: создаёт её первым запросом дня и дополняет следующими.

## Строки

Строка `data[]` начинается с общих полей, за ними идут поля её скрипта в порядке, согласованном с администратором. Ключ `host` принимается и игнорируется.

| Общее поле (`v2-mx`) | Правило |
| - | - |
| `phone_number` | 11–13 цифр |
| `type` | Имя скрипта ровно как в реестре. Регистр важен. |
| `gender_voice` | `male` или `female` |
| `language` | `en`, `ru` или `es` |

Каждое поле скрипта обязательно в каждой строке. Правила полей — на странице [Учётная запись и правила полей](https://docs.hubtalk.ai/ru/v4/compat-adapter/account-settings.md#правила-полей).

## Проверки строк

Проверки идут в порядке V2. Если запрос отклонён, ничего не создаётся.

**1. Неподдерживаемые параметры**

Непустой `batch_status` отвечает `{"type":"error", "data":"The parameter batch_status is not supported"}`, непустой `uniqueID` — `{"type":"error", "data":"The parameter uniqueID is not supported"}` (оба добавлены платформой).

**2. Ключи**

Незнакомый ключ отвечает `{"type":"error", "data":"#<ключ>#  does not exist in the format of the request"}` (два пробела — как в V2), пропущенный — `{"type":"error", "data":"The required field is missing #<ключ>#"}`. Первая такая ошибка останавливает запрос.

**3. Скрипт**

Строка, чьего скрипта нет в реестре вашей учётной записи или его сейчас нельзя использовать (агент в архиве, не опубликован или не задан), получает ошибку строки по полю `type`.

**4. Значения**

Ошибки отвечают `{"type":"error", "data":[{"line":"1", "fields":["amount_due"]}]}` — по записи на каждую строку с ошибкой. С `flag_ignore_errors: "skip"` такие строки отбрасываются, остальные принимаются.

**5. Реестр «Не звонить»**

Для номера из реестра «Не звонить» вашей организации учётная запись либо пропускает строку (строка получает идентификатор, но никто не звонит — поведение V2), либо отклоняет запрос с ошибкой строки по `phone_number`. С `flag_ignore_errors: "skip"` такая строка просто отбрасывается.

**6. Повторная загрузка**

Если проверка включена в учётной записи: номер, уже загруженный сегодня, или тот же номер с тем же `foreign_id` отбрасывается.

Если отброшены все строки, ответ — `{"type":"success", "data":[]}`, и кампания не создаётся.

## Ответ

Каждая принятая строка получает **идентификатор контакта адаптера** — девятизначное число от 100 000 000. Идентификаторы выдаются в порядке строк, включая строки, пропущенные по реестру «Не звонить». Форма ответа задана в учётной записи:

```json Список идентификаторов theme={null}
{"type":"success", "data":[100000001,100000002]}
```

```json Пары batch_id и foreign_id theme={null}
{"type":"success", "data":[{"batch_id":100000001,"foreign_id":"MX-77120"},{"batch_id":100000002,"foreign_id":null}]}
```

Сохраняйте идентификаторы: их принимает [`delete`](https://docs.hubtalk.ai/ru/v4/compat-adapter/delete).

## Часы

Часы читаются в часовом поясе вашей организации и сверяются с окном обзвона учётной записи. Сначала идут четыре проверки V2 — они сравнивают только часы, минуты игнорируются:

| № | Условие | Текст ответа |
| - | - | - |
| 1 | `ending_hour` вне окна (только `create`) | `End time is out of eligible range from 10 to 21` (добавлено платформой; числа — из V2, а не ваше окно) |
| 2 | Текущий час не раньше `ending_hour`, а окно ещё открыто (только `create`) | `The end time is set incorrectly, the current time is greater than the end time` |
| 3 | `start_hour` не раньше `ending_hour` (только `create`) | `The end time is set incorrectly, the end time is less than or equal to the start time` |
| 4 | `start_hour` вне окна (любая операция, которая его передаёт) | `The time is set incorrectly, restrictions from 8 to 19` |

Без `ending_hour` концом считается конец окна учётной записи; `24` означает 23:59. Затем учитываются минуты:

* **Конец срезается** до более раннего из конца окна учётной записи и конца окна обзвона организации. Срезанный запрос всё равно принимается, а в ответе появляется один ключ сверх шаблонов V2:

  ```json theme={null}
  {"type":"success", "data":[…], "notice":"End time 21:30 is out of eligible range, cut to 21:00"}
  ```

* **Старт** — переданный или час старта учётной записи — должен оказаться раньше конца после среза. Иначе ответ — текст проверки 3.

> [!NOTE]
>
> Ключ `notice` — не ошибка: запрос принят, только конец укорочен. Код, который разбирает JSON по ключам, его пропустит. Если код сравнивает тело ответа целиком, присылайте конец внутри окна.

## День кампании и кампания

**День кампании** — сегодня в часовом поясе вашей организации. Если до конца дня (самого раннего из концов окон и запрошенного конца) осталось **5 минут или меньше** либо конец уже прошёл, запрос уходит на завтра с теми же часами. Правило V2 «после 19:56 — на завтра» не используется.

Все запросы одного дня с одинаковыми **скриптом, `cname`, часом и минутой старта и числом попыток** попадают в одну кампанию. Первый создаёт и запускает её, следующие добавляют в неё свои строки. Имя кампании:

```
<cname> <ГГГГ-ММ-ДД> <ЧЧ:ММ> (<скрипт>)
```

— до 80 символов. Кампания закрывается в конце своего дня или при отмене; опустевшая очередь её не закрывает.

> [!WARNING]
>
> Завершённая или отменённая кампания остаётся закрытой. До конца дня запросы с теми же признаками получают внутреннюю ошибку `Internal error, try again later`. Чтобы начать новую кампанию, смените `cname` или час старта.

## Что получает агент

* `gender_voice` и `language` приходят агенту переменными под своими именами. `phone_number` и `type` переменными не становятся.
* Каждое поле скрипта приходит агенту под своим именем, под именем другой переменной или не приходит вовсе — как настроено в реестре.
* Пустое значение заменяется резервным значением из реестра; если его нет, действует умолчание переменной в самом агенте.
* `foreign_id` приходит агенту, только если реестр направил его в переменную. Рядом с идентификатором контакта адаптера он хранится всегда.
* В каждую строку добавляется `rl_today` — день кампании в формате `ДД.ММ.ГГГГ`. Он перекрывает одноимённое поле запроса.

Подробно, как поле запроса становится переменной, — в разделе [Поля и переменные](https://docs.hubtalk.ai/ru/v4/compat-adapter/registry-fields.md).

## Обзвон

Попытки, скорость и интервал берутся из запроса или из дефолтов учётной записи. Интервал отсчитывается от предыдущей попытки каждого контакта. Звонки идут только в часы кампании и внутри окна обзвона организации; действуют реестр «Не звонить» и [частотные правила](https://docs.hubtalk.ai/ru/v4/platform/campaigns/frequency.md) организации.

## Повторные запросы

То же тело (без учёта `user` и `pass`), присланное повторно в течение **10 минут**, получает сохранённый ответ с теми же идентификаторами, и строки не добавляются. Чтобы добавить строки в кампанию, пришлите другое тело — другие номера или значения полей.

## Сбои и время

* Если платформа не может завершить запрос после проверок, от него ничего не остаётся: созданная им кампания отменяется, строки, добавленные им в уже существующую кампанию, снимаются, а ответ — внутренняя ошибка. Повторите запрос позже.
* Все ожидания запроса до начала записи укладываются в 50 секунд. После этого большой `create` может идти дольше — поэтому тайм-аут клиента должен быть не меньше 60 секунд.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.