連絡先

/v1/contacts

contactsノードを使用して、メッセージ送信前にユーザーを検証することによりデータベース内のWhatsAppユーザーを管理し、IDハッシュでユーザーのIDを認証します。

contactsノードを使用して、次のことを実行できます。

• データベースにある電話番号が、有効なWhatsAppアカウントのものであることを確認する。ユーザーにメッセージを送信する前に、statusがvalidであることを確認する必要があります。
• 電話番号に対応しているWhatsApp IDを取得する。メッセージやユーザー通知を送信するには、WhatsApp IDが必要です。

開始する前に

カスタマーに、WhatsAppでのビジネスとのコミュニケーションをオプトインするオプションを提示する必要があります。オプトインフローは各ビジネスが管理します。カスタマーがオプトインしたら、contactsノードを使用して、登録された番号を検証します。詳しくは、WhatsAppでオプトインを取得する方法をご覧ください。

制限

• このエンドポイントを使って、事業者のデータベース内にある電話番号が、有効なWhatsAppアカウントのものであることを確認します
• 呼び出しの数は、電話番号が送信しているメッセージの数を超えてはなりません

ポリシーの施行

事業者がこのエンドポイントを不正使用している場合、以下の措置が取られます。

• 不正使用が疑われる場合、ビジネスマネージャにリストされているすべての管理者に電子メールで最初の警告が送られます
• 事業者は、警告を受け取ってから7日間、行為を改める猶予を与えられます
• 7日間を経過しても呼び出し数が改善されない場合は、電話番号が永続的に無効にされます

推奨事項

メッセージの送信前に連絡先をチェックすることをおすすめします。ただし、カスタマーからの着信メッセージに返信するときは、提供されたwa_idを指定してすぐに返信できるので、連絡先のチェックは不要です。結果はキャッシュされるので、追加費用は発生しません。

作成

オプトインしたユーザーにメッセージを送る前に、POSTリクエストを/v1/contactsエンドポイントに送り、WhatsAppアカウントのユーザー検証リクエストを作成します。呼び出しに、検証する電話番号のリストを含めます。

例

POST /v1/contacts
{
  "blocking": "wait" | "no_wait",
  "contacts": [
  	"16315551000",
  	"+1 631 555 1001",
  	"6315551002",
  	"+1 (631) 555-1004",
  	"1-631-555-1005"
  ],
  "force_check": false | true
}

リクエストした番号の現在のstatusと、そのWhatsApp ID (wa_id)が応答で返されます。

{
  "contacts": [ {
    "wa_id": "16315551000",
    "input": "16315551000",
    "status": "valid"
  },
  {
    "wa_id": "16315551001",
    "input": "+1 631 555 1001",
    "status": "processing" # Only applicable when request is non-blocking
  },
  {
    "input": "6315551002",
    "status": "invalid"
  },
  {
    "input": "+163155588",
    "status": "failed"
  }
}

返されたstatusがvalidだった番号のWhatsApp IDを保存します。有効なユーザーはWhatsAppアカウントを持っているユーザーです。これらのWhatsApp IDを使用して、メッセージとお知らせを送信します。

この手順を定期的に繰り返して、有効なユーザーのリストを管理します。結果はWhatsApp BusinessオンプレミスAPIクライアントのデータベースに7日間キャッシュされます。

パラメーター

/v1/contactsへのPOST呼び出しでは、次のパラメーターがサポートされています。

エッジ

このノードには次のエッジが接続されています。

ブロッキング

blockingパラメーターには、no_waitとwaitの2つのオプションがあります。blockingパラメーターが呼び出しで指定されていない場合は、デフォルトのno_waitになります。

blockingパラメーターによって、リクエストが処理の完了を待機するか(同期)待機しないか(非同期)が決まります。

電話番号の形式

contactsリクエストで使う電話番号は、ダイヤルできる形式であればどんな形式でも構いません。

例として、WhatsApp BusinessオンプレミスAPIクライアントがインドの電話番号(国番号は+91)で登録されている場合は次のようになります。

返されるフィールド

contacts応答のペイロードには、リクエストで送信したものと同じ電話番号の配列と、input、status、wa_idプロパティが含まれます。

processingステータスとともに、HTTPステータス200 OKが返されます。

テンプレートメッセージがWhatsAppアカウントを持たない電話番号に送信されると、「ユーザーが無効である」ことを示すエラーコード 1013付きのエラーメッセージを受け取ります。

応答にその他のエラーが含まれている場合は、エラーメッセージとステータスメッセージをご覧ください。

連絡先をブロックする

ブロックは、悪質行為者が有害な行為を続けるのを阻止するための防御機能とみなされる場合があります。連絡先をブロックするには、過去24時間以内にその連絡先から送信されたメッセージを受け取っている必要があります。

例

別のWhatsAppアカウントをブロックする理由を指定して、API呼び出しを/v1/contacts/{phone_number}/blockに送信します。

POST /v1/contacts/+16315551000/block
{
   "reason": "Optional string(0;60). Freeform block reason. Will be used when another WhatsApp account is being blocked"
}

成功した応答にはHTTPステータス200があり、「エラー」オブジェクトはありません。

失敗した場合の応答は次のようになります。

{   
    "errors": [
        {
            "code": 2048,
            "title": "Not engaged contact",
            "details": "Invalid Request. This contact hasn't engaged with you in the last 24 hrs."
        }
    ]
}

パラメーター

/v1/contacts/{phone_number}/blockへのPOST呼び出しでは、次のパラメーターがサポートされています。

連絡先のブロックを解除する

この呼び出しで連絡先のブロックを解除します

例

API呼び出しを/v1/contacts/{phone_number}/unblockに送信します

POST /v1/contacts/+16315551000/unblock

成功した応答にはHTTPステータス200があり、「エラー」オブジェクトはありません。

失敗した場合の応答は次のようになります。

{   
    "errors": [
        {
            "code": 1009,
            "title": "Parameter value is not valid",
            "details": "Provided WhatsApp ID is not valid. Please provide a valid WhatsApp ID or a phone number with a country code"
        }
    ]
}

パラメーター

/v1/contacts/{phone_number}/unblockへのPOST呼び出しでは、次のパラメーターがサポートされています。

ブロックリスト

ブロックした連絡先のリストを取得する方法は次のようになります。

例

API呼び出しを/v1/contacts/blocklistに送信し、ブロックした連絡先のページ分割されたリストを受け取ります

GET /v1/contacts/blocklist?limit=10&offset=0

受け取る応答には、1ページ分のブロックリストと、ページ分割情報が含まれています

{
   "contacts": [
       {
           "wa_id": "16315551000@s.whatsapp.net"
       }
   ],
   "pagination": {
       "limit": 10,
       "offset": 0,
       "total": 1
   }
}

パラメーター

/v1/contacts/blocklistへのGET呼び出しでは、次のパラメーターがサポートされています。

レポート機能

レポート機能は、悪質行為者の予防対策を構築するための重要なシグナルを提供します。連絡先を報告するには、過去24時間以内にその連絡先から送信されたメッセージを受け取っている必要があります。

例

別のWhatsAppアカウントをブロックしている場合はその理由を指定して、API呼び出しを/v1/contacts/{phone_number}/reportに送信します。

POST /v1/contacts/+16315551000/block
{
   "reason": "Optional string(0;60). Freeform block reason. Will be used when another WhatsApp account is being blocked",
   "block": "true | false optional boolean with default of false",
   "message_id": "message-id. Optional reported message id"
}

成功した応答にはHTTPステータス200があり、「エラー」オブジェクトはありません。

失敗した場合の応答は次のようになります。

{  
    "errors": [
        {
            "code": 2048,
            "title": "Not engaged contact",
            "details": "Invalid Request. This contact hasn't engaged with you in the last 24 hrs."
        }
    ]
}

パラメーター

/v1/contacts/{phone_number}/reportへのPOST呼び出しでは、次のパラメーターがサポートされています。