Instagram メッセージ Webhook:DM のペイロード、エコー、各フィールド
Instagram の messages Webhook フィールドは、プロフェッショナルアカウントの DM を届いた順に配信します。テキスト、添付ファイル、シェア、ストーリーへの返信、メンション、インライン返信、削除が対象です。各イベントは messaging 配列に入り、送信者の Instagram スコープ ID、受信者、タイムスタンプ、message オブジェクトを持ちます。アカウント自身が送ったメッセージも同じフィールドで届き、is_echo が true に設定されます。
easyCoexistence は、接続された各 Instagram アカウントを messages に登録し、その DM をエコーを含めて、届いた順に HTTPS エンドポイントへ転送します。
アカウント自身が送信したメッセージのイベントで、true に設定されます。
ほとんどのユーザー操作で開く標準のメッセージングウィンドウで、この期間内はアプリから相手に返信できます。
共有投稿の添付タイプです。旧 share タイプは 2026 年 2 月 1 日までサポートされていました。
誰かがストーリーでアカウントをメンションしたときに Meta が送る DM イベントの添付タイプです。
アカウント所有者が Instagram のダイレクトメッセージへのアクセスを無効にしている場合の、コード 200 配下のエラーサブコードです。
messages フィールドはいつトリガーされますか?
人がプロフェッショナルアカウントに DM を送ったときと、アカウントが DM を送ったときです。Meta の例とリファレンスでは、次のケースが挙げられており、いずれも message オブジェクトを持つ messaging イベントになります。
- テキストと、添付としてのメディア(画像、動画、音声、ファイル)。
- 共有された投稿やリール。
ig_post、ig_reel、reel の添付として届きます。 - アカウントのストーリーへの返信(
reply_to.story)と、アカウントをメンションしたストーリー(story_mention添付)。 - 以前のメッセージへのインライン返信(
reply_to.mid)と、クイック返信(quick_reply.payload)。 - 相手が削除したメッセージ(
is_deleted)、非対応メディア(is_unsupported)、Click-to-Direct 広告をクリックした相手からのメッセージ(referral)。 - アカウントが送ったメッセージ。
is_echoが true に設定されて返ってきます。
messages 通知はどのような形式ですか?
JSON の object が instagram に設定された POST です。コメントと違い、メッセージはアカウントの entry 内の messaging 配列に入り、各要素には sender、recipient、timestamp、message が含まれます。アカウントのストーリーへの返信は次のようになります:
{
"object": "instagram",
"entry": [
{
"id": "<IG_ID>",
"time": 1793448000512,
"messaging": [
{
"sender": { "id": "<IGSID>" },
"recipient": { "id": "<IG_ID>" },
"timestamp": 1793447999874,
"message": {
"mid": "<MESSAGE_ID>",
"text": "<MESSAGE_TEXT>",
"reply_to": {
"story": {
"url": "<CDN_URL_FOR_THE_STORY>",
"id": "<STORY_ID>"
}
}
}
}
]
}
]
}各フィールドの意味は?
Instagram Login の下で Meta が message イベントについて文書化しているフィールドを、外側から順に示します。
- entry[].id:プロフェッショナルアカウントの ID。entry[].time:Meta が通知を送信した時刻で、Meta のメッセージングのサンプルではミリ秒で示されます。
- sender.id と recipient.id:受信 DM では相手の Instagram スコープ ID とアカウントの ID、エコーではその逆になります。
- timestamp:メッセージが送信された時刻で、Meta のサンプルではミリ秒です。到着順ではなく、このタイムスタンプで並べ替えてください。
- message.mid:メッセージ ID。重複排除、リアクション、
reply_to.mid による返信に使います。 - message.text:メッセージにテキストが含まれる場合に入ります。
- message.attachments[]:それぞれに type と payload があり、通常は url を持ちます。共有投稿の
ig_postpayload には、キャプションであるig_post_media_idと title が加わります。 - message.
reply_to:インライン返信の場合は mid、ストーリー返信の場合は story が入り、ストーリーの url と id を持ちます。 - message.
quick_reply.payload と message.referral:選ばれたクイック返信と、Click-to-Direct 広告の ref、ad_id、source、type、ads_context_data。 - message.
is_deleted、is_echo、is_self、is_unsupported:true の場合にだけ含まれます。 - message.
admin_textとhandoff_reason:対象アプリでは、Meta のアプリ(Meta Business Agent など)が会話を引き継いだことを示す通知です。mid や text がない場合もあります。
エコーはどのように動作しますか?
アカウントがメッセージを送信すると、Meta は is_echo を true にした messages イベントも送ります。このとき sender.id はアカウント、recipient.id は相手の Instagram スコープ ID になり、アカウントが自分自身に送ったテストメッセージには is_self も付きます。エコーはアカウントが言ったことを記録するため会話ログには必要ですが、返信するかどうかを判断するハンドラーでは、エコーを必ずスキップしてください。アカウントがメッセージにリアクションしたり、リアクションを削除したりした場合、Meta はエコーを送りません。
{
"object": "instagram",
"entry": [
{
"id": "<IG_ID>",
"time": 1793448061203,
"messaging": [
{
"sender": { "id": "<IG_ID>" },
"recipient": { "id": "<IGSID>" },
"timestamp": 1793448060950,
"message": {
"mid": "<MESSAGE_ID>",
"text": "<REPLY_TEXT>",
"is_echo": true
}
}
]
}
]
}どの ID に返信しますか?
sender.id、つまり相手の Instagram スコープ ID です。この ID は、相手がアカウントにメッセージを送るか、アカウントのメディアにコメントしたときに Meta が作成するもので、その相手とそのアカウントに固有です。recipient.id にこの ID を設定して POST /<IG_ID>/messages を送ると返信できます。イベントには名前やユーザー名は含まれません。name や username などのフィールドを指定して GET /<IGSID> を呼ぶと取得できます。アカウントにメッセージを送った相手は、この検索に必要な同意を与えているためです。
メッセージは 24 時間ウィンドウをどのように開きますか?
アプリが相手にメッセージを送れるのは、相手がアカウントにメッセージを送った後に限られ、かつ相手の操作が開く標準のメッセージングウィンドウ内に限られます。ほとんどの操作では 24 時間続き、Click-to-Direct 広告をクリックした後に送られた最初のメッセージからは最大 7 日間続きます。相手から新しいメッセージが届くと新しいウィンドウが開くため、追跡すべきは相手の最新のタイムスタンプです。エコーはアカウント自身のメッセージなので、ウィンドウは延長されません。人が書いた返信には、Meta が別に設けた 7 日間の Human Agent ウィンドウを、human_agent タグを付けて使えます。
messages イベントに含まれないものは?
Meta のメッセージングリファレンスによると、ハンドラーが探すかもしれないいくつかのものは含まれていません:
- 相手の名前やユーザー名。含まれるのは Instagram スコープ ID のみで、GET /<IGSID> で解決できます。
- 一度だけ表示するメディア。URL のない一時的な添付として届きます。
- カルーセル内の正確な画像。カルーセル投稿の 1 枚の画像へのリアクションや転送は、最初の画像として報告されます。
- リアクション、編集、既読通知。これらは専用のフィールドで届きます。
- 既読マーク。Webhook で配信されたメッセージは、返信が送られるまで Instagram の受信箱で未読のままです。
Meta はほかにどのメッセージングフィールドを挙げていますか?
Instagram Login 向けの Meta のフィールド一覧とサンプルには、messages のほかに次の項目があり、いずれも独立した messaging イベントです。easyCoexistence は各アカウントを messages、comments、mentions のみに登録するため、以下はどれも転送される内容には含まれません:
message_reactions:相手がメッセージにリアクションしたり、リアクションを削除したりします。reaction.mid、action(react または unreact)、reaction と emoji を含みます。message_edit:相手がメッセージを編集します。message_edit.mid、新しいテキスト、num_editを含みます。messaging_postbacks:相手がアイスブレイカーやテンプレートボタンをタップします。postback.mid、title、payload を含みます。messaging_referral:すでに会話中の相手が、ref パラメーター付きの ig.me リンクを開きます。messaging_seen:相手がメッセージを読みます。read.mid を含みます。messaging_optins、messaging_handover、standby:後の 2 つは、Meta のハンドオーバープロトコルで会話を共有するアプリ向けです。
アカウント側で何を有効にする必要がありますか?
「メッセージへのアクセスを許可」を有効にしてください。Meta では、API からメッセージを管理できるようにする前に、プロフェッショナルアカウントでこれを有効にする必要があります。Instagram アプリで「設定」「メッセージとストーリーへの返信」「メッセージコントロール」「接続されたツール」の順に進みます。これがオフの間は、コード 200、サブコード 2534041 で送信が失敗します。アプリには instagram_business_basic と instagram_business_manage_messages が必要で、所有または管理していないアカウントに対応するには Advanced Access が必要です。
easyCoexistence は DM をどのように転送しますか?
コメントと同様に、Meta がアカウントについて配信する各 entry は、platform、account_id、external_id、entry を含むエンベロープに入れて HTTPS エンドポイントに POST されます。リクエストは X-EC-Signature で、アカウントのシークレットを使って署名されます。送信は一度だけで、コピーは保持されません。エコーも他と一緒に転送されるため、返信前に is_echo を確認してください。返信するには、account_id と、イベントの sender.id を recipient_id として send_social_dm を呼び出します。呼び出しは 24 時間ウィンドウ内に行ってください。DM を起点とするオートメーションも同じイベントで動作します。
{
"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": "image", "payload": { "url": "<URL_FOR_THE_MEDIA>" } }
]
}
}
]
}
}よくある間違い
- エコーに返信すること。is_echo が設定されたイベントはアカウント自身のメッセージで、それに返信するとアカウントが自分自身とのループに入ってしまいます。
- メッセージには必ずテキストがあると想定すること。添付、シェア、ストーリーのメンション、削除は text フィールドなしで届くため、message オブジェクトの内容で分岐してください。
- 到着順で並べること。Meta は障害後にメッセージを順不同で配信することがあるため、timestamp で並べ替えてください。
- time と timestamp を秒として解析すること。Meta のメッセージングのサンプルでは両方ともミリ秒で示されており、秒として読むと、はるか未来の日付になってしまいます。
アカウントごとのシークレットで署名されます。転送ではコピーは保持されず、DM は既定では保存されません。send_social_dm は 24 時間ウィンドウ内で返信し、オートメーションでは固定テキストや AI を使って自動返信できます。料金は接続 1 件あたり月額 US$ 9 から、接続を増やすほど下がり US$ 0.75 まで。最初の 3 日間は無料トライアルです。
よくある質問
Instagram のメッセージ Webhook のタイムスタンプは秒ですか、ミリ秒ですか?
Meta のメッセージングのサンプルでは、timestamp と entry の時刻のどちらもミリ秒です。秒として読むと、はるか未来の日付になります。
Instagram DM の Webhook から送信者のユーザー名を取得するには?
name や username などのフィールドを指定して GET /<IGSID> を呼び出してください。イベントに含まれるのは、相手の Instagram スコープ ID だけです。
Instagram DM の Webhook が届かないのはなぜですか?
アカウントで「メッセージへのアクセスを許可」が有効になっているか、/subscribed_apps で messages に登録されているか、所有していないアカウントに対してアプリが Advanced Access を備えた Live 状態になっているかを確認してください。
easyCoexistence は Instagram のメッセージリアクションを転送しますか?
いいえ。リアクションは message_reactions で届きますが、easyCoexistence はアカウントを messages、comments、mentions に登録しています。
続きを読む
最初のチャンネルを 2 分で接続しましょう。
プラットフォームの審査を待つ必要はありません。WhatsApp、Instagram、TikTok などのチャンネルを接続して、AI に投稿、返信、レポートを任せてみてください。
- 3 日間無料
- いつでも解約可能
- 公式 API のみ使用
- 24/7 監視
確認日