Groups

グループ一覧

グループをリアルタイム一覧します。limit は 1..100、既定 50。無効または期限切れ cursor の扱いは Provider ごとに異なります。

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 を保存します。原因に応じてパラメーター修正・認証・状態確認を行い、送信や書き込みの再試行前に前回の結果を確認します。エラーリファレンス

invalid_request · 10000 · 400: 必須項目、形式、チャネルの条件を確認して修正します。
invalid_api_key · 11001 · 401: X-Api-Key とワークスペースの有効性を確認します。