メッセージ送信 API

メッセージ送信APIを使用することで、WhatsAppのメッセージ機能をビジネスシステムに統合できます。
APIを呼び出す前に、コンソールのAPIキーページでキーを作成してください。

エンドポイント

POST https://wa.api.engagelab.cc/v1/messages

認証

EngageLab REST APIはHTTPベーシック認証を使用します：HTTPヘッダーにAuthorizationを追加してください：

Authorization: Basic ${base64_auth_string}

              
              Authorization: Basic ${base64_auth_string}

このコードブロックはフローティングウィンドウ内に表示されます

上記のbase64_auth_stringの生成アルゴリズムは次の通りです：base64(dev_key:dev_secret)

ヘッダー名は"Authorization"で、値はbase64エンコードされた"username:password"ペア（コロンで区切る）です。
WhatsApp APIのシナリオでは、usernameはDevKey、passwordはDevSecretです。これらはコンソールの構成管理-APIキーページで取得してください。

リクエスト例

リクエストヘッダー

POST /v1/messages HTTP/1.1 Content-Type: application/json Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0

              
              POST /v1/messages  
HTTP/1.1  Content-Type: application/json  
Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0

このコードブロックはフローティングウィンドウ内に表示されます

リクエストボディ

{ "from": "+8613800138000", "to": [ "00447911123456" ], "body": { "type": "template", "template": { "name": "code", "language": "zh_CN", "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "12345" } ] } ] } }, "request_id": "123asdbbqwe9faweg", "custom_args": { "arg1": "string val", "arg2": 123 } }

              
               {
    "from": "+8613800138000",
    "to": [
        "00447911123456"
    ],
    "body": {
        "type": "template",
        "template": {
            "name": "code",
            "language": "zh_CN",
            "components": [
                {
                    "type": "body",
                    "parameters": [
                        {
                            "type": "text",
                            "text": "12345"
                        }
                    ]
                }
            ]
        }
    },
    "request_id": "123asdbbqwe9faweg",
    "custom_args": {
        "arg1": "string val",
        "arg2": 123
    }
}

このコードブロックはフローティングウィンドウ内に表示されます

リクエストパラメータ

リクエストオブジェクトはJSON形式で表現されるため、リクエストヘッダーにはContent-Type: application/jsonを含める必要があります。

パラメータ	型	必須	説明
from	String	任意	送信者の番号
to	String Array	必須	受信者の電話番号
body	JSON Object	必須	メッセージ本文
request_id	String	任意	リクエストを識別するためのカスタムリクエストID。レスポンスで返されます。
custom_args	JSON Object	任意	メッセージステータスコールバックで開発者に返されるカスタム情報。

from

パラメータ	型	必須	説明
from	String	任意	送信者の番号、つまりメッセージ送信に使用するビジネス電話番号。国際コードを含める必要があります。指定しない場合、デフォルトの送信者番号が使用されます（コンソールで構成する必要があります）。

to

パラメータ	型	必須	説明
to	String Array	必須	受信者のWhatsApp電話番号。国際コードを含める必要があります。

body

以下のフィールドを含むメッセージ本文：

パラメータ	型	必須	説明
type	string	必須	メッセージタイプ。現在サポートされているタイプ： template: テンプレートメッセージ text: テキストメッセージ image: 画像メッセージ audio: 音声メッセージ video: 動画メッセージ document: ドキュメントメッセージ sticker: ステッカーメッセージテンプレートメッセージのみユーザーに積極的に送信できます。他のメッセージタイプは、ユーザーが24時間以内に返信した場合にのみ送信可能です。画像/音声/動画/ドキュメント/ステッカーはすべてメディアメッセージであり、メディアメッセージ形式要件を遵守してください。
template	template object	任意	type=templateの場合に使用。詳細はtemplate objectの説明を参照してください。
text	text object	任意	type=textの場合に使用。詳細はtext objectの説明を参照してください。
image	image object	任意	type=imageの場合に使用。詳細はimage objectの説明を参照してください。
audio	audio object	任意	type=audioの場合に使用。詳細はaudio objectの説明を参照してください。
video	video object	任意	type=videoの場合に使用。詳細はvideo objectの説明を参照してください。
document	document object	任意	type=documentの場合に使用。詳細はdocument objectの説明を参照してください。
sticker	sticker object	任意	type=stickerの場合に使用。詳細はsticker objectの説明を参照してください。

text objectの説明

テキストメッセージ

パラメータ	型	必須	説明
body	String	必須	テキスト内容。WhatsAppでは4096文字以内である必要があります。

例

{ "from": "8613800138000", //送信者の電話番号 "to": ["8613800138000"], //受信者の電話番号 "body": { "type": "text", //メッセージタイプ "text": { "body": "your-text-message-content" //メッセージ内容 } } }

              
              {
    "from": "8613800138000", //送信者の電話番号
    "to": ["8613800138000"], //受信者の電話番号
    "body": {
        "type": "text", //メッセージタイプ
        "text": {
            "body": "your-text-message-content" //メッセージ内容
        }
    }
}

このコードブロックはフローティングウィンドウ内に表示されます

image objectの説明

画像メッセージ

パラメータ	型	必須	説明
id	String	任意	WhatsAppが生成したmedia_id。idまたはlinkのいずれかに値が必要です。
link	String	任意	画像リンク。http/httpsリンク。メディアメッセージ形式要件を遵守してください。
caption	String	任意	画像の説明。最大1024文字まで。

例

{ "from": "8613800138000",//送信者の電話番号 "to": ["8613800138000"], //受信者の電話番号 "body": { "type": "image",//メッセージタイプ "image": { "link": "https://img.jiguang.cn/jiguang/public/img/c866bd2.png", //画像リンク "caption": "caption info" // 任意、画像下のテキスト説明。最大1024文字 } } }

              
              {
    "from": "8613800138000",//送信者の電話番号
    "to": ["8613800138000"], //受信者の電話番号
    "body": {			
            "type": "image",//メッセージタイプ
            "image": {
                "link": "https://img.jiguang.cn/jiguang/public/img/c866bd2.png", //画像リンク
        "caption": "caption info"   // 任意、画像下のテキスト説明。最大1024文字
            }
    }
}

このコードブロックはフローティングウィンドウ内に表示されます

video objectの説明

動画メッセージ

パラメータ	型	必須	説明
id	String	任意	WhatsAppが生成したmedia_id。idまたはlinkのいずれかに値が必要です。
link	String	任意	動画リンク。http/httpsリンク。メディアメッセージ形式要件を遵守してください。
caption	String	任意	動画の説明。最大1024文字まで。

例

{ "from": "8613800138000",//送信者の電話番号 "to": ["8613800138000"], //受信者の電話番号 "body": { "type": "video",//メッセージタイプ "video": { "link": "https://img.jiguang.cn/jiguang/public/videos/432acc5.mp4", //動画リンク "caption": "caption info" // 任意、動画下のテキスト説明。最大1024文字 } } }

              
              {
    "from": "8613800138000",//送信者の電話番号
    "to": ["8613800138000"], //受信者の電話番号
    "body": {			
            "type": "video",//メッセージタイプ
            "video": {
                "link": "https://img.jiguang.cn/jiguang/public/videos/432acc5.mp4", //動画リンク
        "caption": "caption info"   // 任意、動画下のテキスト説明。最大1024文字
            }
    }
}

このコードブロックはフローティングウィンドウ内に表示されます

audio objectの説明

音声メッセージ

パラメータ	型	必須	説明
id	String	任意	WhatsAppが生成したmedia_id。idまたはlinkのいずれかに値が必要です。
link	String	任意	音声リンク。http/httpsリンク。メディアメッセージ形式要件を遵守してください。

例

{ "from": "8613800138000",//送信者の電話番号 "to": ["8613800138000"], //受信者の電話番号 "body": { "type": "audio",//メッセージタイプ "audio": { "link": "https://file-examples.com/storage/fe5947fd2362fc197a3c2df/2017/11/file_example_MP3_700KB.mp3" //音声リンク } } }

              
              {
    "from": "8613800138000",//送信者の電話番号
    "to": ["8613800138000"], //受信者の電話番号
    "body": {
            "type": "audio",//メッセージタイプ
            "audio": {
                "link": "https://file-examples.com/storage/fe5947fd2362fc197a3c2df/2017/11/file_example_MP3_700KB.mp3" //音声リンク
            }
    }
}

このコードブロックはフローティングウィンドウ内に表示されます

document objectの説明

ドキュメントメッセージ

パラメータ	型	必須	説明
id	String	任意	WhatsAppが生成したmedia_id。idまたはlinkのいずれかに値が必要です。
link	String	任意	ドキュメントリンク。http/httpsリンク。メディアメッセージ形式要件を遵守してください。
caption	String	任意	ドキュメントの説明。最大1024文字まで。
filename	String	任意	ファイル名。`filename`フィールドが指定されていないが`caption`フィールドがある場合、`caption`がファイル名として使用されます。`filename`が指定されている場合、その値がファイル名として使用されます。

例

{ "from": "8613800138000",//送信者の電話番号 "to": ["8613800138000"], //受信者の電話番号 "body": { "type": "document",//メッセージタイプ "document": { "link": "https://img.jiguang.cn/jiguang/public/videos/432acc5.mp4", //ドキュメントリンク "caption": "caption info", // 任意、ドキュメント下のテキスト説明。最大1024文字 "filename": "document file name" // 任意、ファイル名 } } }

              
              {
    "from": "8613800138000",//送信者の電話番号
    "to": ["8613800138000"], //受信者の電話番号
    "body": {
            "type": "document",//メッセージタイプ
            "document": {
                "link": "https://img.jiguang.cn/jiguang/public/videos/432acc5.mp4", //ドキュメントリンク
        "caption": "caption info",   // 任意、ドキュメント下のテキスト説明。最大1024文字
        "filename": "document file name"    // 任意、ファイル名
            }
    }
}

このコードブロックはフローティングウィンドウ内に表示されます

sticker objectの説明

ステッカーメッセージ

パラメータ	型	必須	説明
id	String	任意	WhatsAppが生成したmedia_id。idまたはlinkのいずれかに値が必要です。
link	String	任意	ステッカーリンク。http/httpsリンク。メディアメッセージ形式要件を遵守してください。

例

{ "from": "8613800138000",//送信者の電話番号 "to": ["8613800138000"], //受信者の電話番号 "body": { "type": "sticker",//メッセージタイプ "sticker": { "link": "http://sample-file.bazadanni.com/download/images/webp/sample.webp" //ステッカーリンク } } }

              
              {
    "from": "8613800138000",//送信者の電話番号
    "to": ["8613800138000"], //受信者の電話番号
    "body": {
            "type": "sticker",//メッセージタイプ
            "sticker": {
                "link": "http://sample-file.bazadanni.com/download/images/webp/sample.webp" //ステッカーリンク
            }
    }
}

このコードブロックはフローティングウィンドウ内に表示されます

template オブジェクトの説明

テンプレートメッセージを送信するには、まずテンプレートを作成する必要があります。コンソール操作またはAPI 呼び出しによる作成を使用して作成できます。

パラメーター	タイプ	必須	説明
name	String	必須	テンプレート名。コンソールのメッセージテンプレートページで確認でき、小文字、数字、アンダースコアのみがサポートされています。
language	String	必須	テンプレートの言語コード。テンプレート作成時に、同じテンプレート名に対して複数の言語を設定できます。そのため、送信時にはnameフィールドとlanguageフィールドを組み合わせて選択したテンプレートを特定する必要があります。
components	components-object array	任意	テンプレートに変数が含まれている場合、このフィールドを入力する必要があります。配列内に1つのcomponentsオブジェクト要素を設定するだけで十分です。

template.components オブジェクトの説明

パラメーター	タイプ	オプション	説明
type	String	必須	テンプレートコンポーネント。変数を含むテンプレート内のコンポーネントには値を割り当てる必要があります。可能な値： header: ヘッダー body: 本文 footer: フッター button: ボタン
parameters	parameters オブジェクト	必須	変数の内容を設定します。

template.components.parameters オブジェクトの説明

パラメーター	タイプ	オプション	説明
type	string	必須	変数内容のタイプ。可能な値：text, currency, date_time, image, video, document。マルチメディアタイプ（image, video, document）はヘッダーでのみ利用可能です。サポートされる形式についてはメディアメッセージ形式要件を参照してください。
text	string	任意	type=textの場合に使用され、変数の内容を指定します。
date_time	localizable オブジェクト	任意	type=date_timeの場合に使用され、textとは異なりローカライズされた表示をサポートします。
currency	localizable オブジェクト	任意	type=currencyの場合に使用され、textとは異なりローカライズされた表示をサポートします。
image	image オブジェクト	任意	type=imageの場合に使用され、image オブジェクト形式と一致します。
video	video オブジェクト	任意	type=videoの場合に使用され、video オブジェクト形式と一致します。
document	document オブジェクト	任意	type=documentの場合に使用され、document オブジェクト形式と一致します。

例

{ "from": "+8613800138000", "to": [ "00447911123456" ], "body": { "type": "template", "template": { "name": "your-template-name", "language": "zh_CN", "components": [ { "type" : "header", "parameters": [{ "type": "document", "document": { "link": "http(s)://the-url", "filename": "your-document-filename" } }] }, { "type": "body", "parameters": [ { "type": "text", "text": "your-text-string" }, { "type": "currency", "currency": { "fallback_value": "$100.99", "code": "USD", "amount_1000": 100990 } }, { "type": "date_time", "date_time": { "fallback_value": "February 25, 1977", "day_of_week": 5, "day_of_month": 25, "year": 1977, "month": 2, "hour": 15, "minute": 33 } }, { "type": "date_time", "date_time": { "fallback_value": "February 25, 1977", "timestamp": 1485470276 } } ] } ] } } }

              
              {
    "from": "+8613800138000",
    "to": [
        "00447911123456"
    ],
    "body": {
        "type": "template",
        "template": {          
            "name": "your-template-name",
                        "language": "zh_CN",
            "components": [
              {
                "type" : "header",
                "parameters": [{
                         "type": "document",
                         "document": {
                             "link": "http(s)://the-url",
                             "filename": "your-document-filename"
                       }
                }]
              },
              {
                 "type": "body",
                 "parameters": [
                        {
                            "type": "text",
                            "text": "your-text-string"
                        },
                        {
                            "type": "currency",
                            "currency": {
                                "fallback_value": "$100.99",
                                "code": "USD",
                                "amount_1000": 100990
                            }
                        },
                        {
                            "type": "date_time",
                            "date_time": {
                                "fallback_value": "February 25, 1977",
                                "day_of_week": 5,
                                "day_of_month": 25,
                                "year": 1977,
                                "month": 2,
                                "hour": 15,
                                "minute": 33
                            }
                        },
                        {
                            "type": "date_time",
                            "date_time": {
                                "fallback_value": "February 25, 1977",
                                "timestamp": 1485470276
                            }
                        }
                    ]
                }
            ]
        }
    }
}

このコードブロックはフローティングウィンドウ内に表示されます

認証カテゴリの特別な注意事項

認証カテゴリ（カテゴリがAUTHENTICATION）のテンプレートメッセージについては、WhatsAppの最新ルール（2023/06/01）に基づき、認証カテゴリでテンプレートを作成/編集する際に送信されるテンプレートフィールドが、WhatsApp側で生成される最終的なテンプレートフィールドと一致しません（テンプレート作成/編集APIドキュメントを参照）。そのため、認証カテゴリのテンプレートメッセージを送信する場合、BODY内の変数を渡すだけでなく、BUTTON内にも変数を渡し、変数値を一致させる必要があります。

{ "from": "+8613800138000", "to": [ "00447911123456" ], "body": { "type": "template", "template": { "name": "your-template-name", "language": "zh_CN", "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "123456" } ] }, // ボタン変数値を追加します。本質的に、テンプレートのボタンは変数を含むURLタイプになります。 { "type": "button", "sub_type": "url", "index": 0, "parameters": [ { "type": "text", "text": "123456"//認証コードの具体的なコード値 } ] } ] } } }

              
              {
    "from": "+8613800138000",
    "to": [
        "00447911123456"
    ],
    "body": {
        "type": "template",
        "template": {          
            "name": "your-template-name",
                        "language": "zh_CN",
            "components": [
              {
                 "type": "body",
                 "parameters": [
                        {
                            "type": "text",
                            "text": "123456"
                        }
                  ]
              },
              // ボタン変数値を追加します。本質的に、テンプレートのボタンは変数を含むURLタイプになります。
              {			
                 "type": "button",
                 "sub_type": "url",
                 "index": 0,
                 "parameters": [
                        {
                            "type": "text",
                            "text": "123456"//認証コードの具体的なコード値
                        }
                  ]
              }
            ]
        }
    }
}

このコードブロックはフローティングウィンドウ内に表示されます

レスポンスパラメーター

成功レスポンス

フィールド	タイプ	オプション	説明
message_id	String	必須	EngageLab WhatsAppメッセージID。メッセージを一意に識別します。
request_id	String	任意	リクエスト中に送信されたカスタムID。レスポンスでそのまま返されます。

{ "message_id": "cbggf4if6o9ukqaalfug", "request_id": "your-sendno-string" }

              
              {
    "message_id": "cbggf4if6o9ukqaalfug",
    "request_id": "your-sendno-string"
}

このコードブロックはフローティングウィンドウ内に表示されます

失敗レスポンス

HTTPステータスコードが4xxまたは5xxで、レスポンスボディに以下のフィールドが含まれます：

フィールド	タイプ	オプション	説明
code	int	必須	エラーコード。エラーコードを参照してください。
message	String	必須	エラーの詳細。

{ "code": 3002, "message": "whatsapp.template field must be set correctly when type is template" }

              
              {
    "code": 3002,
    "message": "whatsapp.template field must be set correctly when type is template"
}

このコードブロックはフローティングウィンドウ内に表示されます

エラーコード

エラーコード	HTTPコード	説明
1000	500	内部エラー
2001	401	EngageLab認証に失敗しました。有効なトークン形式が提供されていません。
2002	401	EngageLab認証に失敗しました。トークンが期限切れまたは無効化されています。
2003	400	WhatsApp認証に失敗しました。EngageLabサポートに連絡してください。
2004	403	このAPIを呼び出す権限がありません。APIキーがメッセージ送信API（特定の送信番号）に対して承認されているか確認してください。
3001	400	リクエストパラメーター形式が無効です。JSON形式が使用されているか確認してください。
3002	400	リクエストパラメーターエラー。リクエストパラメーターが要件を満たしているか確認してください。
3003	400	リクエストパラメーターエラー。関連するビジネス検証に失敗しました。メッセージフィールドのエラー説明を参照してください。
4001	400	関連するリソースが存在しません。例えば、テンプレートメッセージ送信時に存在しないテンプレートを使用した場合など。

注意事項

メディアメッセージ形式要件

メディアタイプ	サポートされる形式タイプ Content-Type	サイズ制限
image	image/jpeg, image/png。透明な背景はサポートされていません。	5 MB
video	video/mp4, video/3gpp 注意：H.264ビデオエンコーディングとAACオーディオエンコーディングのみサポートされています。	16MB
audio	audio/aac, audio/mp4, audio/amr, audio/mpeg, audio/ogg; codecs=opus（注意：基本的なaudio/oggはサポートされておらず、audio/ogg; codecs=opusのみサポートされています。）	16MB
document	1. ファイルメッセージ送信時には、任意のMIMEタイプがサポートされています。 2. テンプレートメッセージ送信時には、ヘッダーでのみPDF形式がサポートされています。	100 MB
sticker	image/webp	静的ステッカー：100KB アニメーションステッカー：500KB 512x512ピクセル

言語コード

言語とそのコードの対応関係については、このファイルをダウンロードして参照してください：
テンプレート言語コード.xlsx