Справочник API

Аккаунты

Обновить аккаунт

Частично обновляет аккаунт. Пропущенные поля сохраняются; null недопустим; пустые массивы и объекты очищают соответствующие поля. Дубликат идентичности возвращает 409 duplicate_provider_account.

PATCHhttps://api.unifyport.ai/v1/accounts/{account_id}

Поддерживаемые каналы

all

Перед вызовом

Используйте X-Api-Key нужного рабочего пространства на сервере. Перед запуском замените все заполнители.

Откуда взять параметры
account_id
Возьмите data.id из создания или запроса аккаунта. Идентификатор относится к рабочему пространству X-Api-Key. Получить аккаунт

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

Заголовки

X-Api-Key
stringобязательно

API-ключ рабочей области. Рабочая область определяется по этому заголовку.

Content-Type
stringобязательно

Используйте application/json при отправке JSON-тела запроса.

Параметры пути

account_id
stringобязательно

Идентификатор для маршрута раздела accounts.

Тело запроса

name
string

Понятное человеку имя аккаунта.

provider
string

Клиентский идентификатор провайдера: telegram, whatsapp, whatsapp-protocol, line, twitter, zalo или tiktok.

enum: telegram, whatsapp, line, twitter, zalo, tiktok, whatsapp-protocol, x, x_client, twitter_client

region
string

Регион провайдера, используемый для выделения. Выберите регион со значением allocatable: true из Список регионов провайдера.

minLength: 1

status
string

Бизнес-состояние аккаунта, например active или inactive.

runtime_status
string

Запрашиваемое состояние runtime, если провайдер позволяет менять его через настройки аккаунта.

enum: unknown, starting, running, stopping, stopped, reconnecting, disconnected, error

auth_mode
string

Обязателен при создании аккаунта: qrcode, code или session.

enum: qrcode, code, session

capabilities[]
string[]

В PATCH пропустите для сохранения, передайте [] для очистки; null недопустим.

metadata
object

В PATCH пропустите для сохранения, передайте {} для очистки; null недопустим.

provider_account_ref
string

Идентификатор аккаунта на стороне провайдера, обычно заполняемый после авторизации.

provider_data
object

Настройки провайдера. В PATCH отсутствие сохраняет значение; {} очищает без добавления учётных данных по умолчанию; null недопустим. TikTok provider_data.enable_comment принимает только Boolean, по умолчанию false; строки, числа и null дают 400 invalid_request. Изменения онлайн требуют reconnect; успех start не подтверждает применение, отключение не отзывает события из очереди. Telegram api_id и api_hash необязательны для code, qrcode и session; собственные данные передаются парой строк одного приложения. При создании без собственных данных и пропуске полей учётных данных в непустой замене используются значения платформы по умолчанию; если нужные значения недоступны, запрос завершается ошибкой. Смена значений по умолчанию не заменяет данные существующих аккаунтов. Не записывайте секреты в журнал.

proxy
object

Необязательная конфигурация исходящего прокси для аккаунта.

Как понять результат

Оцените результат по полям ответа и HTTP-статусу этого API, затем выберите следующий шаг в связанных операциях.

Ответ 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "id": "acc_example",
    "name": "Telegram Production",
    "provider": "telegram",
    "status": "active",
    "auth_mode": "code"
  }
}

Тело ответа

provider_profile
object

Профиль, сообщённый провайдером, например display_name. Не возвращается до аутентификации аккаунта.

id
string

Непрозрачный идентификатор аккаунта в подключённом канале. Для WhatsApp это может быть canonical LID без суффикса устройства.

device_id
integer

Необязательный номер устройства входа в сведениях аккаунта WhatsApp, если текущую сессию можно определить. Может измениться после повторной авторизации и не является постоянным идентификатором.

minimum: 0 · maximum: 65535

phone
string

Нормализованный телефон без пробелов, дефисов и начального плюса.

username
string

Имя пользователя у провайдера, если доступно.

display_name
string

Отображаемое имя аккаунта; для WhatsApp оно формируется с приоритетом BusinessName и резервным переходом на PushName.

push_name
string

PushName, сейчас заданный в аккаунте WhatsApp; другие провайдеры не определяют семантику этого поля.

business_name
string

WhatsApp BusinessName; поле отсутствует, если provider не возвращает значение.

first_name
string

Имя, сообщённое провайдером.

last_name
string

Фамилия, сообщённая провайдером.

avatar_url
string

URL аватара аккаунта у провайдера.

bio
string

Описание или статус аккаунта у провайдера.

platform
string

Идентификатор платформы входа, который WhatsApp сообщает при сопряжении. Считайте его непрозрачной строкой и поддерживайте неизвестные значения; для других провайдеров смысл поля не определён. Это не поле device_platform.

id
string

Уникальный идентификатор аккаунта (acc_...). Используйте его в маршрутах уровня аккаунта.

name
string

Понятное человеку имя аккаунта.

provider
string

Идентификатор канала. Используйте значение API без изменений; возвращаемые этим API значения указаны в enum ниже.

enum: telegram, whatsapp, line, twitter, zalo, tiktok, whatsapp-protocol

region
string

Регион провайдера, в котором выделен аккаунт.

status
string

Состояние жизненного цикла аккаунта, например active.

runtime_status
string

Нормализованное состояние runtime: одно из unknown, starting, running, stopping, stopped, reconnecting, disconnected или error.

enum: unknown, starting, running, stopping, stopped, reconnecting, disconnected, error

auth_mode
string

Поток аутентификации, используемый аккаунтом: code, qrcode или session.

capabilities[]
string[]

Возможности, включённые для аккаунта, например send_message и receive_message.

metadata
object

Ваши собственные метки окружения, сохранённые в аккаунте.

provider_account_ref
string

Идентификатор на стороне провайдера, который можно привязать для сопоставления аккаунта с вашей собственной системой.

proxy
object

Настройки исходящего прокси аккаунта, если они заданы.

Ответы

200

200 OK

Запрос выполнен. См. пример тела ответа.

400

Bad Request

Тело запроса, путь или параметры некорректны.

401

Unauthorized

Заголовок X-Api-Key отсутствует или недействителен.

409

Conflict

Запрошенная операция конфликтует с существующим аккаунтом провайдера или ресурсом.

500

Internal Server Error

Сервис столкнулся с неожиданной ошибкой.

502

Bad Gateway

Адаптер или вышестоящий провайдер не смог завершить операцию.

При ошибке запроса

Проверьте HTTP и error.code/numeric_code, сохраните request_id. Исправьте параметры, завершите авторизацию или проверьте runtime. До повторной отправки или записи выясните результат предыдущей попытки. Справочник ошибок

invalid_request · 10000 · 400
Проверьте обязательные поля, форматы и условия канала, затем исправьте запрос.
missing_api_key · 11000 · 401
Проверьте X-Api-Key и активность рабочего пространства.
invalid_api_key · 11001 · 401
Проверьте X-Api-Key и активность рабочего пространства.