Plataforma de Messenger

API de conversaciones de la plataforma de Messenger

Este documento explica cómo obtener información sobre las conversaciones de Messenger y de mensajes de Instagram. Es posible obtener la siguiente información:

  • Una lista de conversaciones de la página de Facebook o tu cuenta profesional de Instagram
  • Una lista de mensajes dentro de cada conversación
  • Información detallada acerca de cada mensaje, que incluye cuándo se envió el mensaje y quién lo envió

Antes de empezar

En este tutorial, se asume que leíste el Resumen de la plataforma de Messenger y el Resumen de mensajes de Instagram, y que implementaste los componentes necesarios.

Necesitarás lo siguiente:

  • El identificador de la página de Facebook de tu negocio o la página de Facebook vinculada a la cuenta profesional de Instagram
  • Un token de acceso a la página solicitado a una persona que pueda realizar la tarea MESSAGING o MODERATE en la página
  • Se requiere acceso avanzado para acceder a las conversaciones entre el negocio y las personas que no tienen un rol en tu app de mensajes, tu cuenta profesional de Instagram, tu página de Facebook o tu negocio

A fin de que se produzcan conversaciones de Messenger entre las personas y tu página, tu app necesitará lo siguiente:

A fin de que se produzcan conversaciones de mensajes de Instagram entre las personas y la cuenta profesional de Instagram, tu app necesitará lo siguiente:

  • Un token de acceso a la página solicitado por una persona que pueda realizar la tarea MESSAGING en la página vinculada a tu cuenta comercial de Instagram
  • Los permisos instagram_basic, instagram_manage_messages y pages_manage_metadata
  • Tu app debe ser propiedad de un negocio verificado

Limitaciones

  • Solo se incluirá la imagen o la URL del video para compartir en los datos que se devuelven en una llamada a la API o en la notificación de webhooks.
  • Si tus cuentas están vinculadas usando claves privadas, como un correo electrónico o un número de teléfono, no podrás recuperar las conversaciones entre estas cuentas. Solo estarán disponibles las conversaciones entre un usuario de Facebook y una cuenta de Instagram. Este problema se resolverá cuando tu app tenga aprobado el acceso avanzado. Si tienes múltiples cuentas vinculadas en el centro de cuentas de la app de Instagram, podrás recuperar conversaciones entre todas las cuentas vinculadas.
  • No se devolverán en las llamadas a la API las conversaciones que se encuentren en la carpeta de solicitudes y que no hayan estado activas en los últimos 30 días.

Puedes usar esta API para sincronizar la bandeja de entrada de las conversaciones previas cuando una cuenta comercial de Instagram se conecta a tu app por primera vez.

Obtén una lista de conversaciones

Para obtener una lista de las conversaciones, envía una solicitud GET al punto de conexión /PAGE-ID/conversations e incluye el parámetro platform configurado en instagram o messenger.

Ejemplo de solicitud

El formato se modificó para facilitar la lectura.
curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/conversations
    ?platform=PLATFORM
    &access_token=PAGE-ACCESS-TOKEN"

Si se envía correctamente, tu app recibirá un objeto JSON con una lista de identificadores de las conversaciones que tuvieron lugar entre tú y una persona y la última vez que se envió un mensaje.

{
  "data": 
    {
      "id": "CONVERSATION-ID-1",  
      "updated_time": "UNIX-TIMESTAMP"
    },
    {
      "id": "CONVERSATION-ID-2",   
      "updated_time": "UNIX-TIMESTAMP"
    }
    ...
  ]
}

Encuentra una conversación con un usuario específico

A fin de obtener una conversación entre tu cuenta profesional de Instagram o página de Facebook y una persona específica, envía una solicitud GET al punto de conexión user_id con el parámetro /PAGE-ID/conversations y los parámetros platform configurados en el identificador específico de Instagram o de la página de la persona.

Ejemplo de solicitud

El formato se modificó para facilitar la lectura.
curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/conversations
    ?platform=PLATFORM
    &user_id=INSTAGRAM-OR-PAGE-SCOPED-ID
    &access_token=PAGE-ACCESS-TOKEN"

Si se envía correctamente, tu app recibirá el identificador de la conversación.


{
  "data": [
      {
        "id": "CONVERSATION-ID"
      },
  ]
}

Obtén una lista de los mensajes de una conversación

Para obtener una lista de mensajes en una conversación, envía una solicitud GET al punto de conexión /CONVERSATION-ID e incluye el campo messages.

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/CONVERSATION-ID
    ?fields=messages
    &access_token=PAGE-ACCESS-TOKEN"

Si se envía correctamente, tu app recibirá una lista de los identificadores de mensajes y el horario en que se crearon los mensajes.

{
  "messages": {
    "data": [
      {
        "id": "Message ID-1",      
        "created_time": "UNIX-TIMESTAMP-MOST-RECENT-MESSAGE"  
      },
      {
        "id": "Message ID-2",
        "created_time": "UNIX-TIMESTAMP"
      },
      {
        "id": "Message ID-3",
        "created_time": "UNIX-TIMESTAMP"
      },
...
    ]
  },
  "id": "Conversation ID", 
}

Obtén información acerca de un mensaje

Para obtener información sobre un mensaje, como emisor, destinatario y contenido del mensaje, envía una solicitud GET al punto de conexión /MESSAGE-ID e incluye los campos que deseas.

Los campos predeterminados son id y created_time.

Nota: Las consultas al punto de conexión /CONVERSATION-ID devolverán todos los identificadores de mensaje de una conversación. Sin embargo, solo podrás obtener información de los últimos 20 mensajes de la conversación. Si consultas un mensaje anterior a los últimos 20, verás un error que indica que el mensaje se eliminó . 

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/MESSAGE-ID
    ?fields=id,created_time,from,to,message
    &access_token=PAGE-ACCESS-TOKEN"

Si la operación se completa con éxito, la app recibirá la siguiente respuesta JSON. En este ejemplo, un cliente envió un mensaje de texto sin formato a tu cuenta profesional de Instagram.

{
  "id": "aWdGGiblWZ...",
  "created_time": "2022-07-12T19:11:07+0000",
  "to": {
    "data": [
      {
        "username": "INSTAGRAM-PROFESSIONAL-ACCOUNT-USERNAME",
        "id": "INSTAGRAM-PROFESSIONAL-ACCOUNT-ID"
      }
    ]
  },
  "from": {
    "username": "INSTAGRAM-USERNAME",
    "id": "INSTAGRAM-SCOPED-ID"
  },
  "message": "Hi Kitty!"
}

Más información

Consulta nuestra referencia para obtener información sobre los siguientes temas:

Ayuda para desarrolladores