Contacts
連絡先一覧
連絡先をリアルタイム一覧します。limit は 1..100、既定 50。無効または期限切れ cursor の扱いは Provider ごとに異なります。
https://api.unifyport.ai/v1/accounts/{account_id}/contacts呼び出す前に
対象ワークスペースの X-Api-Key をサーバー側で使用します。実行前にすべてのプレースホルダーを置き換えます。
パラメーターの取得元
- account_id
- アカウント作成・取得応答の data.id を使います。識別子は X-Api-Key のワークスペースに属します。 アカウント取得
リクエストパラメータ
ヘッダー
X-Api-Keyワークスペース API キー。このヘッダーからワークスペースを特定します。
パスパラメータ
account_idcontacts ルートで使用される識別子。
クエリパラメータ
cursor不透明な next_cursor。先頭は省略します。無効・期限切れ cursor の扱いは Provider ごとに異なります。
limitページサイズは 1〜100。既定値は各エンドポイント説明を参照してください。
minimum: 1 · maximum: 100
qdisplay_name、phone、または username に一致する検索フィルタ。
updated_sinceRFC3339 タイムスタンプ。それ以降に更新された連絡先のみを返し、プロバイダが対応する場合の差分同期に利用します。
format: date-time
リクエストボディ
このエンドポイントは JSON ボディを必要としません。
結果の確認
記載された応答項目と HTTP 状態を確認します。204 成功には本文がありません。診断には X-Request-Id を使い、次は関連操作を参照します。
レスポンス 200 OK
{
"request_id": "<REQUEST_ID>",
"data": {
"items": [
{
"id": "user_example",
"conversation_id": "peer_example",
"display_name": "Alice",
"avatar_url": "",
"provider_user_id": "user_example",
"extra": {
"phone": "8600000000000"
}
}
],
"next_cursor": "",
"has_more": false
}
}
レスポンスボディ
id連絡先識別子。
conversation_idこの連絡先の会話識別子。メッセージ送信やチャットの特定に使用します。
display_name連絡先の表示名。ない場合は空文字列。
avatar_url連絡先のアバター URL。ない場合は空文字列。
provider_user_id連絡先のプロバイダ側ユーザー識別子。
is_blocked接続アカウントがこの連絡先をブロックしているかどうか。
extraobjectphone などプロバイダ固有の追加フィールド。
extraphone などプロバイダ固有の追加フィールド。
phoneWhatsApp phone JID 中解析出的纯手机号。
first_name当前账号通讯录中保存的联系人简称或名字部分。
full_name当前账号通讯录中保存的完整联系人名称。
push_name联系人自行在 WhatsApp 设置的个人名称。
business_nameWhatsApp Business 账号的商业或认证名称。
redacted_phoneProvider 仅返回部分号码时的遮蔽手机号。
next_cursor次ページ用の不透明なカーソル。cursor として渡し直します。空文字列の場合は次のページがないことを意味します。
has_moreこのページの先にさらに結果がある場合は true。
レスポンス
200200 OK
リクエスト成功。レスポンスボディの例を参照してください。
400Bad Request
リクエストボディ、パス、またはパラメータが不正です。
401Unauthorized
X-Api-Key ヘッダが欠落しているか無効です。
409Conflict
要求された操作が、既存のプロバイダアカウントまたはリソースと競合しています。
500Internal Server Error
サービスで予期しないエラーが発生しました。
501Not Implemented
選択したプロバイダはこの操作を実装していません。
502Bad Gateway
プロバイダアダプタまたは上流サービスが操作を完了できませんでした。
失敗時の対応
HTTP 状態と error.code/numeric_code を確認し、request_id を保存します。原因に応じてパラメーター修正・認証・状態確認を行い、送信や書き込みの再試行前に前回の結果を確認します。 エラーリファレンス
- invalid_request · 10000 · 400
- 必須項目、形式、チャネルの条件を確認して修正します。
- invalid_api_key · 11001 · 401
- X-Api-Key とワークスペースの有効性を確認します。