Contacts

連絡先取得

通常の連絡先不存在は 404 contact_not_found。対象会話が存在しない場合は 422 contact_not_found、numeric_code 35000、message Conversation not found を返します。

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

呼び出す前に

対象ワークスペースの X-Api-Key をサーバー側で使用します。実行前にすべてのプレースホルダーを置き換えます。

パラメーターの取得元

account_id: アカウント作成・取得応答の data.id を使います。識別子は X-Api-Key のワークスペースに属します。アカウント取得
contact_id: プロバイダ側の連絡先識別子。不透明な文字列として渡してください。whatsapp と whatsapp-protocol は LID（xxx@lid）を使用します。whatsapp-protocol は連絡先プロフィールのフィールドが欠けていても成功を返す場合があるため、実際に返されたフィールドに従ってください。

WhatsApp Protocol: 連絡先詳細には既存の LID（xxx@lid）が必要です。data.sender.id または data.conversation.id が @lid で終わる場合のみ再利用できます。Protocol に連絡先一覧 API はなく、この API も電話番号から LID を求められません。LID がなければ照会できません。成功応答でもプロフィール項目が省略される場合があります。

リクエストパラメータ

ヘッダー

X-Api-Key

string必須

ワークスペース API キー。このヘッダーからワークスペースを特定します。

パスパラメータ

account_id

string必須

contacts ルートで使用される識別子。

クエリパラメータ

contact_id

string必須

プロバイダ側の連絡先識別子。不透明な文字列として渡してください。whatsapp と whatsapp-protocol は LID（xxx@lid）を使用します。whatsapp-protocol は連絡先プロフィールのフィールドが欠けていても成功を返す場合があるため、実際に返されたフィールドに従ってください。

リクエストボディ

このエンドポイントは JSON ボディを必要としません。

結果の確認

返されたプロフィール項目のみ使用します。識別子は不透明な文字列です。項目の欠如は連絡先の不存在を意味しません。

レスポンス 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "id": "user_example",
    "conversation_id": "peer_example",
    "display_name": "Alice",
    "avatar_url": "",
    "provider_user_id": "user_example",
    "extra": {
      "phone": "8600000000000"
    }
  }
}

レスポンスボディ

id

string

連絡先識別子。

conversation_id

string

この連絡先の会話識別子。メッセージ送信やチャットの特定に使用します。

display_name

string

連絡先の表示名。ない場合は空文字列。

avatar_url

string

連絡先のアバター URL。ない場合は空文字列。

provider_user_id

string

連絡先のプロバイダ側ユーザー識別子。

is_blocked

boolean

接続アカウントがこの連絡先をブロックしているかどうか。

extra

object

phone などプロバイダ固有の追加フィールド。

phone

string

WhatsApp phone JID 中解析出的纯手机号。

first_name

string

当前账号通讯录中保存的联系人简称或名字部分。

full_name

string

当前账号通讯录中保存的完整联系人名称。

push_name

string

联系人自行在 WhatsApp 设置的个人名称。

business_name

string

WhatsApp Business 账号的商业或认证名称。

redacted_phone

string

Provider 仅返回部分号码时的遮蔽手机号。

レスポンス

200

200 OK

リクエスト成功。レスポンスボディの例を参照してください。

400

Bad Request

リクエストボディ、パス、またはパラメータが不正です。

401

Unauthorized

X-Api-Key ヘッダが欠落しているか無効です。

404

Not Found

要求されたプロバイダリソースが見つかりません。

409

Conflict

要求された操作が、既存のプロバイダアカウントまたはリソースと競合しています。

422

Unprocessable Entity

リクエストは有効ですが、対象のプロバイダ会話を解決できません。

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 とワークスペースの有効性を確認します。