Instagram messaging_postbacks webhook: アイスブレイカーとボタン
Instagram の messaging_postbacks Webhook フィールドは、プロフェッショナルアカウントとの会話でユーザーがアイスブレイカーの質問、ボタンテンプレート内のポストバックボタン、または固定メニュー項目をタップした時に、アプリへ通知します。postback オブジェクトには、ユーザーがタップしたテキストである title、そのオプションにアプリが設定した文字列である payload、そして Graph API v11.0 からのメッセージ ID である mid が含まれます。
easyCoexistence は、接続された各 Instagram アカウントをコメント、メッセージ、メンションに登録し、クイックリプライのタップを含むそれらのイベントを、到着次第そのアカウントのシークレットで署名して HTTPS エンドポイントに転送します。
Meta の Ice Breaker API でアカウントが設定できるアイスブレイカーの質問の最大数。
postback イベントに mid が含まれ始める Graph API のバージョンです。フィールド自体は v8.0 以降が必要です。
1 つのボタンテンプレートメッセージに含められるボタンの最大数。各ボタンはポストバックボタンか web_url ボタンです。
固定メニュー項目をユーザーがタップしてから返信できる時間。標準のメッセージングウィンドウが開きます。
1 つのメッセージが提示できるクイックリプライの最大数。タップされたクイックリプライは messages に届き、messaging_postbacks には届きません。
messaging_postbacks はいつ発生しますか?
アプリとアカウントがこのフィールドに登録されている場合、ユーザーが会話内でアカウントの構造化されたオプションのいずれかをタップした時に発生します。Meta のガイドでは、そのソースとして次を挙げています:
- アイスブレイカーの質問:会話の開始時にアカウントが提示する最大 4 件のいずれか。デスクトップでは利用できません。
- ボタンテンプレートのポストバックボタン(1 メッセージあたり最大 3 件)、またはジェネリックテンプレートのポストバックボタン(1 要素あたり最大 3 件)。
- アカウントの固定メニューにあるポストバック項目。
- ig.me リンクの ref パラメータ付きで開かれた新しいスレッドでタップされたアイスブレイカー。この場合、ポストバックには referral も含まれます。
- セルフメッセージのテストで、アカウントが自分のボタンをタップした場合。イベントには
is_selfが true として追加されます。
ポストバック通知はどのような形式ですか?
ポストバックオブジェクトを含むメッセージングイベントで、通常の DM ならメッセージが入る位置にあります。Meta の Instagram Login の例では mid、title、payload が含まれ、アイスブレイカーのガイドでは mid を除いた同じオブジェクトが示されています。通知は次のとおりです:
{
"object": "instagram",
"entry": [
{
"id": "<IG_ID>",
"time": 1793448000512,
"messaging": [
{
"sender": { "id": "<IGSID>" },
"recipient": { "id": "<IG_ID>" },
"timestamp": 1793447999874,
"postback": {
"mid": "<MESSAGE_ID>",
"title": "<ICE_BREAKER_QUESTION_OR_BUTTON_TITLE>",
"payload": "<PAYLOAD_SET_FOR_THE_OPTION>"
}
}
]
}
]
}各フィールドの意味は何ですか?
Meta がポストバックについて文書化しているフィールドを、外側から順に示します:
- sender.id:タップしたユーザーの Instagram スコープ ID で、返信先となる ID。recipient.id と entry[].id:プロフェッショナルアカウント。
- timestamp:Meta のアイスブレイカーのガイドによる、ユーザーがタップした時刻。
- postback.title:ユーザーが見たアイスブレイカーの質問またはボタンのタイトル。
- postback.payload:作成時にアプリが選んで設定した、そのオプションの文字列。
- postback.mid:Graph API v11.0 から、タップによってアカウントに送られたメッセージの ID。
- postback.referral:ig.me リンクの ref パラメータ付きでスレッドが開かれた場合の ref、source、type。
is_self:セルフメッセージのテストでアカウントが自分のボタンをタップした場合、postback の横に true として設定されます。
アイスブレイカーはどのように設定しますか?
graph.instagram.com で POST /<IG_ID>/messenger_profile を使います。platform を instagram に設定し、ice_breakers 配列の call_to_actions に最大 4 件の質問とペイロードのペアを入れます。翻訳されたセットごとに locale を指定できます。GET /me/messenger_profile?fields=ice_breakers で一覧を取得し、fields を ice_breakers にした DELETE で削除できます。ここで選んだペイロードが、質問がタップされた時に messaging_postbacks で返されます。
POST https://graph.instagram.com/<IG_ID>/messenger_profile?access_token=<INSTAGRAM_USER_ACCESS_TOKEN>
Content-Type: application/json
{
"platform": "instagram",
"ice_breakers": [
{
"call_to_actions": [
{ "question": "<QUESTION_1>", "payload": "<PAYLOAD_1>" },
{ "question": "<QUESTION_2>", "payload": "<PAYLOAD_2>" }
]
}
]
}ポストバックボタンはどのように送信しますか?
アカウントが POST /<IG_ID>/messages で送るメッセージの中に含めます。ボタンテンプレートは最大 640 文字のテキストと 1~3 個のボタンを持ちます。ジェネリックテンプレートは最大 10 要素で、各要素に最大 3 個のボタンを持てます。type が postback のボタンは、タップされると messaging_postbacks にそのペイロードを返します。一方 web_url ボタンは、アプリ内ブラウザでページを開きます。messenger_profile で設定する固定メニューも、同じ 2 種類のタイプを取ります。
クイックリプライは messaging_postbacks を使いますか?
いいえ、messages に届きます。タップされたクイックリプライは、そのタイトルをメッセージとして会話に投稿し、messages イベントには text にそのタイトル、quick_reply.payload にそのオプションのペイロードが入ります。1 つのメッセージは最大 13 件のクイックリプライを、それぞれ最大 20 文字のプレーンテキストで提示できます。Instagram Messaging ガイドでは、アイスブレイカーとジェネリックテンプレートの選択も messages が報告する内容として挙げていますが、ペイロードのサンプルはありません。
タップでメッセージングウィンドウが開きますか?
固定メニューについては、Meta がそう述べています。メニュー項目のタップで標準のメッセージングウィンドウが開き、アカウントは 24 時間以内に返信できます。POST /<IG_ID>/messages で、recipient.id にポストバックの sender.id を指定して返信します。アカウントの返信は、is_echo が true に設定された echo として messages に戻ってきます。
easyCoexistence はポストバックを転送しますか?
転送されるのはクイックリプライのタップのみです。タップは messages に届き、easyCoexistence のアプリと接続された各アカウントは messages を購読しているため、quick_reply.payload とともにエンドポイントに届きます。アイスブレイカー、ボタン、メニューのタップは messaging_postbacks に届きますが、easyCoexistence はこれを購読していないため、転送されません。
よくある間違い
- クイックリプライを messaging_postbacks で待つこと。クイックリプライは messages に届き、タップされた選択肢の text の横に quick_reply.payload が入ります。
- postback.title で振り分けること。title はユーザーが見た文字列で、ロケールによって異なる場合があります。振り分けは、アプリが設定する payload で行ってください。
- 古い API バージョンで mid を期待すること。Meta が postback.mid を含めるのは Graph API v11.0 以降のみです。
- 4 件を超えるアイスブレイカーを設定すること、またはデスクトップでテストすること。Meta の Ice Breaker API は最大 4 件の質問を受け付け、この機能はデスクトップでは利用できません。
データのコピーは保持しません。send_social_dm は 24 時間のメッセージングウィンドウ内でユーザーに返信します。接続 1 件あたり月額 US$ 9 から、接続が増えるほど下がり US$ 0.75 まで。最初の 3 日間は無料トライアルです。
よくある質問
Instagram のアイスブレイカーのタップを報告する Webhook フィールドはどれですか?
messaging_postbacks です。postback オブジェクトには、質問が title として、そのために設定されたペイロードが payload として、さらに Graph API v11.0 以降の mid が含まれます。
Instagram アカウントはアイスブレイカーをいくつ持てますか?
最大 4 件の質問で、POST /<IG_ID>/messenger_profile と platform を instagram に設定して登録します。必要に応じてロケールごとに設定できます。
Instagram のポストバックにはどのように返信しますか?
POST /<IG_ID>/messages で、recipient.id にポストバックの sender.id を指定します。sender.id はタップしたユーザーの Instagram スコープ ID です。固定メニューをタップした後、Meta はアカウントに 24 時間以内の返信を認めています。
Instagram のポストバックは title と payload のどちらで振り分けるべきですか?
payload で振り分けてください。アプリがその選択肢に設定した文字列です。title はユーザーが見たテキストで、ロケールによって異なる場合があります。
続きを読む
最初のチャンネルを 2 分で接続しましょう。
プラットフォームの審査を待つ必要はありません。WhatsApp、Instagram、TikTok などのチャンネルを接続して、AI に投稿、返信、レポートを任せてみてください。
- 3 日間無料
- いつでも解約可能
- 公式 API のみ使用
- 24/7 監視
確認日