АккаунтыPOST

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

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

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

Заголовки

X-Api-Key

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

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

Content-Type

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

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

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

У этого эндпоинта нет параметров пути.

Тело запроса

name

string

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

provider

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

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

enum: telegram, whatsapp, line, twitter, zalo, tiktok, 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 недопустим. Не логируйте секреты.

proxy

object

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

Тело ответа

id

string

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

name

string

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

provider

string

Идентификатор провайдера, например telegram, whatsapp, line, twitter, zalo или tiktok.

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

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.

Ответы

201

201 Created

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

400

Bad Request

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

401

Unauthorized

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

409

Conflict

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

500

Internal Server Error

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

503

Service Unavailable

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

Запрос

curl -X POST https://api.unifyport.ai/v1/accounts \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Telegram Production",
  "provider": "telegram",
  "region": "global",
  "status": "active",
  "auth_mode": "qrcode",
  "capabilities": ["send_message", "receive_message"],
  "provider_data": {},
  "metadata": {
    "env": "production"
  },
  "provider_account_ref": "provider-side-identifier"
}'

Ответ

{
  "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"
  }
}