Справочник API

Аккаунты

Создать аккаунт

Создаёт аккаунт провайдера. auth_mode обязателен и принимает qrcode, code или session. Если комбинации provider + auth_mode нужен телефон, передайте provider_data.phone; значение сохраняется для следующих действий аутентификации.

POSThttps://api.unifyport.ai/v1/accounts

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

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

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

Заголовки

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

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

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

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

Тело запроса

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. Следующий шаг указан в связанных операциях.

Ответ 201 Created

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "id": "acc_example",
    "name": "Telegram Production",
    "provider": "telegram",
    "region": "global",
    "status": "active",
    "runtime_status": "stopped",
    "auth_mode": "qrcode",
    "capabilities": [
      "send_message",
      "receive_message"
    ],
    "provider_account_ref": "provider-side-identifier"
  }
}

Тело ответа

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

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

Ответы

201

201 Created

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

400

Bad Request

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

401

Unauthorized

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

409

Conflict

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

500

Internal Server Error

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

503

Service Unavailable

Необходимая серверная служба временно недоступна.

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

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

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