メッセージ

/v1/messages

messagesノードを使って、テキストメッセージ、メディアメッセージ、連絡先メッセージ、位置情報メッセージ、インタラクティブメッセージ、ならびにメッセージテンプレートをカスタマーに送信します。

送信可能なメッセージの具体的な種類については、テキストメッセージ、メディアメッセージ、連絡先メッセージと位置情報メッセージ、インタラクティブメッセージ、メッセージテンプレート、メディアメッセージテンプレート、インタラクティブメッセージテンプレートのガイドをご覧ください。

開始する前に

以下のことが必要です。

• 自身を認証し、サービスにアクセスできるようになるための認証トークンを受け取る。詳しい方法については、ログインと認証に関するドキュメントをご覧ください。
• メッセージを送信するWhatsAppアカウントを認証し、そのWhatsAppユーザーIDを取得する。詳しい方法については、連絡先に関するドキュメントをご覧ください。
• メッセージのカットオフ制御サービス条件を満たす。

制約

• メッセージの種類としては、テキスト、メッセージテンプレート、画像、ドキュメント、および音声がサポートされています。
• テキストメッセージの長さは最大で4096文字です。

作成

メッセージを送信するには、メッセージの種類に関係なく、/messagesノードにPOST呼び出しを実行します。JSONメッセージ本文の内容は、メッセージの種類(テキストや画像など)によって異なります。

パラメーター

/messages POSTリクエストで使用される主なパラメーターは以下のとおりです。

テキストオブジェクト

メディアオブジェクト

オンプレミスAPIの場合、mediaエンドポイントを通じてメディアがWhatsApp Businessオンプレミス/リファレンスのクライアントへのアップロードが成功した場合に、メディアオブジェクトトIDが返されます。

連絡先オブジェクト

contactsの中には、addresses、emails、name、org、phone、urlsをオブジェクトとして入れ子にすることができます。複数化オブジェクトは、以下の例に示すように配列でラッピングされます。

複数化オブジェクトが中に含まれているcontactsのオブジェクトの例は次のとおりです。

"contacts": [
    {
        "addresses": [
            {
                "city": "city name",
                "country": "country name",
                "country_code": "code",
                "state": "Contact's State",
                "street": "Contact's Street",
                "type": "Contact's Address Type",
                "zip": "Contact's Zip Code"
            }
        ],
        "birthday": "birthday",
        "emails": [
            {
                "email": "email",
                "type": "HOME"
            },
            {
                "email": "email",
                "type": "WORK"
            }
        ],
        "name": {
            "first_name": "first name value",
            "formatted_name": "formatted name value",
            "last_name": "last name value",
            "suffix": "suffix value"
        },
        "org": {
            "company": "company name",
            "department": "dep name",
            "title": "title"
        },
        "phones": [
            {
                "phone": "Phone number",
                "wa-id": "WA-ID value",
                "type": "MAIN"
            },
            {
                "phone": "Phone number",
                "type": "HOME"
            },
            {
                "phone": "Phone number",
                "type": "WORK"
            }
        ],
        "urls": [{
            "url": "some url",
            "type": "WORK"
        }]
    }
]

位置情報オブジェクト

テンプレートオブジェクト

templateの中に、componentsとlanguageのオブジェクトをネストできます。

コンポーネントオブジェクト

componentsの中に、parametersオブジェクトをネストできます。さらに、typeをbuttonに設定することができます。

パラメーターオブジェクト

ボタンの型

componentsオブジェクトの中で、typeをbuttonに設定できます。ボタンのパラメーターは次のとおりです。

sub_typeがquick_replyのbuttonタイプの例:

 {
    "type": "button",
    "sub_type": "quick_reply",
    "index": 0,
    "parameters": 
     [{
    	"type": "payload",
    	"payload": "Yes-Button-Payload"
     }]
 } 

sub_typeがbuttonのcopy_codeタイプの例

    
 { 
    "type": "button", 
    "sub_type": "copy_code", 
    "index": 0, 
    "parameters": 
    [{ 
     "type": "coupon_code", 
     "coupon_code": "DISCOUNT20" 
    }] 
 }

Hsmオブジェクト

インタラクティブオブジェクト

アクションオブジェクト

例

音声メッセージ:

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "audio",
  "audio": {
      "id": "your-media-id",
  }
}

ドキュメントメッセージ、filenameを使用:

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "document",
  "document": {
      "id": "your-media-id",
      "filename": "your-document-filename"
  }
}

ドキュメントメッセージ、linkを使用:

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "document",
  "document": {
      "link": "http(s)://the-url"
      "provider": {
          "name" : "provider-name"
      }     
    }
}

動画メッセージ、linkを使用:

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "video",  
  "video": {
      "link": "http(s)://the-url"
      "provider": {
          "name" : "provider-name"
      }
    }
  }
}

テキストメッセージ:

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "text",
  "text": {
      "body": "your-message-content"
  }
}

インタラクティブメッセージ(リスト):

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "interactive",
  "interactive":{
    "type": "list",
    "header": {
      "type": "text",
      "text": "your-header-content-here"
    },
    "body": {
      "text": "your-text-message-content-here"
    },
    "footer": {
      "text": "your-footer-content-here"
    },
    "action": {
      "button": "cta-button-content-here",
      "sections":[
        {
          "title":"your-section-title-content-here",
          "rows": [
            {
              "id":"unique-row-identifier-here",
              "title": "row-title-content-here",
              "description": "row-description-content-here",           
            }
          ]
        },
        {
          "title":"your-section-title-content-here",
          "rows": [
            {
              "id":"unique-row-identifier-here",
              "title": "row-title-content-here",
              "description": "row-description-content-here",           
            }
          ]
        },
        ...
      ]
    }
  }

}

インタラクティブメッセージ(返信ボタン):

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "header": { # optional
      "type": "text" | "image" | "video" | "document",
      "text": "your text"
      # OR
      "document": {
        "id": "your-media-id",
        "filename": "some-file-name"
      }
      # OR
      "document": {
        "link": "the-provider-name/protocol://the-url",
        "provider": {
          "name": "provider-name",
        },
        "filename": "some-file-name"
      },
      # OR
      "video": {
        "id": "your-media-id"
      }
      # OR
      "video": {
        "link": "the-provider-name/protocol://the-url",
        "provider": {
          "name": "provider-name"
        }
      }
      # OR
      "image": {
        "id": "your-media-id"
      }
      # OR
      "image": {
        "link": "http(s)://the-url",
        "provider": {
          "name": "provider-name"
        }
      }
    }, # end header
    "body": {
      "text": "your-text-body-content"
    },
    "footer": { # optional
      "text": "your-text-footer-content"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "unique-postback-id",
            "title": "First Button’s Title" 
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "unique-postback-id",
            "title": "Second Button’s Title" 
          }
        }
      ] 
    } # end action   
  } # end interactive

}

インタラクティブメッセージ(複数商品メッセージと単一商品メッセージ):

{ 
  "recipient_type": "individual",
  "to" : "{{Recipient-WA-ID}}",
  "type": "interactive",
  "interactive": {
    "type": "product",
    "body": {
      "text": "body text"
    },
    "footer": {
      "text": "footer text"
    },
    "action": {
      "catalog_id": "catalog-ID",
      "product_retailer_id": "product-ID"
    }
  }
}

インタラクティブメッセージ(複数商品メッセージ):

{ 
  "recipient_type": "individual",
  "to" : "whatsapp-id",
  "type": "interactive",
  "interactive": 
    {
    "type": "product_list",
    "Header":{
       "type": "text",
        "text": "text-header-content"
     },
     "body":{
        "text": "text-body-content"
      },
     "footer":{
        "text":"text-footer-content"
     },
     "action":{
        "catalog_id":"catalog-id",
        "sections": [
             {
             "title": "section-title",             
             "product_items": [
                  { "product_retailer_id": "product-SKU-in-catalog" },
                  { "product_retailer_id": "product-SKU-in-catalog" },
                            ...
              ]},
              {
              "title": "the-section-title",
              "product_items": [
                 { "product_retailer_id": "product-SKU-in-catalog" }
                           ...
              ]},
               ...
       ]
     },  
    }
}

応答のpayloadの例を以下に示します。簡略化のため、メタオブジェクトとエラーオブジェクトは省略しています。

{
  "messages": [{ 
    "id": "message-id" 
  }]    
}

リクエストが成功すると、メッセージIDを含む応答が返されます。リクエストがerrorsセクションを返した場合は、送信したメッセージを確認して、エラーを修正してから、リクエストを再送してください。エラーについて詳しくは、WhatsApp Businessオンプレミス/リファレンスのクライアントのエラーコードとHTTPステータスコードをご覧ください。

品質評価のためにリクエストが保留になっている場合、message_statusプロパティが応答に含まれます。このプロパティから、メッセージがすぐには送信されず、品質確認後に送信またはドロップされることがわかります。このプロパティが存在するのはメッセージが保留されている場合だけです。

    {
      "messages": [{ 
        "id": "message-id",
        "message_status": "Message has been held because quality assessment is pending",
      }]    
    }
    

テキストメッセージの書式設定

WhatsAppでは一部メッセージの書式設定ができます。次の書式設定記号を使ってメッセージの一部、または全体の書式を設定します。

パフォーマンス

このコンテキストにおけるパフォーマンスとは、WhatsApp Businessオンプレミス/リファレンスクライアントを使用して特定の1秒間で送信できるメッセージの数を表します。どこまで高いパフォーマンスを達成できるかは、さまざまな要素に応じて異なります。最も重要な要素はクライアント設定の選択、およびメッセージ送信先が新規ユーザーかそれとも既存ユーザーかという点です。暗号化セッションの設定の場合、新規ユーザーとのメッセージングにかかる時間が多少長くなります。

よくある質問

詳しくはこちら

• ログインと認証のドキュメント
• 連絡先に関するドキュメント
• WhatsApp Businessオンプレミス/リファレンスのクライアントのエラーコード
• HTTPステータスコード