AccediInizia la prova gratuita
easyCoexistence API ufficiali

Webhook messaging_referral di Instagram: link ig.me e referral degli annunci

Il campo messaging_referral del webhook di Instagram avvisa un'app quando una persona che ha già una conversazione con un account professionale apre un link ig.me con il parametro ref. L'evento contiene un oggetto referral di primo livello: ref, cioè il valore del parametro; source, SHORTLINKS; e type, OPEN_THREAD. Un ref su una nuova conversazione arriva invece all'interno dell'evento messages o messaging_postbacks.

easyCoexistence iscrive ogni account Instagram collegato a commenti, messaggi e menzioni, quindi un ref sul primo messaggio di una nuova conversazione e il referral di un annuncio Click-to-Direct arrivano al tuo endpoint HTTPS dentro il DM inoltrato, firmato con il segreto di quell'account.

2,083

Lunghezza massima, in caratteri, del parametro ref di ig.me, che può contenere solo lettere, cifre, trattini, trattini bassi e segni di uguale.

OPEN_THREAD

Tipo di referral per i link ig.me; anche il referral di un annuncio Click-to-Direct lo usa, con source ADS.

24 hours

Tempo a disposizione dell'app per rispondere dopo un referral in una conversazione esistente, che reimposta la finestra standard.

7 days

Durata massima della finestra aperta dal primo messaggio inviato dopo il clic su un annuncio Click-to-Direct.

Instagram Web

Casi in cui i link ig.me non sono supportati, secondo la guida ig.me di Meta.

Quando si attiva messaging_referral?

Quando una persona che ha già una conversazione con l'account professionale apre un link ig.me con un parametro ref. Instagram apre la conversazione esistente e Meta invia il referral da solo, senza alcun messaggio. Dove arriva un ref dipende dalla conversazione e da ciò che fa la persona:

Existing threadmessaging_referral: a referral object beside sender, with no message.
New thread, ice breaker tappedmessaging_postbacks: postback.referral beside title and payload.
New thread, message typedmessages: message.referral beside mid.
Click-to-Direct admessages: message.referral with source ADS, ad_id and ads_context_data.

Che aspetto ha una notifica di referral?

Un evento di messaggistica il cui oggetto referral si trova accanto a sender, recipient e timestamp, senza messaggi o postback intorno. La guida ig.me di Meta riporta i valori del referral, all'interno della stessa struttura degli altri eventi di messaggistica di Instagram:

A messaging_referral notification
{
  "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"
          }
        }
      ]
    }
  ]
}

Che significato ha ciascun campo?

I campi che Meta documenta per un referral ig.me, dall'esterno verso l'interno:

  • sender.id: l'ID con ambito Instagram della persona che ha aperto il link. recipient.id e entry[].id: l'account professionale.
  • referral.ref: il valore del parametro ref del link, così come era nel link.
  • referral.source: SHORTLINKS negli esempi ig.me di Meta. Una tabella della sua guida Instagram Messaging lo scrive SHORTLINK, e la sua pagina di esempi mostra un segnaposto.
  • referral.type: OPEN_THREAD, che Meta usa per i referral ig.me.
  • timestamp: il momento in cui è stato generato l'evento, in millisecondi negli esempi di Meta.

Come si costruisce un link ig.me con un ref?

Nella forma https://ig.me/<USERNAME>?ref=<VALUE>, dove USERNAME è il nome utente dell'account professionale, secondo la guida Instagram Login di Meta; la sua guida Instagram Messaging scrive https://ig.me/m/<USERNAME>. Il ref può arrivare fino a 2.083 caratteri di lettere, cifre, trattini, trattini bassi e segni di uguale. Meta suggerisce di usare i ref per tracciare i canali, collegare una persona a una sessione in un'altra app o indirizzarla verso contenuti specifici, e consiglia gli ice breaker, ciascuno con un proprio ref, per le nuove conversazioni.

Dove arrivano i referral degli annunci?

Nei messaggi. Una persona che clicca un annuncio che apre Instagram Direct e invia un messaggio genera un evento messages il cui message.referral contiene il ref dell'annuncio, se impostato, ad_id, source ADS, type OPEN_THREAD e ads_context_data con il titolo dell'annuncio e la photo_url o la video_url cliccata. Le pagine Instagram di Meta documentano messaging_referral solo per i link ig.me.

A Click-to-Direct ad referral, inside messages
"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>"
    }
  }
}

Un referral apre la finestra di messaggistica?

Sì, in una conversazione esistente: la guida ig.me di Meta dice che il referral reimposta la finestra standard di messaggistica di 24 ore, così l'app può rispondere entro 24 ore dall'evento. Un primo messaggio inviato dopo il clic su un annuncio Click-to-Direct può aprire una finestra fino a 7 giorni da quel messaggio. Rispondi con POST /<IG_ID>/messages impostando recipient.id sul sender.id dell'evento.

easyCoexistence inoltra i referral?

Quelli che arrivano dentro i messaggi. Ogni account Instagram collegato è iscritto a commenti, messaggi e menzioni, quindi un ref sul primo messaggio di una nuova conversazione e il referral di un annuncio Click-to-Direct arrivano al tuo endpoint dentro il DM inoltrato, come message.referral. messaging_referral, per le conversazioni esistenti, e messaging_postbacks, per i tocchi sugli ice breaker, sono campi separati che Meta consegna a un'app iscritta a essi.

Errori comuni

  • Aspettarsi messaging_referral su una nuova conversazione. Lì il ref arriva in messages o messaging_postbacks, a seconda che la persona abbia scritto o toccato un ice breaker.
  • Inserire altri caratteri nel ref. Meta accetta lettere, cifre, trattini, trattini bassi e segni di uguale, fino a 2.083 caratteri.
  • Confrontare source con una sola stringa esatta. Gli esempi di Meta mostrano SHORTLINKS per ig.me e ADS per gli annunci, ma una delle sue tabelle riporta SHORTLINK, quindi verifica dove si trova il referral e il ref.
  • Testare i link su Instagram Web. Meta non li supporta lì, quindi aprili nell'app Instagram.
Farlo con EasyCoexistence

send_social_dm risponde entro la finestra di 24 ore. Da US$ 9 a US$ 0,75 per connessione al mese, in calo man mano che aggiungi connessioni, con i primi 3 giorni di prova gratuita.

Domande frequenti

Cosa contiene referral.source in un referral Instagram?

SHORTLINKS negli esempi ig.me di Meta e ADS per un annuncio Click-to-Direct, anche se una tabella della guida Instagram Messaging di Meta scrive SHORTLINK. Verifica dove si trova il referral e il ref invece di basarti su una sola stringa esatta.

Quanto può essere lungo il parametro ref di ig.me?

Fino a 2.083 caratteri, usando solo lettere, cifre, trattini, trattini bassi e segni di uguale.

Dove arriva un ref di ig.me su una nuova conversazione Instagram?

In messages quando la persona scrive un primo messaggio, o in messaging_postbacks quando tocca un ice breaker. messaging_referral riguarda solo le conversazioni esistenti.

I link ig.me funzionano su Instagram Web?

No. La guida ig.me di Meta dice che non sono supportati su Instagram Web.

Continua a leggere

Collega il tuo primo canale in due minuti.

Nessuna revisione delle piattaforme da aspettare. Collega WhatsApp, Instagram, TikTok o un altro canale, poi chiedi alla tua AI di pubblicare, rispondere o fare un report, e guardala al lavoro.

  • 3 giorni gratis
  • Disdici quando vuoi
  • Solo API ufficiali
  • Monitorato 24/7

Verificato il