Каналы

Подключение канала

Подключение и первичная настройка канала (QR-код, OAuth с Meta, SIP-провижининг) выполняются через мастер в личном кабинете (my.aisar.app/settings/channels/add), а не напрямую через этот API — мастер использует отдельные, специфичные для каждого провайдера эндпоинты подключения. Исключение — Telegram Business (telegram_business): подключение сводится к одному вызову с токеном бота и описано ниже, в разделе «Telegram Business».

Жизненный цикл

Жизненный цикл канала отражают два поля:

• setup_state (draft → pairing → ready | failed) — этап первичной настройки.
• status (connected | disconnected | connecting | reconnecting | paused | expired | banned) — текущее состояние уже настроенного канала. banned — не тупик: если провайдер снял блокировку аккаунта, канал можно переподключить обычным reconnect/пейрингом; если блокировка ещё действует, провайдер отклонит подключение и канал вернётся в banned.

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

И список (GET /channels), и карточка (GET /channels/{channel}) отдают пару булевых полей, по которым решают, что каналу можно поручить прямо сейчас, не разбирая типы и статусы вручную. calling_enabled — канал способен принимать и совершать звонки: у SIP-телефонии всегда true; у личного WhatsApp (подключённого по QR) — только когда на канале включён тумблер звонков; у WhatsApp Business — только когда для номера настроен номер звонков (config.calling_did), поэтому WABA без включённых звонков за телефонию не считается. messaging_enabled — вторая половина той же пары: true у подключённого (status = connected) мессенджер-канала, виджета или соцсети и false у SIP-транка (это только голос) и у любого канала не в статусе connected. Оба поля присутствуют всегда, у каналов любого типа.

Третье поле той же пары — voice_calls_supported — про способность канала, а не про его текущее состояние: true, только если это личный (QR) WhatsApp-канал, подключённый к рантайму AISAR, который несёт голосовые звонки. У остальных типов канала (WhatsApp Business, SIP-телефония, Telegram и т.д.) поле всегда false и ничего не добавляет — их способность звонить уже полностью описана calling_enabled. Не путайте пару: voice_calls_supported отвечает на вопрос «этот канал вообще способен нести звонки», calling_enabled — «звонки сейчас включены»; тумблер приёма звонков в личном кабинете показывается только когда voice_calls_supported: true. voice_calls_supported: false на канале обычного WhatsApp не означает, что AISAR не умеет звонки с обычного WhatsApp вообще — платформа это умеет, часть каналов уже работает на рантайме с такой поддержкой. Значит только то, что ЭТОТ канал подключён к рантайму без поддержки звонков; включить их можно, переподключив канал через поддержку AISAR — самостоятельной миграции в личном кабинете для этого нет.

Ещё одно булево поле и списка, и карточки — can_start_conversation: может ли канал написать клиенту первым, то есть открыть переписку с контактом, с которым у этого канала ещё не было треда. Оно true у всех типов, кроме Telegram Business (telegram_business): такой канал только отвечает тем, кто написал сам, поэтому не предлагайте его в выборе канала для нового диалога и для рассылки (подробности — в разделе «Telegram Business» ниже). Кроме того, список GET /channels отдаёт status_message и last_error_code — те же поля, что и карточка: короткий машиночитаемый код состояния канала и код его последней ошибки. По ним видно, почему канал не может отправлять, без отдельного запроса карточки.

Что канал делает со входящим WhatsApp-звонком

Поведение задаёт config.call_handling.mode, и три его значения меняются обычным PATCH /v1/channels/{channel}: ignore — звонок не трогаем (в кабинете он останется пропущенным), reject — сразу отклоняем, reject_with_message — отклоняем и отправляем собеседнику текст из config.call_handling.auto_reply_text. Конфиг сливается по ключам, присылать объект целиком не нужно.

Два поведения стоит учесть заранее. Отклоняет любое значение, кроме ignore, — опечатка в mode тихо превратится в отклонение всех звонков, а текст автоответа уйдёт только при точном reject_with_message. И четвёртое состояние, приём звонка (answer), через PATCH не выставляется: запрос вернёт 422 с указанием нужного эндпоинта.

Приём входящих включается отдельной ручкой: POST /v1/channels/{channel}/whatsmeow-calling/enable с телом {"ban_risk_ack": true} — подтверждение риска блокировки номера обязательно, без него 422. Ручка доступна только каналу с voice_calls_supported: true (иначе 404) и токену с правом управления телефонией (иначе 403); если свободной ёмкости для звонков сейчас нет, ответ 422 с error: calls_instance_unavailable, и канал остаётся в прежнем состоянии, а не наполовину включённым. Выключение — POST /v1/channels/{channel}/whatsmeow-calling/disable: оно возвращает mode в ignore и снова открывает выбор из трёх значений выше. Пока приём включён, PATCH не может понизить mode: значение answer удерживается, чтобы обычное сохранение формы настроек не выключило звонки мимоходом.

Профиль WhatsApp-номера

Аватар и тексты профиля читаются и меняются через /v1/channels/{channel}/whatsapp/profile. Набор доступных полей зависит не от типа канала, а от того, что умеет конкретное подключение, поэтому ответ всегда содержит capabilities: у WhatsApp Business доступны about, description, адрес, почта, сайты и категория, у WhatsApp, подключённого по QR, — фото и about, а описание — только если номер работает в приложении WhatsApp Business. Опирайтесь на capabilities и limits из ответа: попытка прислать неподдержанное поле отклоняет запрос целиком, а не применяет его частично.

Заблокированные пользователи WhatsApp (blocked-users)

GET /channels/{channel}/whatsapp/blocked-users (с 2026-09-04) читает список номеров, заблокированных ПРОВАЙДЕРОМ на этом канале — это не список контактов, заблокированных внутри AISAR (тем управляют POST /contacts/{contact}/block и /unblock, см. группу «Контакты»). Формат элементов numbers[] зависит от типа подключения: у WhatsApp Business (Cloud API) это номер в формате провайдера (например +12025550179), у WhatsApp по QR (whatsmeow) — WhatsApp JID (например 12125550175@s.whatsapp.net). Пагинация курсорная: передайте after со значением next_cursor предыдущего ответа за следующей страницей; next_cursor: null означает конец списка. limit — от 1 до 1000, по умолчанию 100.

Доступен только для WhatsApp-каналов (whatsapp/whatsapp_business) — на канале другого типа ответ 422 {error_code: "channel_not_whatsapp"}; отключённый канал — 409 {error_code: "channel_offline"}. Авторизация — право channel:view (а не contact:update, как у block/unblock): это чтение состояния канала, а не действие над контактом; чужой канал — 403.

Временная блокировка исходящих у SIP-транка (`sip_outbound_gated`)

У канала sip_telephony, подключённого по IP-адресу оборудования оператора (см. руководство по подключению каналов, раздел «SIP-телефония (BYO-транк)»), может быть временно закрыт исходящий трафик, если тот же адрес уже используется другой компанией AISAR у того же оператора. Это отражено булевым полем sip_outbound_gated — оно присутствует у КАЖДОГО канала (не только sip_telephony) и равно false, если ограничение не действует. Пока sip_outbound_gated: true, канал по-прежнему принимает входящие звонки, но POST /calls/originate и POST /softphone/external-call для него ведут себя так, будто у компании нет ни одного подключённого SIP-канала. Ограничение снимается автоматически, без вызова какого-либо эндпоинта, как только на номер канала приходит первый подтверждённый входящий звонок.

Архивные каналы

Канал, удалённый с сохранением истории (DELETE /channels/{channel} без keep_history=false — так по умолчанию, см. ниже), не пропадает: он soft-deleted, помечен archived_at, а его переписка остаётся доступной на чтение внутри AISAR. Обычный GET /channels такие каналы не возвращает, и параметра, который включил бы их обратно в общий список, не существует — include_archived в валидации GET /channels не описан, и любое его значение молча игнорируется. Единственный способ увидеть архивный канал — отдельный список GET /channels/archived.

GET /channels/archived отдаёт тот же ChannelListResource, что и обычный список, плюс заполненные archived_at и messages_count (число сообщений канала, включая впоследствии удалённые по отдельности). Момент архивации отмечен вебхук-событием channel.archived (см. справочник событий вебхуков) — этот список и есть то место, где канал, о котором оно уведомило, можно найти позже. GET /channels/{channel} по id архивного канала отдаёт 404 — это штатное поведение (route-model binding не резолвит soft-deleted модель), а не признак того, что канал потерян.

Окончательное, необратимое удаление архивного канала вместе с историей — DELETE /channels/archived/{channelId} (channelId — целое число: soft-deleted канал не резолвится через route-model binding, поэтому путь принимает id напрямую, а не {channel}). Ответ 200 означает, что удаление поставлено в очередь фоновой задачей, а не что оно уже завершилось.

Тела запросов жизненного цикла

Пауза/возобновление/отключение вызываются без тела запроса, а переподключение (POST /channels/{channel}/reconnect) для OAuth/бот-каналов принимает provider-specific тело (Instagram/Threads/Facebook Messenger — { code }, WhatsApp Business — { authorization_code, waba_id, phone_number_id }, Telegram Bot — { bot_token }, Telegram Business — { bot_token }, где токен необязателен), иначе 422; для WhatsApp/Telegram по QR и Live Chat тело пустое. Полный контракт по типам приведён в партнёрской документации (гайд о подключении каналов, секция «Прямой API»).

С 2026-09-26 при переподключении Telegram Bot ({ bot_token }) токен бота, который уже привязан к другому живому каналу AISAR, отклоняется 409 с code/error_code bot_already_connected (компания-владелец не раскрывается). В PATCH /channels/{channel} поле crm_settings.funnel_id принимает только воронку своей компании (иначе 422), а crm_settings: null сохраняется как { "funnel_id": null } — «без переопределения воронки».

Telegram Business (`telegram_business`)

Канал Telegram Business ведёт личный Telegram-аккаунт через собственного бота компании с включённым Business Mode: это официальный Bot API, сессия аккаунта в AISAR не хранится. Подключение идёт в два шага. Сначала POST /v1/channels/telegram-business/complete-signup с токеном бота: AISAR проверяет токен и Business Mode, создаёт канал и настраивает вебхук бота. Второй шаг делает сам владелец аккаунта в приложении Telegram (Настройки → Telegram для бизнеса → Чат-боты), через API его выполнить нельзя. До этого канал находится в setup_state: pairing, status: connecting, status_message: awaiting_business_connection и уже занимает место в лимите каналов тарифа. После подключения он переходит в ready/connected. Вебхук-событие channel.connected на это подключение не отправляется, поэтому следите за состоянием через GET /channels/{channel}.

Тело complete-signup: bot_token (обязателен, формат 123456789:AAF…, до 200 символов), name (до 255 символов), description, timezone (по умолчанию UTC). Если name не задан, канал называется Telegram Business @имя_бота, а при первом подключении аккаунта получает имя владельца, если вы не переименовали его раньше. Поля config, allowed_team_ids, allow_broadcasts, allow_automations, allow_inbound_handling и child_id запрещены: с любым из них ответ 422. Нужно право channel.create. Действуют лимит тарифа на число каналов и ограничение 10 запросов в минуту на пользователя. Ответ 201 — объект канала. Токен бота в ответ не попадает и хранится в зашифрованном виде. Эфемерный токен партнёрской connect-сессии этот эндпоинт не принимает (403): в iframe-визарде подключения каналов Telegram Business пока нет.

Отказы с кодом приходят плоским телом без обёртки data: {"message": "…", "code": "…", "error_code": "…"}, где code и error_code совпадают.

Значения status_message у канала Telegram Business:

• awaiting_business_connection — канал создан, владелец ещё не подключил бота в Telegram (pairing, connecting).
• null при connected — всё работает.
• read_only_no_reply_right — канал connected, но владелец не выдал боту право отвечать на сообщения. Входящие приходят, отправка из AISAR отклоняется с кодом no_reply_right, пока право не включат в Telegram.
• business_connection_disabled — владелец отключил бота в настройках Telegram (disconnected). История в AISAR сохраняется, канал оживает, когда бота включат снова.
• owner_connected_as_personal_channel:{id} — этот же аккаунт уже ведёт личный Telegram-канал компании с id {id}. Подключение остановлено (setup_state: failed, status: disconnected), иначе каждое сообщение приходило бы дважды. Блокирует только личный канал, который принимает сообщения (connected, connecting, reconnecting, paused); отключённый, expired или banned не мешает. Правило работает и в обратную сторону: если личный канал с тем же аккаунтом подключится позже, уже работающий канал Telegram Business перейдёт в это же состояние. Чтобы снять блок, отключите личный канал, затем в Telegram уберите бота из чат-ботов и добавьте снова либо переподключите канал Telegram Business.
• bot_token_revoked — Telegram отклонил токен бота, обычно после его перевыпуска в @BotFather (expired). Переподключите канал новым токеном того же бота.

После подключения аккаунта карточка GET /channels/{channel} отдаёт config.telegram_business — несекретную проекцию подключения: owner_user_id, owner_username, owner_name (владелец аккаунта), bot_username, rights с булевыми can_reply, can_read_messages, can_delete_sent_messages, затем dangerous_rights и personal_channel_identity_unknown. dangerous_rights — список прав, которые владелец выдал боту, хотя AISAR ими не пользуется: переводы звёзд, подарки, правка имени, описания, фото и username профиля, истории, удаление любых сообщений. Пустой список означает, что лишних прав нет. personal_channel_identity_unknown: true значит, что в компании есть личный Telegram-канал, аккаунт которого пока не удалось сопоставить, и возможное задвоение сообщений не исключено. В списке GET /channels у канала этого типа есть только урезанный config.telegram_business с rights и personal_channel_identity_unknown, прочий config список не отдаёт. Проекцию пишет только сервер: config.telegram_business в PATCH /channels/{channel} молча отбрасывается, сохранённое значение не меняется. Токен бота и идентификатор подключения наружу не отдаются нигде.

Написать клиенту первым такой канал не может. Telegram разрешает боту отвечать от имени аккаунта только в личных чатах, где клиент писал за последние 24 часа, а шаблонов, которые открывали бы окно заново, у Telegram нет. Поэтому у канала can_start_conversation: false, и открыть через него переписку с новым контактом нельзя: такие запросы отклоняются с 422 channel_cannot_start_conversation (см. группы «Сообщения» и «Диалоги»). В рассылках канал не участвует: явный выбор его в channels.channelIds или content.channels[].channelId даёт 422, в режиме last_interacted его треды пропускаются, а allow_broadcasts: true в PATCH /channels/{channel} отклоняется с 422. Окно 24 часа сервер при ответе не проверяет, limits.reply_window_hours: 24 служит подсказкой для интерфейса. Если клиент молчит дольше, Telegram откажет в доставке, и сообщение получит failed с кодом outside_window. Истории до подключения Telegram боту не отдаёт. Поддерживаются только личные чаты, без групп и каналов Telegram. Кнопки в сообщениях и реакции не поддерживаются. Общий POST /v1/channels такой канал не создаёт (422 по полю channel_type), и перевести существующий канал в этот тип через PATCH тоже нельзя (422 по channel_type_id).

Переподключение — POST /channels/{channel}/reconnect с телом { "bot_token": "…" }, где токен необязателен. Без него AISAR берёт сохранённый токен и заново настраивает вебхук. Новый токен принимается только от того же бота, это сценарий «перевыпустил токен в @BotFather». Каждое переподключение меняет адрес и секрет вебхука. Если Telegram их не принял, прежние восстанавливаются, и канал работает как до запроса. Когда аккаунт уже подключён, AISAR заново читает из Telegram состояние подключения и права. Отказы: 422 different_bot (токен другого бота; его подключают новым каналом), 422 invalid_token, 422 business_mode_disabled, 409 bot_already_connected, 502 webhook_setup_failed и 502 telegram_unavailable с тем же плоским телом, что у подключения, а также 403 connect_session_not_supported: эфемерным токеном партнёрской connect-сессии такой канал не переподключается.

Сбои отправки через этот канал несут свои коды. Код виден в status.error_details события message.status.updated (в скобках, формат «текст (код)») и в журнале канала как запись message.send.failed.{код}. Коды из списка ниже, кроме telegram_error, терминальны: сообщение сразу получает failed, без повторных попыток. Квитанций доставки и прочтения Bot API не даёт, поэтому успешно отправленное сообщение сразу получает delivered, а read не приходит.

• outside_window — клиент не писал больше 24 часов, Telegram не доставит ответ, пока клиент не напишет снова. Тот же код, что у Facebook Messenger.
• no_reply_right — у бота нет права отвечать от имени аккаунта.
• business_not_connected — владелец ещё не подключил бота к аккаунту.
• business_connection_inactive — подключение отключено или удалено в Telegram, канал переходит в disconnected.
• bot_token_revoked — Telegram отклонил токен бота, канал переходит в expired.
• owner_connected_as_personal_channel — аккаунт уже подключён как личный Telegram-канал компании, отправка через бота остановлена.
• telegram_error — прочие ошибки Telegram. Отправка повторяется по обычной схеме, затем сообщение получает failed. Если Telegram просит подождать (HTTP 429), повтор идёт через названный им интервал, но не позже чем через 5 минут, и тоже расходует попытку.

provider_key и тип канала

Поле provider_key — публичный, нейтральный идентификатор провайдера; внутренние имена runtime-библиотек наружу никогда не отдаются. Полный перечень значений и правила маппинга QR-каналов — в справочнике «Типы: мессенджинг», тип Channel. Чтобы различать тип канала в коде, опирайтесь на channel_type.key, а не на отображаемое имя.

Пагинация логов канала

GET /channels/{channel}/logs пагинирован: page/per_page (принимается и алиас perPage), максимум 500, по умолчанию 200. До 2026-08-25 эндпоинт параметры пагинации молча игнорировал и всегда отдавал новейшие 200 строк — заглянуть дальше в историю было нельзя. Сортировка — created_at desc, затем id desc: рантайм пишет пачки логов в пределах одной секунды, и без вторичной сортировки по id одна и та же строка могла повториться на одной странице и пропасть с другой. Ответ обёрнут как у прочих постраничных списков: элементы — в data, служебная информация — в meta (current_page, last_page, per_page, total); формат самого элемента лога не менялся.

Коды сбоя отправки в журнале канала

Помимо кодов подключения (connection.ready, connection.lost и т. п.), GET /channels/{channel}/logs пишет записи о судьбе исходящих сообщений и рассылок. message.send.failed.{error_code} — уровень error: одна запись на исчерпавшую все повторные попытки отправку (не на каждую попытку — иначе рассылка затопила бы журнал канала), {error_code} — код ошибки последней попытки либо unknown; context несёт message_id, attempts, error_code и усечённый response (только reason/status/response из ответа рантайма/провайдера — внутренний адрес рантайма из response исключён по соображениям ИБ). message.status.failed_suppressed — уровень warning: провайдер прислал квитанцию о сбое ПОСЛЕ того, как сообщение уже получило delivered/read/played — статус сообщения не понижается (см. событие message.status.updated), но сам факт провайдерской ошибки фиксируется здесь; context несёт message_id и reason (человекочитаемая причина). message.status.orphan_failed (с 2026-09-09) — уровень warning: провайдер прислал failed-статус на внешний id сообщения, которого нет в AISAR (не сохранилось при отправке либо сохранено под другим id) — только failed логируется так, чтобы не затоплять журнал квитанциями sent/delivered/read по личным WhatsApp-номерам, где такие «ничьи» статусы — норма для сообщений, отправленных прямо с телефона; context несёт external_message_id, recipient и сырой errors от провайдера. broadcast.preflight_blocked (с 2026-09-09) — уровень error: запись о том, что прогон рассылки не стартовал, потому что Meta считает WABA-канал неспособным отправлять (health_status.can_send_message = BLOCKED); context несёт broadcast_id, error_code и possible_solution от Meta (когда есть).

sip_status в ответе eligibility

sip_status внутри eligibility.calling (в ответе GET .../whatsapp-calling, а также POST .../whatsapp-calling/enable|disable) — производное поле AISAR, не сырой статус Meta: ENABLED, когда на канале включены звонки (сохранён config.calling_did), NOT_SET — звонки не включены, UNKNOWN — не удалось получить ответ от Graph API (детали — в unknown_reason/detail на верхнем уровне ответа). Для решения «доступны ли звонки прямо сейчас» надёжнее полагаться на active (true только когда can_receive_call_sip === "AVAILABLE") и сам can_receive_call_sip — они всегда отражают текущее состояние Meta, тогда как sip_status — локальное зеркало последнего успешного enable/disable на стороне AISAR и может не увидеть изменение, сделанное напрямую в WhatsApp Manager.

Семейные (Kids) компании и общие мутации каналов

С 30.09.2026 практически ЛЮБОЕ изменение канала — а не только удаление — недоступно семейной (Kids) компании: оба варианта 403 {"message": "...", "error": "company_type_forbidden"} возвращают POST/PUT/PATCH /channels/{channel}, disconnect, reconnect, pause, resume, все runtime-pairing/* (включая passkey-шаги), профиль/username/conversational-components WhatsApp, templates/sync, POST/PUT .../access, все маршруты */complete-signup (Meta, Instagram Business, Threads, Messenger, Telegram Bot, SIP-телефония, Live Chat), meta/discover-from-code, messenger/pages, connect-sessions и setup-failures. Для канала семейной компании принадлежность ребёнку — не родительский контроль, а фактически работа от имени несовершеннолетнего в чужом мессенджере, поэтому эта поверхность закрыта для семьи целиком. Чтение (GET) везде остаётся общим — на нём держится подключение по QR и просмотр диалога. Оставлены доступными семье только: POST /channels (в узком виде — см. ниже), POST /channels/{channel}/connect/start, POST /channels/{channel}/auth-code и отвязка канала от ребёнка в кабинете Kids (POST /v1/kids/children/{child}/channels/{channel}/unlink, вне этой группы). DELETE /channels/{channel} и DELETE /channels/archived/{channelId} по-прежнему отдельно недоступны семейной компании тем же кодом — единственный путь снять канал для Kids остаётся отвязкой в кабинете, а не эти общие маршруты.

POST /channels для семейной компании принимает только channel_type — whatsapp или telegram (иной тип — 422), и только поля channel_type, name, account_name, child_id, start_pairing, pairing_mode, pairing_phone_number — присутствие любого другого поля (например status, config, allow_inbound_handling) отвечает 422; child_id обязателен и должен быть неудалённым ребёнком текущей компании (см. ниже). POST /channels/{channel}/connect/start для семейной компании дополнительно проверяет: попытка (пере)подключить уже подключённый канал (status = connected) отвечает 409 {"error_code": "channel_already_connected"} вместо обычного повторного пейринга — сначала отвяжите канал в кабинете Kids; поле force семье недоступно (422, «Forced re-pairing is not available for your account type.»); mode принимает только qr, code или phone (иные значения, доступные business-каналам, — 422).

Отдельно от вышеперечисленного, POST /channels с child_id (для любой компании, где поле применимо) принимает только существующего, не удалённого ребёнка текущей компании — ссылка на чужого, несуществующего или уже удалённого ребёнка отвечает 422.

Права доступа к каналу (`.../access`)

rules в теле POST/PUT /channels/{channel}/access — не более 500 элементов, иначе 422. У каждого элемента model_id проверяется по соседнему model_type: для user это должен быть пользователь с ролью в текущей компании, для team — неудалённая команда текущей компании; иначе 422. Исключение — пара model_type+model_id, уже записанная на ЭТОМ канале: она принимается повторно, даже если этот пользователь с тех пор покинул компанию или лишился роли, — это нужно, потому что кабинет обычно отправляет весь список правил канала целиком, а не только изменённую строку. Канал другой компании отвечает 404. Удаление команды (DELETE /teams/{team}) удаляет и её правила доступа на всех каналах, где они были записаны.

Правило rule каждого элемента — allow или block, но для model_type: "team" значение block не поддерживается ни при каких обстоятельствах — оно всегда отвечает 422 на rules.N.rule («A team can only be allowed on a channel. To keep someone out, block that user personally.»). Команда может только открывать канал своим участникам; чтобы закрыть канал конкретному человеку, блокируйте его лично — model_type: "user", rule: "block".

Когда для компании включены командные ограничения доступа к каналам (платформенная настройка), менять .../access — как и состав/список каналов команды (см. группу «Команды и пользователи») — может только администратор компании или сотрудник платформы: у любого другого пользователя (в т.ч. с правом channel:update) запрос отвечает 403 {"message": "...", "code": "channel_access_admin_only"}, и правила канала не меняются. Пока эта настройка выключена (текущее поведение по умолчанию), действует только обычная проверка права channel:update — как описано в примерах ниже. Узнать, может ли ТЕКУЩИЙ пользователь сейчас менять доступ, можно без пробной записи — по полю can_edit_channel_access ответа GET /v1/me (см. группу «Команды и пользователи»).

Выбор команд в мастере подключения (allowed_team_ids)

Мастера подключения — POST /channels/meta/complete-signup, .../instagram-business/complete-signup, .../threads/complete-signup, .../messenger/complete-signup, .../telegram-bot/complete-signup, .../sip-telephony/complete-signup и POST /channels/{channel}/sip/update — принимают необязательный allowed_team_ids: массив id команд ТЕКУЩЕЙ компании, не более 100. С 30.09.2026 каждый переданный id превращается в командное allow-правило доступа канала — то же самое, что записал бы POST .../access с model_type: "team" — и видно в ответе GET /channels/{channel}/access сразу после подключения. Прежде значение просто сохранялось в channel.config.allowed_team_ids и ни на что не влияло — доступ к каналу оставался открыт всем. Чужой, удалённый или несуществующий id команды отвечает 422; для семейной (Kids) компании поле недоступно вовсе — этот тип компании не пользуется командами. Когда включены командные ограничения доступа (см. выше), выбрать хотя бы одну команду может только администратор компании или сотрудник платформы — иначе 403 channel_access_admin_only, и в этом случае канал вообще не создаётся/не обновляется. Правки — только добавление: повторный мастер (sip/update) никогда не снимает уже записанное командное правило, даже если прислать пустой список или вовсе не прислать поле, — снять правило можно только через .../access или форму команды.

Ключ config.allowed_team_ids больше нигде не записывается: ни этими мастерами (он заменён на командные правила доступа выше), ни общим PATCH/POST /channels/{channel} — если прислать config.allowed_team_ids в общем обновлении канала, значение молча отбрасывается из тела запроса (остальной config сохраняется как обычно), а не сохраняется как есть. В ответах SIP и Facebook Messenger (единственных двух типов, чей config раньше нёс этот ключ) новые и обновлённые каналы больше не несут config.allowed_team_ids.

Подключение instagram (личный аккаунт) по логину и паролю

Только для каналов типа instagram (личный аккаунт), если этот тип доступен вашей компании; иначе подключение отвечает 403. POST /channels/{channel}/connect/start принимает тело { "username": "...", "password": "...", "restart"?: true }: username — имя пользователя, email или телефон аккаунта (обязателен, до 255 символов), password — пароль (обязателен, до 255 символов, нигде не сохраняется и не попадает в логи), restart — необязательный флаг «начать вход заново». Необязательный mode, если передан, может быть только credentials (иное — 422). Успех — 200: data.message, data.channel_id, data.connection (status: "starting", mode: "credentials", объект login, см. ниже) и data.runtime_push ({ "sent": true, "reason": null, "status": null }). Дальше опрашивайте GET /channels/{channel}/connection.

• 403 — этот тип канала недоступен вашей компании; 404 — канал не найден или принадлежит другой компании.
• 409 с data.error_code: "pairing_in_progress" — вход по этому каналу уже идёт (шаг ввода кода или подтверждения); в ответе также data.channel_id и data.connection. Чтобы начать заново, передайте "restart": true.
• 429 с data.error_code: "login_rate_limited", data.retry_after (секунды) и заголовком Retry-After — слишком много попыток входа. Какой именно лимит сработал, ответ не раскрывает; тело всегда состоит из message, error_code, retry_after. После нескольких неверных паролей подряд вход для этого логина ставится на паузу (срок виден в login.paused_until).
• 503 с data.error_code: "runtime_unavailable" — сейчас нет доступного рантайма Instagram; 502 с data.runtime_push: { "sent": false, "reason": ... } — рантайм не принял команду. В обоих случаях состояние канала не меняется.
• 422 — не заполнен или слишком длинный username/password, неверный mode или restart не boolean.

Если на шаге входа Instagram просит код, передайте его через POST /channels/{channel}/auth-code с телом { "code": "123456" }: только цифры, 4-12 символов, пробелы и дефисы допускаются и отбрасываются (иное — 422); поля phoneCodeHash и password для instagram игнорируются. Успех — 200 с data.message: "Auth code submitted.", data.channel_id, data.runtime_push. Если код сейчас не ожидается (login.step не равен waiting_code) — 409 с data.error_code: "code_not_expected". Не более 5 кодов за 10 минут на канал: дальше 429 login_rate_limited с retry_after. Если рантайм не принял код — 502.

Снимок подключения (GET /channels/{channel}/connection и GET /channels/{channel}/runtime-pairing) для instagram дополнительно содержит data.connection.login с полями ровно: step, code_kind, masked_destination, attempts_left, expires_at, kind, paused_until, failure. step: logging_in, waiting_code, waiting_approval, bad_password, unsupported_challenge, account_mismatch, ig_wait или null. code_kind — куда ушёл код: sms, email, totp или sms_2fa; masked_destination — маска адресата кода; attempts_left — сколько попыток ввода кода осталось; expires_at — до какого момента действует шаг (ISO 8601); kind — вид проверки Instagram (например change_password); paused_until — до какого момента вход на паузе, иначе null; failure — причина завершившегося без шага входа: code_timeout, code_invalid, approval_timeout или null. Значения connection.pairing_state (и совпадающего с ним connection.status) для шагов: authorizing, code_required, approval_required, bad_password, action_in_app_required, account_mismatch, ig_wait. Для каналов других типов объекта login нет.

Для всех каналов: ответы connect/start, auth-code, runtime-pairing и создания канала со стартом сопряжения больше не содержат сырой ответ рантайма. В runtime_push остаются только три поля: sent (boolean), reason (строка или null) и status (HTTP-код ответа рантайма или null).

Email-канал: подключение и настройки ящика

Канал типа email подключается двумя вызовами. POST /channels/email/test-connection проверяет ящик и ничего не сохраняет, POST /channels/email/complete-signup повторяет проверку и создаёт канал (201, обычный объект канала с provider_key: "imap_smtp"). Оба вызова требуют права channel.create, недоступны семейной (Kids) компании (403 company_type_forbidden) и ограничены по частоте: 10 запросов в минуту на пользователя и 30 в час на компанию (429); неудачные проверки одного ящика дополнительно ограничены по паре «сервер + логин». complete-signup проверяет ещё и лимит каналов тарифа, как другие мастера подключения. Тип канала доступен всем компаниям с 2026-10-09.

Тело обоих вызовов: provider (сейчас только imap_smtp), email (адрес ящика, до 320 символов), username (логин, обычно равен адресу), password (пароль приложения или ящика, до 1024 символов; нигде не возвращается и не логируется), imap_host и smtp_host (публичные имена серверов, IP-адреса внутренней сети и служебные адреса дают 422), imap_port (993 или 143), smtp_port (465 или 587). Необязательные imap_security и smtp_security (ssl или starttls) должны совпадать с портом: 993 и 465 это ssl, 143 и 587 это starttls, иное сочетание даёт 422. Шифрование обязательно, соединение без TLS и самоподписанные сертификаты не поддерживаются. Поле child_id запрещено (422): email-канал никогда не бывает каналом ребёнка.

test-connection отвечает 200 с отчётом data = { imap: { ok, code }, smtp: { ok, code }, sent_folder }: для каждого протокола ok и либо code: null, либо нормализованный код email_*. Сырые ответы почтового сервера и текст библиотек в ответ не попадают, поэтому вызов нельзя использовать как сканер портов. Тестовое письмо не отправляется. Коды: email_auth_failed (сервер не принял логин или пароль, чаще всего это не пароль приложения или выключен IMAP), email_tls_failed (нет защищённого соединения или сертификат выдан на другое имя), email_host_blocked (адрес сервера недопустим), email_dns_failed (имя сервера не найдено), email_host_unreachable (сервер не отвечает на порту), email_timeout (сервер не ответил вовремя), email_port_not_allowed, email_protocol_error (неожиданный ответ сервера), email_folder_not_found (не открывается «Входящие»), email_provider_requires_oauth (ящик Microsoft 365 или Outlook.com, пароль не принимается, вход через Microsoft появится позже). Слишком частые неудачные проверки одного ящика дают 429 с data.code = "email_test_rate_limited" и заголовком Retry-After.

complete-signup принимает те же поля ящика и необязательные: name (название канала), display_name (имя отправителя в заголовке From; переводы строк запрещены), signature_text (подпись, до 2000 символов, простой текст), save_to_sent (сохранять копию исходящего в «Отправленные», по умолчанию true), initial_sync_days (0, 3 или 7: за сколько дней загрузить уже лежащие во «Входящих» письма, по умолчанию 0), poll_interval_seconds (интервал проверки ящика, от 60 до 900 секунд; если не передан, берётся значение по умолчанию сервера), timezone (идентификатор часового пояса). Загруженная история попадает в чат как история: ИИ-агент, автоматизации и уведомления на неё не срабатывают. Ответы: 201 канал создан; 409 с data.code = "mailbox_already_connected", если этот адрес уже подключён в вашей компании; 422 при невалидном теле; 422 с data = { message, code, imap, smtp, sent_folder }, если проверка ящика не прошла (code это код первой неудачной стороны, сначала IMAP, затем SMTP; отчёт устроен как у test-connection); 429 email_test_rate_limited. Пароль хранится в зашифрованном виде и ни в одном ответе не возвращается.

GET /channels/{channel}/email-settings (право channel.view) возвращает настройки ящика без секретов: channel_id, provider, email_address, display_name, username, imap_host, imap_port, imap_security, smtp_host, smtp_port, smtp_security, sent_folder, save_to_sent, quote_on_reply, poll_interval_seconds, initial_sync_days, signature_text, filters (skip_bulk, по умолчанию true, и skip_auto_replies, по умолчанию false), а также состояние проверки: last_polled_at, last_success_at, consecutive_failures, last_error_code. PATCH по тому же пути (право channel.update) меняет только безобидные параметры: display_name, signature_text, poll_interval_seconds (60–900), save_to_sent, quote_on_reply и filters.skip_bulk / filters.skip_auto_replies (передайте только те флаги, которые нужно изменить; остальные сохраняются). Пустая строка в display_name или signature_text сбрасывает значение в null. Адрес, логин, пароль и серверы через PATCH не меняются: их передача даёт 422 с подсказкой использовать reconnect. Канал другой компании и канал не типа email отвечают одинаково: 404.

Пароль, логин и серверы email-канала меняются через POST /channels/{channel}/reconnect. Обязателен password; необязательны username, imap_host, imap_port, smtp_host, smtp_port (не переданные берутся из текущих настроек). Адрес ящика изменить нельзя. Полная проверка ящика выполняется заново с тем же бюджетом запросов, что у test-connection, и прежний секрет заменяется только после успешной проверки. Если проверка не прошла, ответ 422 содержит data.code (первая неудачная сторона) и отчёт imap / smtp, а прежний пароль остаётся нетронутым; частые неудачи дают 429 email_test_rate_limited. После успешного обновления канал снова начинает проверяться, письма, пришедшие за время простоя, подтягиваются. Когда сервер перестаёт принимать пароль, канал получает статус expired и last_error_code = "email_auth_failed"; при длительной недоступности сервера (10 неудачных проверок подряд) статус становится disconnected с last_error_code = "email_unreachable".