Instagram messaging_referral Webhook:ig.me 連結與廣告推薦
Instagram 的 messaging_referral Webhook 欄位會在已與專業帳戶有對話的用戶開啟帶有 ref 參數的 ig.me 連結時,通知應用程式。事件中有一個頂層 referral 物件:ref 為參數值;source 為 SHORTLINKS;type 為 OPEN_THREAD。新對話中的 ref 則會改在 messages 或 messaging_postbacks 事件內送達。
easyCoexistence 會為每個已連接的 Instagram 帳戶訂閱 comments、messages 與 mentions,因此新對話首則訊息中的 ref,以及 Click-to-Direct 廣告的推薦,都會在轉發的 DM 內送達你的 HTTPS 端點,並以該帳戶的密鑰簽署。
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 會自行發送推薦,不附帶訊息。推薦會在哪裡送達,取決於對話串及用戶的操作:
推薦通知是什麼樣子?
一則訊息事件,其 referral 物件與 sender、recipient 及 timestamp 並列,前後不附帶 message 或 postback。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"
}
}
]
}
]
}referral 的各欄位分別代表什麼?
以下為 Meta 為 ig.me 推薦所記載的欄位,由外至內排列:
- sender.id:開啟連結之用戶的 Instagram 範圍 ID。recipient.id 與 entry[].id:專業帳戶。
- referral.ref:連結中 ref 參數的值,與連結所攜帶的內容一致。
- referral.source:Meta 的 ig.me 範例中為 SHORTLINKS。Meta 的 Instagram 訊息指南中有一個表格拼寫為 SHORTLINK,其範例頁面則顯示佔位符。
- referral.type:
OPEN_THREAD,Meta 用於 ig.me 推薦。 - timestamp:事件觸發的時間,Meta 範例中以毫秒計。
如何建立帶有 ref 的 ig.me 連結?
格式為 https://ig.me/<USERNAME>?ref=<VALUE>,其中 USERNAME 為專業帳戶的用戶名稱,見 Meta 的 Instagram Login 指南;其 Instagram 訊息指南則寫作 https://ig.me/m/<USERNAME>。ref 最多可達 2,083 個字元,只可使用英文字母、數字、連字號、底線與等號。Meta 建議用 ref 追蹤渠道、把用戶與另一應用程式的工作階段連繫,或引導至特定內容,並建議為新對話設置各自附有 ref 的 ice breaker。
廣告推薦在哪裡送達?
在 messages 事件中送達。用戶點擊開啟 Instagram Direct 的廣告並發送訊息後,會產生一則 messages 事件,其 message.referral 包含廣告的 ref(如有設定)、ad_id、source ADS、type OPEN_THREAD,以及 ads_context_data,當中有廣告標題,以及用戶點擊的 photo_url 或 video_url。Meta 的 Instagram 頁面只記載 ig.me 連結的 messaging_referral。
"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 會轉發推薦嗎?
會轉發附於訊息的推薦。每個已連接的 Instagram 帳戶都會訂閱 comments、messages 與 mentions,因此新對話首則訊息中的 ref,以及 Click-to-Direct 廣告的推薦,都會以 message.referral 形式,於轉發的 DM 內送達你的端點。messaging_referral(用於現有對話串)與 messaging_postbacks(用於 ice breaker 點擊)則是獨立欄位,由 Meta 傳送給已訂閱它們的應用程式。
常見錯誤
- 在新對話中等待 messaging_referral。新對話中的 ref 會按用戶是輸入還是點擊 ice breaker,而在 messages 或 messaging_postbacks 中送達。
- 在 ref 中使用其他字元。Meta 只接受英文字母、數字、連字號、底線與等號,最多 2,083 個字元。
- 將 source 與單一完整字串作比對。Meta 的範例中,ig.me 為 SHORTLINKS,廣告為 ADS,但其中一個表格寫作 SHORTLINK,因此應按推薦所在位置及 ref 進行判斷。
- 在 Instagram Web 上測試連結。Meta 不支援在 Instagram Web 上使用 ig.me 連結,請在 Instagram 應用程式中開啟。
send_social_dm 會在 24 小時時間窗口內回覆。每個連接每月 US$ 9 至 US$ 0.75,連接越多越便宜,首 3 天免費。
常見問題
referral.source 在 Instagram 推薦中包含什麼?
Meta 的 ig.me 範例為 SHORTLINKS,廣告的 Click-to-Direct 推薦則為 ADS,不過 Meta 的 Instagram 訊息指南中有一個表格寫作 SHORTLINK。應按推薦所在位置及 ref 進行判斷,而非依賴單一的完整字串。
ig.me 的 ref 參數最長可以多長?
最多 2,083 個字元,只可使用英文字母、數字、連字號、底線與等號。
ig.me 的 ref 在 Instagram 新對話中於何處送達?
用戶輸入首則訊息時在 messages 送達,點擊 ice breaker 時則在 messaging_postbacks 送達。messaging_referral 只涵蓋現有對話串。
ig.me 連結能否在 Instagram Web 上運作?
不能。Meta 的 ig.me 指南指出,Instagram Web 不支援此類連結。
繼續閱讀
兩分鐘內連接您的第一個頻道。
無需等待平台審核。連接 WhatsApp、Instagram、TikTok 或其他頻道,然後請您的 AI 發佈貼文、回覆訊息或匯報數據,並看着它運作。
- 免費試用 3 天
- 隨時取消
- 只用官方 API
- 24/7 監察
驗證日期