Contacts

連絡先取得

X の id はユーザー名です。provider_user_id と conversation_id は、どちらも X の数値ユーザー ID を文字列で返します。成功時はプロフィールが取得されています。通常の連絡先不存在は 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

対応チャネル

WhatsAppLINEXWhatsApp Protocol

呼び出す前に

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

パラメーターの取得元

account_id: アカウント作成・取得応答の data.id を使います。識別子は X-Api-Key のワークスペースに属します。アカウント取得
contact_id: X（twitter）では @ を付けずにユーザー名を指定します（例：alice_example）。プロバイダ側の連絡先識別子。不透明な文字列として渡してください。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必須

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

リクエストボディ

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

結果の確認

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

レスポンス 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "id": "alice_example",
    "conversation_id": "1234567890123456789",
    "display_name": "Alice Example",
    "avatar_url": "https://media.example.com/avatar.jpg",
    "provider_user_id": "1234567890123456789"
  }
}

レスポンスボディ

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 で設定したプロフィール名。

username

string

WhatsApp の連絡先のユーザー名（provider=whatsapp）で、プロフィール名 push_name とは独立しています。一覧と詳細では空でないユーザー名を取得済みの場合のみ返されます。欠落は現時点で不明であることを意味し、相手が未設定であることを示すものではありません。欠落を理由に保存済みのユーザー名を消去しないでください。

minLength: 1

business_name

string

WhatsApp Business アカウントのビジネス名または認証済みの名前。

redacted_phone

string

プロバイダーが番号の一部だけを返した場合のマスクされた電話番号。

レスポンス

200

200 OK

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

400

Bad Request

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

401

Unauthorized

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

403

Forbidden

リクエストは識別されましたが、この操作は許可されていません。

404

Not Found

要求されたリソースが見つかりません。error.code と現在の操作を合わせて確認してください。

409

Conflict

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

422

Unprocessable Entity

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

500

Internal Server Error

サービスで予期しないエラーが発生しました。

501

Not Implemented

選択したプロバイダはこの操作を実装していません。

502

Bad Gateway

プロバイダアダプタまたは上流サービスが操作を完了できませんでした。

失敗時の対応

HTTP 状態と error.code/numeric_code を確認し、request_id を保存します。原因に応じてパラメーター修正・認証・状態確認を行い、送信や書き込みの再試行前に前回の結果を確認します。エラーリファレンス

HTTP ステータス、error.code、error.numeric_code を現在の操作と合わせて確認します。数値コードは文字列です。request_id は調査用で、冪等性キーやタスク ID ではありません。

invalid_request · 10000 · 400

JSON 本文と必須項目を確認してください。

対処と再試行: 操作とチャネルの条件に従ってパラメーターを修正してから再実行します。同じ無効なリクエストを繰り返しても解決しません。

JSON の例です。message は実際の原因によって変わります · 400 · 10000

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_request",
    "numeric_code": "10000",
    "message": "Invalid request parameters"
  }
}

invalid_target_workspace · 11003 · 400

上書き対象のワークスペースが空、または形式が無効です。上書き用ヘッダーを削除し、対象ワークスペースの API Key を使用してください。

発生条件: ワークスペースを上書きする X-Workspace-Id リクエストヘッダーを送った場合に適用されます。

対処と再試行: 操作とチャネルの条件に従ってパラメーターを修正してから再実行します。同じ無効なリクエストを繰り返しても解決しません。

JSON の例です。message は実際の原因によって変わります · 400 · 11003

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_target_workspace",
    "numeric_code": "11003",
    "message": "Invalid target workspace"
  }
}

provider_invalid_request · 30001 · 400

チャネル固有の項目と形式を確認してください。

対処と再試行: 操作とチャネルの条件に従ってパラメーターを修正してから再実行します。同じ無効なリクエストを繰り返しても解決しません。

JSON の例です。message は実際の原因によって変わります · 400 · 30001

{
  "request_id": "req_example",
  "error": {
    "code": "provider_invalid_request",
    "numeric_code": "30001",
    "message": "Provider rejected the request"
  }
}

invalid_api_key · 11001 · 401

API Key が正しく有効か確認してください。

対処と再試行: request_id と構造化されたコードを保存し、現在の操作を調査してから次の対応を決めます。

JSON の例です。message は実際の原因によって変わります · 401 · 11001

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_api_key",
    "numeric_code": "11001",
    "message": "Invalid API key"
  }
}

missing_api_key · 11000 · 401

X-Api-Key ヘッダーを追加してください。

対処と再試行: request_id と構造化されたコードを保存し、現在の操作を調査してから次の対応を決めます。

例 · 401 · 11000

{
  "request_id": "req_xxx",
  "error": {
    "code": "missing_api_key",
    "numeric_code": "11000",
    "message": "Missing X-Api-Key header"
  }
}

workspace_override_forbidden · 11002 · 403

この API Key に許可されていないワークスペースの上書きを要求しています。上書き用ヘッダーを削除し、対象ワークスペースの API Key を使用してください。

発生条件: ワークスペースを上書きする X-Workspace-Id リクエストヘッダーを送った場合に適用されます。

対処と再試行: request_id と構造化されたコードを保存し、現在の操作を調査してから次の対応を決めます。

JSON の例です。message は実際の原因によって変わります · 403 · 11002

{
  "request_id": "req_example",
  "error": {
    "code": "workspace_override_forbidden",
    "numeric_code": "11002",
    "message": "Workspace override is not allowed"
  }
}

contact_not_found · 35000 · 404

このアカウントで連絡先が見つかりません。識別子を確認してください。

対処と再試行: 対象の識別子、所有範囲、現在のワークスペースを確認します。不存在やアクセス不可が確認された対象を、一時的なサービス障害として自動再試行しないでください。

JSON の例です。message は実際の原因によって変わります · 404 · 35000

{
  "request_id": "req_example",
  "error": {
    "code": "contact_not_found",
    "numeric_code": "35000",
    "message": "Contact not found"
  }
}

target_workspace_not_found · 11004 · 404

上書きで指定したワークスペースが存在しないか利用できません。所有範囲を確認し、上書き用ヘッダーを削除して対象ワークスペースの API Key を使用します。再試行で権限は増えません。

発生条件: ワークスペースを上書きする X-Workspace-Id リクエストヘッダーを送った場合に適用されます。

JSON の例です。message は実際の原因によって変わります · 404 · 11004

{
  "request_id": "req_example",
  "error": {
    "code": "target_workspace_not_found",
    "numeric_code": "11004",
    "message": "Target workspace not found"
  }
}

account_binding_not_found · 30006 · 409

有効なチャネル接続への紐付けがありません。アカウントの状態を確認してください。

対処と再試行: 認証と実行状態を照会し、目的の状態とチャネルの対応範囲に応じて更新・起動・再接続を選びます。接続の問題だけではログアウトしたとは判断できません。接続が必要な業務操作の前に running を確認してください。

JSON の例です。message は実際の原因によって変わります · 409 · 30006

{
  "request_id": "req_example",
  "error": {
    "code": "account_binding_not_found",
    "numeric_code": "30006",
    "message": "Account is not bound to an available server"
  }
}

egress_configuration_pending · 20032 · 409

プラットフォームの既定のネットワーク設定を確認または読み込みできません。ログアウトを意味するものではありません。

発生条件: この操作はプラットフォームのネットワーク容量、またはアカウントに固定された既定のネットワーク設定を使用します。

対処と再試行: request_id を保存し、再度書き込む前にアカウントや作成結果を確認してください。容量や設定の復旧を待つか、サポートに連絡してください。アカウント作成、ネットワーク変更、再起動を自動で繰り返さないでください。

JSON の例です。message は実際の原因によって変わります · 409 · 20032

{
  "request_id": "req_example",
  "error": {
    "code": "egress_configuration_pending",
    "numeric_code": "20032",
    "message": "Account network configuration is pending verification"
  }
}

provider_not_ready · 30009 · 409

接続が未準備です。認可と runtime_status を確認してから再試行を判断してください。

JSON の例です。message は実際の原因によって変わります · 409 · 30009

{
  "request_id": "req_example",
  "error": {
    "code": "provider_not_ready",
    "numeric_code": "30009",
    "message": "Provider client is not ready"
  }
}

provider_not_ready · 30014 · 409

このアカウントに必要なチャネルのインスタンスがありません。実行環境の可用性の問題であり、認証の期限切れを示すものではありません。

対象チャネル: WhatsApp

JSON の例です。message は実際の原因によって変わります · 409 · 30014

{
  "request_id": "req_example",
  "error": {
    "code": "provider_not_ready",
    "numeric_code": "30014",
    "message": "Provider instance is missing"
  }
}

provider_not_ready · 30015 · 409

チャネルの実行プロセスは停止しています。起動前に意図した停止かを確認してください。実行の停止自体はログアウトを意味しません。

対象チャネル: WhatsApp

JSON の例です。message は実際の原因によって変わります · 409 · 30015

{
  "request_id": "req_example",
  "error": {
    "code": "provider_not_ready",
    "numeric_code": "30015",
    "message": "Provider runtime is stopped"
  }
}

contact_not_found · 35000 · 422

GET /contacts/info が Conversation not found を返しました。対象の識別子と照会アカウントを確認してください。

発生条件: チャネルが対象の会話の不存在を明示的に確認した場合にのみ適用されます。

対象チャネル: WhatsApp

例 · 422 · 35000

{
  "request_id": "req_xxx",
  "error": {
    "code": "contact_not_found",
    "numeric_code": "35000",
    "message": "Conversation not found"
  }
}

get_contact_failed · 20020 · 500

account_id を確認し、アカウントが属するワークスペースの X-Api-Key を使います。このワークスペースにないアカウントには現在のキーでアクセスできません。

発生条件: アカウントが見つからない場合、従来の HTTP ステータスと操作の code を維持し、numeric_code でアカウントの不存在を示します。

JSON の例です。message は実際の原因によって変わります · 500 · 20020

{
  "request_id": "req_example",
  "error": {
    "code": "get_contact_failed",
    "numeric_code": "20020",
    "message": "Account not found"
  }
}

get_contact_failed · 30010 · 500

チャネルが操作を完了できませんでした。message に「Provider operation failed:」以降の元の原因が含まれる場合があります。原因の文面は可変で、安定したプログラムのインターフェースではありません。

発生条件: チャネルがより具体的な失敗分類を返さない場合、現在の操作のエラーを維持します。

対処と再試行: request_id を保存し、識別子とアカウントのアクセス範囲を確認します。原因を確認してから照会を再試行してください。照会失敗は空の結果やリソースの不存在を意味しません。

対象チャネル: WhatsApp

JSON の例です。message は実際の原因によって変わります · 500 · 30010

{
  "request_id": "req_example",
  "error": {
    "code": "get_contact_failed",
    "numeric_code": "30010",
    "message": "Provider operation failed"
  }
}

get_contact_failed · 35002 · 500

連絡先取得：サービスが有効な照会結果を返せませんでした。

JSON の例です。message は実際の原因によって変わります · 500 · 35002

{
  "request_id": "req_example",
  "error": {
    "code": "get_contact_failed",
    "numeric_code": "35002",
    "message": "Failed to get contact"
  }
}

unsupported_by_provider · 30003 · 501

チャネルが未対応です。対応表から利用可能な操作を選んでください。

対処と再試行: ドキュメントで対応しているチャネルと操作を選びます。同じリクエストを繰り返しても機能やベータ権限は追加されません。

例 · 501 · 30003

{
  "request_id": "req_xxx",
  "error": {
    "code": "unsupported_by_provider",
    "numeric_code": "30003",
    "message": "Operation not supported by this provider"
  }
}

provider_adapter_not_found · 30004 · 502

チャネルサービスを利用できません。状態を確認するか後で再試行してください。書き込みは前回の結果を先に確認してください。

JSON の例です。message は実際の原因によって変わります · 502 · 30004

{
  "request_id": "req_example",
  "error": {
    "code": "provider_adapter_not_found",
    "numeric_code": "30004",
    "message": "Provider adapter unavailable"
  }
}

provider_unavailable · 30002 · 502

チャネルサービスを利用できません。状態を確認するか後で再試行してください。書き込みは前回の結果を先に確認してください。

例 · 502 · 30002

{
  "request_id": "req_example_provider_unavailable",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "30002",
    "message": "Provider service unavailable"
  }
}

provider_unavailable · 30010 · 502

対象チャネル: WhatsApp

例 · 502 · 30010

{
  "request_id": "req_example_operation_failed",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "30010",
    "message": "Provider operation failed: Example operation could not be completed"
  }
}

provider_unavailable · 30020 · 502

whatsapp-protocol の同期リクエストは numeric_code=30020 でログイン制限を示します。セッションのインポート、実行操作、送信、連絡先照会に影響する場合がありますが、現在の操作の HTTP ステータスと code を維持します。このチャネルに WhatsApp の 20102 イベント契約を適用しないでください。

対処と再試行: 自動送信と再試行を停止し、公式 WhatsApp アプリで制限を確認・解消するようユーザーに案内します。解消と必要な再認証の後に再開してください。以前の running 状態は制限解除の証拠にはなりません。

対象チャネル: WhatsApp Protocol

例 · 502 · 30020

{
  "request_id": "req_example_account_restricted",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "30020",
    "message": "Account login is restricted. Check the official WhatsApp app for details."
  }
}

provider_unavailable · 30021 · 502

このリクエスト時点で、アカウントはメッセージングプラットフォームに接続されていませんでした。WhatsApp の連絡先追加では 500 / create_contact_failed / 30021 が返ることがあります。ログアウトや、現在も実行状態が disconnected であることを意味しません。現在の状態を照会してから復旧方法を選んでください。

対処と再試行: 接続が必要な業務操作を停止します。まず POST /v1/accounts/{account_id}/runtime/refresh を呼び、最新状態に従って復旧し、runtime_status=running を確認してから業務 API を実行します。再送前に前回の書き込み結果を確認してください。

対象チャネル: WhatsApp

例 · 502 · 30021

{
  "request_id": "req_example_connection_disconnected",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "30021",
    "message": "example operation: websocket not connected"
  }
}