Iniciar sesiónEmpezar prueba gratis
easyCoexistence APIs oficiales

Webhook messaging_referral de Instagram: enlaces ig.me y referencias de anuncios

El campo messaging_referral de Instagram notifica a una app cuando una persona que ya tiene una conversación con una cuenta profesional abre un enlace ig.me con el parámetro ref. El evento contiene un objeto referral de primer nivel: ref, el valor del parámetro; source, SHORTLINKS; y type, OPEN_THREAD. Un ref en una conversación nueva llega dentro del evento messages o messaging_postbacks.

easyCoexistence suscribe cada cuenta de Instagram conectada a comments, messages y mentions, así que un ref en el primer mensaje de un hilo nuevo y la referencia de un anuncio Click-to-Direct llegan a tu endpoint HTTPS dentro del DM reenviado, firmado con el secreto de esa cuenta.

2,083

Número máximo de caracteres que puede tener el parámetro ref de un enlace ig.me, usando solo letras, dígitos, guiones, guiones bajos y signos de igual.

OPEN_THREAD

Tipo de referencia de los enlaces ig.me; la referencia de un anuncio Click-to-Direct también lo usa, con source ADS.

24 hours

Tiempo que tiene la app para responder tras una referencia en una conversación existente, lo que restablece la ventana estándar.

7 days

Duración máxima de la ventana que abre un primer mensaje enviado tras hacer clic en un anuncio Click-to-Direct.

Instagram Web

Dónde no se admiten los enlaces ig.me, según la guía de ig.me de Meta.

¿Cuándo se activa messaging_referral?

Cuando una persona que ya tiene una conversación con la cuenta profesional abre un enlace ig.me que lleva un parámetro ref. Instagram abre el hilo existente y Meta envía la referencia por su cuenta, sin ningún mensaje. Dónde llega una referencia depende del hilo y de lo que haga 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.

¿Cómo es una notificación de referencia?

Un evento de mensajería cuyo objeto referral va junto a sender, recipient y timestamp, sin mensaje ni postback alrededor. La guía de ig.me de Meta muestra los valores de la referencia dentro del mismo esquema que los demás eventos de mensajería de 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"
          }
        }
      ]
    }
  ]
}

¿Qué significa cada campo?

Los campos que Meta documenta para una referencia de ig.me, de fuera hacia dentro:

  • sender.id: el ID con alcance de Instagram de la persona que abrió el enlace. recipient.id y entry[].id: la cuenta profesional.
  • referral.ref: el valor del parámetro ref del enlace, tal como lo llevaba.
  • referral.source: SHORTLINKS en los ejemplos de ig.me de Meta. Una tabla de su guía de mensajería de Instagram lo escribe SHORTLINK, y su página de ejemplos muestra un marcador de posición.
  • referral.type: OPEN_THREAD, que Meta usa en las referencias de ig.me.
  • timestamp: cuándo se activó el evento, en milisegundos en los ejemplos de Meta.

¿Cómo se construye un enlace ig.me con ref?

Como https://ig.me/<USERNAME>?ref=<VALUE>, donde USERNAME es el nombre de usuario de la cuenta profesional, según la guía de Instagram Login de Meta; su guía de mensajería de Instagram escribe https://ig.me/m/<USERNAME>. El ref puede tener hasta 2,083 caracteres de letras, dígitos, guiones, guiones bajos y signos de igual. Meta sugiere refs para rastrear canales, vincular a una persona con una sesión de otra app o dirigirla a un contenido concreto, y recomienda rompehielos, cada uno con su propio ref, para las conversaciones nuevas.

¿Dónde llegan las referencias de anuncios?

En messages. Una persona que hace clic en un anuncio que abre Instagram Direct y envía un mensaje genera un evento messages cuyo message.referral contiene el ref del anuncio si se definió uno, ad_id, source ADS, type OPEN_THREAD y ads_context_data con el título del anuncio y el photo_url o video_url en el que hizo clic. Las páginas de Instagram de Meta documentan messaging_referral solo para los enlaces 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>"
    }
  }
}

¿Una referencia abre la ventana de mensajería?

Sí, en un hilo existente: la guía de ig.me de Meta indica que la referencia restablece la ventana estándar de mensajería de 24 horas, así que la app puede responder dentro de las 24 horas del evento. Un primer mensaje enviado tras hacer clic en un anuncio Click-to-Direct puede abrir una ventana de hasta 7 días desde ese mensaje. Responde con POST /<IG_ID>/messages y recipient.id igual al sender.id del evento.

¿easyCoexistence reenvía las referencias?

Las que viajan en messages. Cada cuenta conectada está suscrita a comments, messages y mentions, así que un ref en el primer mensaje de un hilo nuevo y la referencia de un anuncio Click-to-Direct llegan a tu endpoint dentro del DM reenviado, como message.referral. messaging_referral, para hilos existentes, y messaging_postbacks, para los toques en rompehielos, son campos separados que Meta entrega a una app suscrita a ellos.

Errores comunes

  • Esperar messaging_referral en una conversación nueva. Ahí el ref llega en messages o messaging_postbacks, según la persona haya escrito o tocado un rompehielos.
  • Poner otros caracteres en ref. Meta acepta letras, dígitos, guiones, guiones bajos y signos de igual, hasta 2,083 caracteres.
  • Comparar source con una sola cadena exacta. Los ejemplos de Meta muestran SHORTLINKS para ig.me y ADS para anuncios, pero una de sus tablas dice SHORTLINK; decide según dónde esté la referencia y según ref.
  • Probar los enlaces en Instagram Web. Meta no admite enlaces ig.me allí, así que ábrelos en la app de Instagram.
Hacerlo con EasyCoexistence

send_social_dm responde dentro de la ventana de 24 horas. De US$ 9 a US$ 0.75 por conexión al mes, bajando a medida que añades conexiones, con los primeros 3 días gratis.

Preguntas frecuentes

¿Qué contiene referral.source en una referencia de Instagram?

SHORTLINKS en los ejemplos de ig.me de Meta y ADS para un anuncio Click-to-Direct, aunque una tabla de la guía de mensajería de Instagram de Meta lo escribe SHORTLINK. Decide según dónde esté la referencia y según ref, en lugar de una sola cadena exacta.

¿Cuánto puede medir el parámetro ref de un enlace ig.me?

Hasta 2,083 caracteres, usando solo letras, dígitos, guiones, guiones bajos y signos de igual.

¿Dónde llega un ref de ig.me en una conversación nueva de Instagram?

En messages cuando la persona escribe un primer mensaje, o en messaging_postbacks cuando toca un rompehielos. messaging_referral cubre solo los hilos existentes.

¿Funcionan los enlaces ig.me en Instagram Web?

No. La guía de ig.me de Meta indica que no se admiten en Instagram Web.

Sigue leyendo

Conecta tu primer canal en dos minutos.

Sin esperar revisiones de las plataformas. Conecta WhatsApp, Instagram, TikTok u otro canal, pídele a tu IA que publique, responda o te haga un informe, y míralo trabajar.

  • 3 días gratis
  • Cancela cuando quieras
  • Solo APIs oficiales
  • Monitorizado 24/7

Verificado el