messages Webhook の Instagram DM 添付ファイル
Instagram の messages Webhook は、DM のメディアを message.attachments に入れて届けます。これは type と payload を持つオブジェクトの配列で、payload は通常 CDN の url を含みます。Instagram Login 向けの Meta の一覧では、image、video、audio、file、ig_post、ig_reel、reel、story_mention、media、story、ig_story、そして旧式の share が挙げられています。一度だけ表示されるメディアは、URL のない ephemeral 添付として届きます。
easyCoexistence は、接続された各 Instagram アカウントを messages に登録し、DM の添付を Meta が送ったとおりに、お使いの HTTPS エンドポイントへ転送します。
共有投稿の添付の種類。ペイロードには url に加えて、投稿のキャプションである ig_post_media_id と title が追加されます。
旧式の share 添付タイプが、Instagram の投稿共有でサポートされなくなった時期。
消えるメディア(一度だけ表示)の添付タイプで、URL は付きません。
メッセージに未対応のメディアが含まれる場合、メッセージイベントで true に設定されます。
カルーセル投稿の画像 1 枚にリアクションまたは転送があったときに、通知が報告する内容。
DM イベントはどの添付の種類を運べますか?
Meta の Instagram Login の例では、message.attachments[].type に次の値が挙げられており、それぞれ payload オブジェクトを持ちます。ほとんどの payload は Meta の CDN 上のメディアを指す url を含みます。Meta が追加の payload フィールドを文書化しているのは ig_post だけなので、payload を読む前に type を確認してください。
添付付きの DM はどのような形ですか?
message オブジェクトがテキストの代わりに、またはテキストと並んで attachments を持つ messages イベントです。Meta のサンプルでは、1 つのメッセージに 2 件のメディアが含まれ、それぞれが独自の type と payload.url を持っています。そのため、ハンドラーは最初の要素だけを読むのではなく、配列を繰り返し処理する必要があります:
{
"object": "instagram",
"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": "<CDN_URL>" } },
{ "type": "video", "payload": { "url": "<CDN_URL>" } }
]
}
}
]
}
]
}共有投稿はどのように届きますか?
ig_post 添付です。2025 年 11 月 3 日以降、Meta は投稿の共有を share と ig_post の両方の添付で送っていました。share は 2026 年 2 月 1 日まで投稿でサポートされ、Meta は新しい連携では ig_post への対応が必要だとしています。そのペイロードには、投稿のメディア ID と、title としてのキャプションが追加されます:
"attachments": [
{
"type": "ig_post",
"payload": {
"ig_post_media_id": "<MEDIA_ID>",
"title": "<POST_CAPTION>",
"url": "<CDN_URL>"
}
}
]各フィールドは何を意味しますか?
Meta が DM イベントについて文書化している添付フィールドを、配列から順に示します:
- message.attachments[]: メディア 1 件につき 1 オブジェクト。Meta のサンプルでは、1 つのメッセージに 2 件含まれます。
- type: 項目の種類。上の一覧から選びます。payload を読む前に、これで分岐してください。
- payload.url: メディアの CDN URL。Meta の概要では、これらの URL はプライバシーに配慮したもので、コンテンツが削除されたか期限切れになると何も返しません。
- payload.
ig_post_media_idと payload.title:ig_postのみ。共有された投稿のメディア ID とキャプションです。 - message.text: メッセージにテキストも含まれる場合にだけ存在します。
- message.
is_unsupported: メッセージに Webhook が対応していないメディアが含まれる場合に true になります。
添付 URL はどれくらい有効ですか?
Meta はそれらをコンテンツに紐づけています。Meta の概要では、Instagram の CDN URL はプライバシーに配慮したもので、コンテンツが削除されるか期限切れになると、メディアを返さなくなると説明しています。ストーリーメンションのガイドでは、ストーリーの URL はストーリーが期限切れになるか削除されると表示されなくなるとしています。ファイルが必要なアプリは、Meta のルールの範囲内で、イベントが届いたときに取得してください。特にストーリーのメディアは、保存もキャッシュもしてはいけません。
Webhook に含まれないメディアはどれですか?
Meta の Instagram Messaging ガイドには、ハンドラーがエラーとしてではなく、想定すべき抜け漏れとして扱うべき項目が次のように挙げられています:
- 消えるメディア(一度だけ表示、または再生を許可しない): URL のない ephemeral 型の添付です。
- 未対応のメディア: メッセージは
is_unsupportedが true に設定された状態で届きます。 - GIF とステッカー: そのガイドでは Webhook は発生しないとされていますが、Meta の Instagram Login の例では image に含まれています。
- 選ばれたカルーセル画像: カルーセル投稿の 1 枚へのリアクションや転送は、最初の画像として報告されます。
- 共有全般: Meta のメッセージングガイドでは、共有メディアの URL のみが含まれるとまだ書かれていますが、
ig_postでは現在メディア ID とキャプションも追加されます。
easyCoexistence は添付をどのように転送しますか?
エントリー内は変更されません:メディア付きの DM は、Meta が送ったとおりの attachments 配列を含み、platform、account_id、external_id、entry からなるエンベロープに入り、X-EC-Signature で署名されてエンドポイントに届きます。添付ファイルはダウンロードされず、イベントは既定では保存されません。オートメーションを有効にしているアカウントは、DM のテキストを 7 日間保持しますが、メディアは保持しません。必要なメディアは、イベントが届いた時点で payload.url から取得してください。ストーリーのメディアは保存しないでください。
よくある間違い
- 最初の添付だけを読む。message.attachments は配列で、Meta のサンプルでは 1 つのメッセージに 2 件入るため、配列を繰り返し処理してください。
- 共有投稿に今も type share で照合している。Meta は投稿について 2026 年 2 月 1 日まで対応していました。ig_post を読み、メディア ID とキャプションは payload から取得してください。
- payload.url を後で取得するために保存する。コンテンツが削除されるか期限切れになると、メディアを返さなくなるため、ストーリーのメディアを除き、到着時に必要なものをダウンロードしてください。
- type を確認せずに payload.url を読む。一度だけ表示されるメディアは URL のない ephemeral として届き、未対応のメディアは is_unsupported を設定します。
署名はそのアカウントのシークレットで行われ、コピーは保持されません。そのため、エージェントやコードが必要なメディアを取得できます。send_social_dm は 24 時間のウィンドウ内での返信に使えます。接続 1 件あたり月額 US$ 9 から、接続を増やすほど下がり US$ 0.75 まで。最初の 3 日間は無料です。
よくある質問
Instagram DM の添付からメディアを保存できますか?
イベントが届いたときに必要なものをダウンロードしてください。payload.url は、コンテンツが削除されるか期限切れになるとメディアを返さなくなるためです。ストーリーのメディアは例外で、Meta のルールでは保存もキャッシュもしてはいけないとされています。
なぜ Instagram DM の Webhook にはメディアの URL がないのですか?
多くの場合、メディアが一度だけ表示されるものか、未対応のものだからです。一度だけ表示されるものは URL のない ephemeral 添付として届き、未対応のものは is_unsupported を true に設定します。
Instagram の GIF やステッカーは messages Webhook を発生させますか?
Meta のドキュメントは一致していません。Instagram Login の例では GIF とステッカーを image に含めていますが、Instagram Messaging ガイドでは Webhook は発生しないとされています。実際のアカウントでテストしてください。
1 件の Instagram DM イベントに複数の添付が含まれることはありますか?
はい。message.attachments は配列で、Meta のサンプルでは 1 つのメッセージに 2 件のメディアが含まれています。
続きを読む
最初のチャンネルを 2 分で接続しましょう。
プラットフォームの審査を待つ必要はありません。WhatsApp、Instagram、TikTok などのチャンネルを接続して、AI に投稿、返信、レポートを任せてみてください。
- 3 日間無料
- いつでも解約可能
- 公式 API のみ使用
- 24/7 監視
確認日