Contacts

連絡先を追加

チャネルアカウントに連絡先を追加します。phone_number または username の少なくとも一方を指定します。whatsapp_options は WhatsApp のみで使用でき、未対応チャネルは 501 unsupported_by_provider を返します。

POSThttps://api.unifyport.ai/v1/accounts/{account_id}/contacts/add

呼び出す前に

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

パラメーターの取得元

account_id: アカウント作成・取得応答の data.id を使います。識別子は X-Api-Key のワークスペースに属します。アカウント取得

リクエスト

curl -X POST "https://api.unifyport.ai/v1/accounts/{account_id}/contacts/add" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "phone_number": "8600000000000",
  "username": "alice_user",
  "whatsapp_options": {
    "first_name": "Alice",
    "full_name": "Alice Example",
    "sync_to_device_contacts": false
  }
}'

リクエストパラメータ

ヘッダー

X-Api-Key

string必須

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

Content-Type

string必須

JSON のリクエストボディを送る場合は application/json を使用します。

パスパラメータ

account_id

string必須

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

リクエストボディ

phone_number

string

国または地域コードを含む数字のみの電話番号。プラス記号、空白、区切り文字は含めません。phone_number または username を指定します。

minLength: 1

username

string

チャネルのユーザー名。username または phone_number を指定し、形式は対象チャネルに従います。

minLength: 1

whatsapp_options

object

WhatsApp 専用の任意連絡先設定。first_name、full_name、sync_to_device_contacts は whatsapp_options 内にのみネストし、他のチャネルではこのオブジェクトを省略します。

first_name

string

WhatsApp 連絡先の任意の名。

full_name

string

WhatsApp 連絡先の任意の氏名。

sync_to_device_contacts

boolean

現在の WhatsApp アカウントに関連付けられた端末のシステム連絡先にも保存するか。デフォルトは false。

結果の確認

記載された応答項目と HTTP 状態を確認します。204 成功には本文がありません。診断には X-Request-Id を使い、次は関連操作を参照します。

レスポンス 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "id": "8600000000000@s.whatsapp.net",
    "conversation_id": "123456789012345@lid",
    "display_name": "Alice Example",
    "avatar_url": "",
    "provider_user_id": "8600000000000@s.whatsapp.net",
    "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 ヘッダが欠落しているか無効です。

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