Справочник API

Аккаунты

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

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

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

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

Используйте 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 недопустим. Не логируйте секреты. При создании аккаунта Telegram поля api_id и api_hash необязательны. Если не указаны собственные учётные данные приложения, платформа использует учётные данные приложения по умолчанию. Для своего приложения передайте оба значения одного и того же приложения Telegram в виде строк.

proxy
object

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

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

Следуйте описанию полей и HTTP-статуса. Успешный 204 не содержит тела; для диагностики используйте X-Request-Id. Следующий шаг указан в связанных операциях.

Ответ 200 OK

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

Тело ответа

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

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

provider_profile
object

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

id
string

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

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.

Ответы

200

200 OK

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

400

Bad Request

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

401

Unauthorized

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

409

Conflict

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

500

Internal Server Error

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

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

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

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