Webhook で届く Instagram ストーリーのメンションと返信
Instagram は、ストーリーのメンションと返信を messages Webhook フィールドの DM として配信します。メンションは、attachments に story_mention 型の項目を持つメッセージとして届き、ストーリーの CDN URL は payload.url に入ります。返信には本人のテキストと reply_to.story が含まれ、そこにストーリーの url と id、リンクステッカー付きのストーリーの場合は link_sticker_url が入ります。
easyCoexistence は、接続された各 Instagram アカウントを messages に登録するため、ストーリーのメンションと返信は、ほかの DM と一緒に届いた時点で HTTPS エンドポイントに届きます。
アカウントをストーリーでメンションしたときに Meta が送る messages イベントの添付タイプ。
2025 年 12 月 12 日に Meta が reply_to.story に追加したフィールドで、返信先ストーリーのリンクステッカー URL を保持します。
ストーリーの有効期間。期限切れまたは削除されると、メンションの URL は表示されなくなります。
ストーリーのメンションが届くアカウント。非公開アカウントのメンションは、プロフェッショナルアカウントをフォローしている場合に限り届きます。
Meta の Instagram Messaging ガイドによると、Webhook が対応していないストーリーへの返信。
ストーリーのメンションはどのように届きますか?
DM として届きます。ユーザーがストーリーでプロフェッショナルアカウントをメンションすると、Instagram はそのストーリーを参照するメッセージをアカウントの受信箱に入れ、Meta がそれに対して messages イベントを送信します。sender.id は本人の Instagram スコープ ID で、message.attachments には story_mention 型の項目が 1 つ入っており、その payload.url がストーリーの CDN URL です。Meta のサンプルにはテキストがないため、添付を読み取ってください:
{
"object": "instagram",
"entry": [
{
"id": "<IG_ID>",
"time": 1793448000512,
"messaging": [
{
"sender": { "id": "<IGSID>" },
"recipient": { "id": "<IG_ID>" },
"timestamp": 1793447999874,
"message": {
"mid": "<MESSAGE_ID>",
"attachments": [
{
"type": "story_mention",
"payload": { "url": "<CDN_URL>" }
}
]
}
}
]
}
]
}ストーリーへの返信はどのように届きますか?
こちらも DM として届き、本人のメッセージと、アカウントのストーリーを指す reply_to オブジェクトが含まれます。reply_to.story にはストーリーの CDN url と id が入ります。Meta の Webhook リファレンスには、2025 年 12 月に追加された link_sticker_url も記載されています。これはリンクステッカー付きのストーリーへの返信で使われ、リンクごとに自動化を振り分ける用途に Meta が推奨しています。以前のメッセージへのインライン返信では、代わりに reply_to.mid を使います。
"message": {
"mid": "<MESSAGE_ID>",
"text": "<MESSAGE_TEXT>",
"reply_to": {
"story": {
"url": "<CDN_URL>",
"id": "<STORY_ID>"
}
}
}各フィールドは何を意味しますか?
Meta がこの 2 つのイベントについて文書化しているフィールドを、外側から順に示します:
- entry[].id と recipient.id:プロフェッショナルアカウント。sender.id:本人の Instagram スコープ ID で、返信の宛先になる ID。
- timestamp:メッセージが送信された時刻で、Meta のサンプルではミリ秒単位です。entry[].time は Meta が通知を送信した時刻です。
- message.mid:メッセージ ID。再送の重複排除と、
reply_to.mid を使った返信に使います。 - attachments[].type
story_mentionと payload.url:メンションと、そのメンションを行ったストーリーの CDN URL。 reply_to.story.url とreply_to.story.id:本人が返信したアカウントのストーリー。reply_to.story.link_sticker_url:そのストーリーのリンクステッカーの URL。- message.text:返信の本文。メッセージにテキストが含まれる場合に入ります。
ストーリーの URL はいつまで使えますか?
ストーリーが有効な間は使えます。ストーリーは 24 時間後、または作成者が削除すると消えます。Meta のストーリーメンションガイドによると、その時点で URL は表示されなくなります。概要には、Instagram の CDN URL はプライバシーに配慮した仕様で、削除済みまたは期限切れのコンテンツには何も返さないとあります。同じガイドでは、CDN URL の保存は認められていますが、メディアの保存は認められていません。アプリはストーリーの内容をサーバーに保存もキャッシュもしてはならず、ストーリーがなくなったらプレースホルダーを表示すべきとされています。
どちらのイベントも発火しないのはどんな場合ですか?
Meta のガイドには、ストーリーのイベントを待つハンドラーが何も受け取らないケースが挙げられています:
- プロフェッショナルアカウントをフォローしていない非公開アカウントによるストーリーのメンション。
- 通常の投稿へのタグ付け。Meta によると、messages Webhook を発火させるのはストーリーのメンションだけで、投稿へのタグ付けは対象外です。
- GIF またはステッカーを使ったストーリーへの返信。Webhook は対応していません。
- メンション API 経由のストーリー。GET /<
IG_ID>/tags と POST /<IG_ID>/mentions は対応していないため、ストーリーのメンションは DM で届きます。
ストーリーのメンションと返信はメッセージングウィンドウを開きますか?
返信は本人からのメッセージであり、Meta は本人が会話を始める経路としてストーリーのメンションを挙げています。本人の操作によって開くウィンドウは、ほとんどの操作で 24 時間続きます。その間、アカウントは recipient.id にイベントの sender.id を設定して POST /<IG_ID>/messages で返信できます。アカウントの返信は is_echo が true の状態で messages に戻ってきます。
easyCoexistence はどのように転送しますか?
messages フィールドで転送します。接続された各アカウントはこのフィールドに登録されているため、ストーリーのメンションと返信は、アカウントのほかの DM と一緒にエンドポイントに届きます。各エントリーは platform、account_id、external_id、entry からなるエンベロープに入り、アカウントのシークレットで X-EC-Signature に署名されて、1 回だけ送信されます。コピーは保存されません。send_social_dm は、イベントの sender.id を recipient_id として本人に返信し、24 時間のウィンドウ内で送信されます。
POST <YOUR_ENDPOINT>
Content-Type: application/json
X-EC-Signature: t=1793448001,v1=<HEX_HMAC_SHA256>
{
"platform": "instagram",
"account_id": "<ACCOUNT_ID>",
"external_id": "<IG_ID>",
"entry": {
"id": "<IG_ID>",
"time": 1793448000512,
"messaging": [
{
"sender": { "id": "<IGSID>" },
"recipient": { "id": "<IG_ID>" },
"timestamp": 1793447999874,
"message": {
"mid": "<MESSAGE_ID>",
"attachments": [
{ "type": "story_mention", "payload": { "url": "<CDN_URL>" } }
]
}
}
]
}
}よくある間違い
- ストーリーのメディアを保存すること。Meta のストーリーメンションガイドは CDN URL の保存を認めていますが、コンテンツの保存は認めていません。コンテンツはサーバーに保存もキャッシュもしてはなりません。
- message.text だけを読むこと。ストーリーのメンションは story_mention 型の添付を持ち、Meta のサンプルではテキストがないため、テキストのみを扱うハンドラーには空のメッセージとして見えます。
- 数日後にストーリーの URL を表示すること。ストーリーは 24 時間後に期限切れになるか削除されると機能しなくなるため、それ以降はプレースホルダーを表示してください。
- ストーリーのメンションを comments フィールドやメンション API で探すこと。Meta はこれを messages の DM として配信します。
アカウントのシークレットで署名され、コピーは保存されません。send_social_dm は、24 時間のウィンドウ内で Claude、ChatGPT、または独自のコードから本人に返信します。料金は接続 1 件あたり月額 US$ 9 から US$ 0.75 まで、接続を増やすほど下がります。最初の 3 日間は無料トライアルです。
よくある質問
Instagram のストーリーメンションのイベントにテキストは含まれますか?
Meta のサンプルでは含まれません。ストーリーのメンションは、ストーリーの CDN URL を持つ story_mention 型の添付を含むため、message.text だけを読むハンドラーには空のメッセージとして見えます。
Instagram ストーリーの返信にある link_sticker_url とは何ですか?
本人が返信したストーリーのリンクステッカーの URL で、reply_to.story.link_sticker_url に入ります。Meta は 2025 年 12 月 12 日に追加し、リンクごとに自動化を振り分ける用途を推奨しています。
GIF やステッカーによるストーリーへの返信は Webhook を発火させますか?
いいえ。Meta の Instagram Messaging ガイドによると、GIF またはステッカーで行われたストーリーへの返信には Webhook が対応していません。
非公開アカウントはストーリーのメンション Webhook を発火させますか?
プロフェッショナルアカウントをフォローしている場合に限ります。公開アカウントからのメンションは、発生したとおりに届きます。
続きを読む
最初のチャンネルを 2 分で接続しましょう。
プラットフォームの審査を待つ必要はありません。WhatsApp、Instagram、TikTok などのチャンネルを接続して、AI に投稿、返信、レポートを任せてみてください。
- 3 日間無料
- いつでも解約可能
- 公式 API のみ使用
- 24/7 監視
確認日