Справочник API

Groups

Список групп

Возвращает группы в реальном времени. limit: 1..100, по умолчанию 50. Невалидные или устаревшие cursor обрабатываются провайдерами по-разному.

GEThttps://api.unifyport.ai/v1/accounts/{account_id}/groups

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

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

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

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

Заголовки

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

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

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

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

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

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

cursor
string

Непрозрачный курсор провайдера. Передавайте предыдущий next_cursor без изменений; пропустите или оставьте пустым для первой страницы. Поддельные, просроченные или повторно используемые в других запросах курсоры могут игнорироваться, сбрасываться на первую страницу или вызывать ошибку провайдера. Не рассчитывайте на единообразный ответ 400.

limit
integer

Размер страницы от 1 до 100; значение по умолчанию указано на странице эндпоинта.

minimum: 1 · maximum: 100

Тело запроса

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

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

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

Ответ 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "items": [
      {
        "id": "group_example",
        "conversation_id": "group_example",
        "name": "Project team",
        "avatar_url": "",
        "member_count": 5,
        "joined_at": "2026-07-01T08:00:00Z",
        "created_at": "2026-06-15T08:00:00Z",
        "description": "Project coordination group",
        "extra": {}
      }
    ],
    "next_cursor": "",
    "has_more": false
  }
}

Тело ответа

id
string

Идентификатор группы. Для группы conversation_id равен этому id.

conversation_id
string

Идентификатор беседы для группы; равен id.

name
string

Название группы.

avatar_url
string

URL аватара группы или пустая строка, если он не задан.

member_count
integer

Число участников в группе.

format: int64

joined_at
string

Время вступления подключённого аккаунта в группу, если доступно.

format: date-time

created_at
string

Время создания группы по данным провайдера, если доступно.

format: date-time

description
string

Описание группы, когда оно доступно.

permissions
object

Group-wide speaking permissions, returned only when explicitly supplied by the source. Missing means unknown; admins_only=false permits ordinary members to speak, but does not guarantee this account can send.

admins_only
boolean

true means only administrators may speak; false is an explicit state, not an omitted or default value.

extra
object

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

is_announcement_group
boolean

Предоставляется только для групп WhatsApp. true подтверждает, что это группа объявлений сообщества; false означает, что текущие данные подтверждают несоответствие условиям такой группы. Отсутствие поля означает неизвестное состояние; null не возвращается. Эта классификация не указывает на право текущего аккаунта отправлять сообщения. Не зависит от permissions.admins_only.

next_cursor
string

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

has_more
boolean

true, когда за пределами этой страницы доступно больше результатов.

Ответы

200

200 OK

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

400

Bad Request

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

401

Unauthorized

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

409

Conflict

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

500

Internal Server Error

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

501

Not Implemented

Выбранный провайдер не реализует эту операцию.

502

Bad Gateway

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

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

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

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