Справочник API

Аккаунты

Список аккаунтов

Возвращает аккаунты провайдеров в текущем workspace. Состояние аутентификации доступно через эндпоинты Authentication.

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

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

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

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

Заголовки

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

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

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

limit
integer

Максимальное число аккаунтов на странице: от 1 до 100, по умолчанию 20. Недопустимое значение или повторная передача параметра limit возвращает 400 invalid_request (numeric_code=10000). Для следующих страниц значение можно менять.

minimum: 1 · maximum: 100

cursor
string

Непрозрачный курсор списка аккаунтов. Для первой страницы опустите параметр или передайте пустую строку; для следующей передайте data.next_cursor из предыдущего ответа без изменений. Действителен только в workspace, где был выдан. Недопустимый cursor, повторная передача параметра или использование в другом workspace возвращает 400 invalid_request (numeric_code=10000).

Тело запроса

Этот эндпоинт не требует JSON-тела запроса.

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

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

Ответ 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "items": [
      {
        "id": "acc_example",
        "name": "Telegram Production",
        "provider": "telegram",
        "region": "global",
        "status": "active",
        "runtime_status": "running",
        "auth_mode": "qrcode",
        "capabilities": [
          "send_message",
          "receive_message"
        ],
        "metadata": {
          "env": "production"
        },
        "provider_account_ref": "provider-side-identifier",
        "provider_profile": {
          "id": "778899",
          "phone": "8600000000000",
          "username": "production_bot",
          "display_name": "Production Bot",
          "first_name": "Production",
          "last_name": "Bot",
          "avatar_url": "https://example.com/avatar.jpg",
          "bio": "Customer support"
        }
      }
    ],
    "has_more": false
  }
}

Тело ответа

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.

has_more
boolean

Есть ли следующая страница списка аккаунтов.

next_cursor
string

Непрозрачный курсор следующей страницы списка аккаунтов, возвращается только при has_more=true. Передайте его без изменений как cursor для следующей страницы; на последней странице поле отсутствует.

Ответы

200

200 OK

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

400

Bad Request

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

401

Unauthorized

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

500

Internal Server Error

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

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

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

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