Configurar webhooks para Instagram

Los webhooks para Instagram te permiten recibir notificaciones en tiempo real cuando alguien comenta en los objetos multimedia de los usuarios de tu app, cuando menciona con @ a los usuarios de tu app o cuando vencen las historias de los usuarios de tu app.

Recibir notificaciones de webhook en tiempo real

Para recibir notificaciones de webhook en tiempo real, es necesario cumplir con los siguientes requisitos:

• Es necesario que la app tenga configurados los webhooks de Instagram y esté suscrita a los campos adecuados en el panel de apps.
• Es necesario que las apps de consumidor se encuentren en modo activo.
• Las apps de negocios deben contar con permisos que tengan el nivel de acceso avanzado. Puedes solicitar el acceso avanzado de permisos de la siguiente manera:

• El usuario de la app debe haber concedido a tu app los permisos correspondientes (instagram_manage_insights para Historias, instagram_manage_comments para comentarios y @menciones).
• La página conectada a la cuenta del usuario de la app debe tener las suscripciones a la página activadas.
• La empresa conectada a la página del usuario de la app debe estar verificada.
• Es necesario que el propietario del objeto multimedia en el cual aparece el comentario o la @mención no haya configurado su cuenta como privada.

Limitaciones

• Las notificaciones de webhooks de comentarios sobre álbumes no incluyen el identificador del álbum. Para obtener el identificador del álbum, consulta el identificador del comentario en el webhook y solicita el campo media.
• Las apps no reciben una notificación de webhooks si el objeto multimedia en el que aparece el comentario o la @mención se creó con una cuenta privada.
• Las estadísticas de historias que tengan un recuento inferior a 5 devuelven el valor -1.
• Las apps solo recibirán notificaciones de webhooks por los comentarios en el contenido multimedia de Instagram en vivo si se está transmitiendo dicho contenido.
• No se admiten reels.
• Es necesario que tu app haya completado correctamente la revisión de apps (acceso avanzado) para recibir notificaciones de webhooks correspondientes a los campos comments y live_comments.

Paso 1: Crear un punto de conexión

Crea un punto de conexión que acepte y procese webhooks. Durante la configuración, selecciona el objeto API Graph de Instagram, haz clic en Configurar y suscribe uno o varios campos de Instagram.

Campos de Instagram

Paso 2: Activar suscripciones a la página

Tu app debe activar las suscripciones a la página en la página conectada a la cuenta del usuario de la app. Para ello, debes enviar una solicitud POST al perímetro Apps suscritas a la página y suscribirte a cualquier campo de la página.

Requisitos del punto de conexión

• Token de acceso a la página del usuario de la app
• pages_manage_metadata

Sintaxis de la solicitud

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

Parámetros de la solicitud

Tu app no recibe notificaciones de los cambios que se realicen en un campo, a menos que configures las suscripciones a la página en el panel de apps 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 comunes

Capturar las estadísticas de historias

Si te suscribes al campo story_insights, una vez que la historia caduca, enviamos a tu punto de conexión una notificación de webhook que contiene las métricas de la interacción de los usuarios con la historia.

Ejemplo de carga útil de una notificación de estadísticas 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 en comentarios

Si te suscribes al campo mentions, enviamos a tu punto de conexión una notificación de webhook cuando un usuario de Instagram @menciona una cuenta comercial o de creador de Instagram en un comentario o texto.

Aquí puedes ver un ejemplo del contenido de una notificación de webhook generada en respuesta a un comentario enviado a una cuenta comercial de Instagram (17841405726653026):

Ejemplo de carga útil de una notificación de @mención en un comentario

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

Obtener el contenido del comentario

A fin de obtener el contenido del comentario, usa la propiedad comment_id para consultar el 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 de la notificación y responder

Cuando obtengas la respuesta, analiza la carga útil de la propiedad text a fin de determinar si quieres responder el comentario. Para responderlo, usa los valores de la propiedad caption_id y media_id de la carga útil de la notificación de webhook con el objetivo de consultar el punto de conexión 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 en textos

Si te suscribes al campo mentions, enviamos a tu punto de conexión una notificación cuando un usuario @menciona una cuenta comercial o de creador de Instagram en un comentario o un texto de un objeto multimedia que no pertenece al creador o la empresa.

Aquí puedes ver un ejemplo de carga útil de una notificación de webhook generada en respuesta a una @mención en texto enviada a una cuenta comercial de Instagram (17841405726653026):

Ejemplo de carga útil de notificación de webhook de @mención en texto

[
  {
    "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, usa la propiedad media_id a fin de consultar el 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 de la notificación y responder

Cuando obtengas la respuesta, analiza la carga útil de la propiedad caption para determinar si quieres responder el comentario. Para responderlo, usa la propiedad media_id del webhook para consultar el 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"
}