Instagram messaging_referral Webhook: ig.me リンクと広告からの参照
Instagram の messaging_referral フィールドは、ref パラメータを含む ig.me リンクを、すでに企業アカウントと会話がある人が開いたときにアプリへ通知します。イベントには最上位の referral オブジェクトが含まれ、ref はパラメータの値、source は SHORTLINKS、type は OPEN_THREAD です。新しい会話での ref は、代わりに messages または messaging_postbacks イベントに含まれて届きます。
easyCoexistence は、接続された各 Instagram アカウントのコメント、メッセージ、メンションを購読します。
ig.me の ref パラメータに入れられる最大文字数。使えるのは英字、数字、ハイフン、アンダースコア、等号のみです。
ig.me リンクの参照タイプ。Click-to-Direct 広告の参照も同じ型を使い、source は ADS になります。
既存の会話での参照を受けたあと、アプリが返信できる期限。標準のウィンドウはこの時点からリセットされます。
Click-to-Direct 広告をクリックしたあとに最初のメッセージを送った場合に、ウィンドウが続く最長期間。
Meta の ig.me ガイドによると、ig.me リンクが対応していない環境。
messaging_referral はいつ発火しますか?
すでに企業アカウントと会話がある人が、ref パラメータ付きの ig.me リンクを開いたときに発火します。Instagram は既存のスレッドを開き、Meta はメッセージなしで参照を単独で送信します。参照が届く場所は、スレッドの状態と本人の操作によって変わります。
参照通知はどのような形式ですか?
sender、recipient、timestamp と並んで referral オブジェクトを持つメッセージングイベントです。メッセージやポストバックは含まれません。Meta の ig.me ガイドでは、他の Instagram メッセージングイベントと同じエンベロープ内に、参照の値が次のように示されています:
{
"object": "instagram",
"entry": [
{
"id": "<IG_ID>",
"time": 1793448000512,
"messaging": [
{
"sender": { "id": "<IGSID>" },
"recipient": { "id": "<IG_ID>" },
"timestamp": 1793447999874,
"referral": {
"ref": "<REF_PARAMETER_VALUE>",
"source": "SHORTLINKS",
"type": "OPEN_THREAD"
}
}
]
}
]
}各フィールドの意味は何ですか?
Meta が ig.me 参照について文書化しているフィールドを、外側から順に示します:
- sender.id: リンクを開いた人の Instagram スコープ ID。recipient.id と entry[].id: 企業アカウント。
- referral.ref: リンクの ref パラメータの値。リンクに含まれていたとおりの値です。
- referral.source: Meta の ig.me サンプルでは SHORTLINKS。Meta の Instagram Messaging ガイドの表では SHORTLINK と表記されており、例のページではプレースホルダーが使われています。
- referral.type: ig.me 参照で Meta が使う
OPEN_THREAD。 - timestamp: イベントがトリガーされた時刻。Meta のサンプルではミリ秒単位です。
ref 付きの ig.me リンクはどう作りますか?
https://ig.me/<USERNAME>?ref=<VALUE> の形式で作成します。USERNAME は企業アカウントのハンドルです。Meta の Instagram Login ガイドではこの形式ですが、Instagram Messaging ガイドでは https://ig.me/m/<USERNAME> と書かれています。ref には英字、数字、ハイフン、アンダースコア、等号を使い、最大 2,083 文字まで入力できます。Meta は、チャネルの追跡、別のアプリのセッションと人の紐付け、特定コンテンツへの誘導に ref を使うことを勧めています。また、新規会話にはアイスブレイカーを用意し、それぞれに個別の ref を付けることを推奨しています。
広告からの参照はどこに届きますか?
messages に届きます。Instagram のダイレクトを開いてメッセージを送る広告をクリックした人は、messages イベントを発生させます。その message.referral には、設定されていれば広告の ref、ad_id、source の ADS、type の OPEN_THREAD、そして広告のタイトルとクリックされた photo_url または video_url を含む ads_context_data が含まれます。Meta の Instagram ページでは、messaging_referral は ig.me リンクについてのみ説明されています。
"message": {
"mid": "<MESSAGE_ID>",
"referral": {
"ref": "<AD_REF_IF_SET>",
"ad_id": "<AD_ID>",
"source": "ADS",
"type": "OPEN_THREAD",
"ads_context_data": {
"ad_title": "<AD_TITLE>",
"photo_url": "<IMAGE_URL_CLICKED>",
"video_url": "<THUMBNAIL_URL_FOR_THE_AD_VIDEO>"
}
}
}参照によってメッセージングウィンドウは開きますか?
既存のスレッドでは、はい。Meta の ig.me ガイドによると、参照によって 24 時間の標準メッセージングウィンドウがリセットされるため、アプリはイベントから 24 時間以内に返信できます。Click-to-Direct 広告をクリックしたあとに最初のメッセージを送ると、そのメッセージから最長 7 日間のウィンドウが開く場合があります。返信には POST /<IG_ID>/messages を使い、recipient.id にはイベントの sender.id を設定してください。
easyCoexistence は参照を転送しますか?
メッセージに乗って届く参照は転送します。接続された各アカウントは、コメント、メッセージ、メンションを購読しています。そのため、新しいスレッドの最初のメッセージに含まれる ref と、Click-to-Direct 広告の参照は、転送された DM の中で message.referral としてエンドポイントに届きます。既存のスレッドを対象とする messaging_referral と、アイスブレイクのタップを対象とする messaging_postbacks は、それぞれ別のフィールドで、購読しているアプリに Meta が配信します。
よくある間違い
- 新しい会話で messaging_referral を待つこと。新規会話では、本人が入力したか、アイスブレイカーをタップしたかによって、ref は messages または messaging_postbacks に届きます。
- ref に他の文字を入れること。Meta が受け付けるのは英字、数字、ハイフン、アンダースコア、等号のみで、最大 2,083 文字です。
- source を一つの完全一致文字列と比較すること。Meta のサンプルでは ig.me は SHORTLINKS、広告は ADS ですが、ある表では SHORTLINK と書かれています。source ではなく、参照の位置と ref によって分岐させてください。
- Instagram Web でリンクをテストすること。Meta は Instagram Web での ig.me リンクに対応していないため、Instagram アプリで開いてください。
そのため、新しいスレッドの最初のメッセージに含まれる ref と Click-to-Direct 広告の参照は、そのアカウントのシークレットで署名された転送 DM の中で、HTTPS エンドポイントに届きます。send_social_dm は 24 時間のウィンドウ内で返信します。料金は接続 1 件あたり月額 US$ 9 から US$ 0.75 まで、接続を増やすほど下がります。最初の 3 日間は無料です。
よくある質問
Instagram の参照で referral.source には何が入りますか?
Meta の ig.me サンプルでは SHORTLINKS、Click-to-Direct 広告では ADS が入ります。ただし Meta の Instagram Messaging ガイドの表では SHORTLINK と表記されています。値の完全一致ではなく、参照の位置と ref によって分岐してください。
ig.me の ref パラメータはどのくらいの長さにできますか?
最大 2,083 文字です。使えるのは英字、数字、ハイフン、アンダースコア、等号のみです。
新しい Instagram 会話では、ig.me の ref はどこに届きますか?
本人が最初のメッセージを入力した場合は messages、アイスブレイカーをタップした場合は messaging_postbacks に届きます。messaging_referral が対象とするのは既存のスレッドのみです。
ig.me リンクは Instagram Web で動きますか?
いいえ。Meta の ig.me ガイドでは、Instagram Web での利用はサポートされていないとされています。
続きを読む
最初のチャンネルを 2 分で接続しましょう。
プラットフォームの審査を待つ必要はありません。WhatsApp、Instagram、TikTok などのチャンネルを接続して、AI に投稿、返信、レポートを任せてみてください。
- 3 日間無料
- いつでも解約可能
- 公式 API のみ使用
- 24/7 監視
確認日