Configurar webhooks para Instagram

Los webhooks para Instagram permiten recibir notificaciones en tiempo real cuando alguien hace un comentario en los objetos multimedia de los usuarios de la aplicación, cuando alguien @menciona a dichos usuarios o cuando caducan sus historias.

Recibir notificaciones de webhooks en directo

Para recibir notificaciones de webhooks en directo, se deben reunir las condiciones siguientes:

• Es necesario configurar los webhooks de Instagram y suscribirse a los campos correspondientes en el panel de aplicaciones.
• Las aplicaciones de consumidor deben estar en modo publicado.
• Las aplicaciones empresariales deben tener permisos con un nivel de acceso avanzado. Puedes solicitar el acceso avanzado para los permisos como se muestra a continuación:

• El usuario de la aplicación le debe haber concedido los permisos adecuados (instagram_manage_insights para historias e instagram_manage_comments para comentarios y @menciones).
• La página conectada a la cuenta del usuario de la aplicación debe tener las suscripciones de página activadas.
• La empresa conectada a la página del usuario de la aplicación debe estar verificada.
• El propietario del objeto multimedia en el que aparece el comentario o la @mención no debe tener la cuenta establecida en privada.

Limitaciones

• Las notificaciones de webhooks para los comentarios de los álbumes no incluyen el identificador del álbum. Para obtenerlo, envía una consulta al identificador del comentario en el webhook y solicita su campo media.
• Las aplicaciones no reciben notificaciones de webhooks si el contenido multimedia en que aparece el comentario o la @mención se creó mediante una cuenta privada.
• Las métricas de insights de historias con recuentos inferiores a 5 se devuelven como -1.
• Las aplicaciones solo reciben notificaciones de webhooks para los comentarios en contenido multimedia publicado de Instagram si dicho contenido está en una transmisión.
• No se admiten los reels.
• Tu aplicación debe haber completado la revisión de la aplicación correctamente (acceso avanzado) para recibir notificaciones de los webhooks de los campos de webhook comments y live_comments.
• Si el contenido multimedia se utiliza para anuncios dinámicos, el identificador del anuncio no se devolverá.

Paso 1: Crear un extremo

Crea un extremo que acepte y procese webhooks. Durante la configuración, selecciona el objeto API Graph de Instagram, haz clic en Configurar y suscríbete a uno o varios campos de Instagram.

Campos de Instagram

Paso 2: Activar las suscripciones de página

La aplicación debe activar las suscripciones de página en la página conectada a la cuenta del usuario de la aplicación. Para ello, es necesario enviar una solicitud POST al perímetro de aplicaciones suscritas a una página y suscribirse a cualquier campo de la página.

Requisitos de extremo

• Identificador de acceso a la página del usuario de la aplicación
• pages_manage_metadata

Sintaxis de la solicitud

POST /{page-id}/subscribed_apps
  ?access_token={access-token}
  &subscribed_fields={fields}

Parámetros de la solicitud

La aplicación no recibe notificaciones de cambios en un campo a menos que configures suscripciones de página en el panel de aplicaciones y te suscribas a ese campo.

Ejemplo de solicitud

curl -i -X POST \
  "https://graph.facebook.com/v21.0/1755847768034402/subscribed_apps?subscribed_fields=feed&access_token=EAAFB..."

Ejemplo de respuesta

{
  "success": true
}

Usos habituales

Capturar insights de historias

Si te suscribes al campo story_insights, enviamos al extremo una notificación de webhook con métricas de las interacciones de los usuarios en una historia después de que esta caduque.

Ejemplo de carga útil de insights de historias

[
  {
    "entry": [
      {
        "changes": [
          {
            "field": "story_insights",
            "value": {
              "media_id": "18023345989012587",
              "exits": 1,
              "replies": 0,
              "reach": 17,
              "taps_forward": 12,
              "taps_back": 0,
              "impressions": 28
            }
          }
        ],
        "id": "17841405309211844",  // Instagram Business or Creator Account ID
        "time": 1547687043
      }
    ],
    "object": "instagram"
  }
]

Responder a @menciones de comentarios

Si te suscribes al campo mentions, enviamos al extremo una notificación de webhook cuando un usuario de Instagram @menciona una cuenta empresarial o de creador de Instagram en un comentario o un texto.

Por ejemplo, a continuación se incluye un ejemplo de carga útil de notificaciones de webhooks de comentarios enviadas para una cuenta empresarial de Instagram (17841405726653026):

Ejemplo de carga útil de @menciones de comentarios

[
  {
    "entry": [
      {
        "changes": [
          {
            "field": "mentions",
            "value": {
              "comment_id": "17894227972186120",
              "media_id": "17918195224117851"
            }
          }
        ],
        "id": "17841405726653026",
        "time": 1520622968
      }
    ],
    "object": "instagram"
  }
]

Obtener el contenido del comentario

Para obtener el contenido del comentario, utiliza la propiedad comment_id a fin de enviar una consulta al perímetro GET /{ig-user-id}/mentioned_comment:

Ejemplo de consulta

GET https://graph.facebook.com/17841405726653026 ?fields=mentioned_comment.comment_id(17894227972186120) 

Ejemplo de respuesta

{
  "mentioned_comment": {
    "timestamp": "2018-03-20T00:05:29+0000",
    "text": "@bluebottle challenge?",
    "id": "17894227972186120"
  },
  "id": "17841405726653026"
}

Analizar la carga útil y responder

Al recibir la respuesta, analiza la carga útil de la propiedad text a fin de determinar si quieres responder al comentario. Para responder, utiliza los valores de las propiedades caption_id y media_id de la carga útil de notificaciones de webhooks a fin de enviar una consulta al extremo POST /{ig-user-id}/mentions:

Ejemplo de consulta

curl -i -X POST \
  -d "comment_id=17894227972186120" \
  -d "media_id=17918195224117851" \
  -d "message=Challenge%20accepted!" \
  -d "access_token={access-token}" \
  "https://graph.facebook.com/17841405726653026/mentions"

Ejemplo de respuesta

{
  "id": "17911496353086895"
}

Responder a @menciones de textos

Si te suscribes al campo mentions, enviamos al extremo una notificación de webhook cuando un usuario @menciona una cuenta empresarial o de creador de Instagram en un comentario o un texto de un objeto multimedia que no es propiedad de la empresa ni del creador.

Por ejemplo, a continuación se incluye un ejemplo de notificación de webhook de @menciones en textos enviada para una cuenta empresarial de Instagram (17841405726653026):

Ejemplo de notificación de webhook de @menciones en textos

[
  {
    "entry": [
      {
        "changes": [
          {
            "field": "mentions",
            "value": {
              "media_id": "17918195224117851"
            }
          }
        ],
        "id": "17841405726653026",
        "time": 1520622968
      }
    ],
    "object": "instagram"
  }
]

Obtener el contenido del texto

Para obtener el contenido del texto, utiliza la propiedad media_id a fin de enviar una consulta al perímetro GET /{ig-user-id}/mentioned_media:

Ejemplo de consulta

GET https://graph.facebook.com/17841405726653026 ?fields=mentioned_media.media_id(17918195224117851){caption,media_type} 

Ejemplo de respuesta

{
  "mentioned_media": {
    "caption": "@bluebottle There can be only one!",
    "media_type": "IMAGE",
    "id": "17918195224117851"
  },
  "id": "17841405726653026"
}

Analizar la carga útil y responder

Al recibir la respuesta, analiza la carga útil de la propiedad caption a fin de determinar si quieres responder al comentario. Para responder, utiliza la propiedad media_id del webhook a fin de enviar una consulta al perímetro POST /{ig-user-id}/mentions:

Ejemplo de consulta

curl -i -X POST \
  -d "media_id=17918195224117851" \
  -d "message=MacLeod%20agrees!" \
  -d "access_token={access-token}" \
  "https://graph.facebook.com/17841405726653026/mentions"

Ejemplo de respuesta

{
  "id": "17911496353086895"
}