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:

Si los permisos de la aplicación no tienen un nivel de acceso avanzado, la aplicación no recibe notificaciones de webhooks.

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 (Advanced Access) para recibir notificaciones de los webhooks de los campos de webhook comments y live_comments.

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

Campo	Descripción	Permisos necesarios
`comments`	Comentarios en contenido multimedia de Instagram propiedad del usuario de Instagram de la aplicación. Los valores de `ad_id` y `ad_title` se devolverán en el objeto multimedia cuando un usuario comente en una publicación promocionada de Instagram o una publicación publicitaria de Instagram. Esto puede generar notificaciones de webhook duplicadas.	instagram_manage_comments pages_manage_metadata pages_read_engagemento pages_show_list
`live_comments`	Comentarios en contenido multimedia publicado de Instagram propiedad del usuario de Instagram de la aplicación.	instagram_manage_comments pages_manage_metadata pages_read_engagemento pages_show_list
`mentions`	@menciones del usuario de Instagram de la aplicación en un comentario.	instagram_manage_comments pages_manage_metadata pages_read_engagemento pages_show_list
`story_insights`	Métricas que describen las interacciones en una historia. Se envían una hora después de que caduque la historia.	instagram_manage_insights pages_manage_metadata pages_read_engagemento pages_show_list

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

Marcador de posición del valor	Descripción del valor
`{page_id}`	Identificador de la página conectada a la cuenta del usuario de la aplicación.
`{access_token}`	Identificador de acceso a la página del usuario de la aplicación.
`{fields}`	Un campo de página (p. ej., `feed`).

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/v19.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"
}