Plataforma de Messenger

API de conversaciones para la plataforma de Messenger

En este documento se explica cómo obtener información sobre las conversaciones con mensajes de Instagram y Messenger. Puedes obtener lo siguiente:

  • Una lista de las conversaciones de tu página de Facebook o cuenta profesional de Instagram.
  • Una lista de los mensajes de cada conversación.
  • Detalles sobre cada mensaje, tales como el remitente y la fecha de envío del mensaje.

Antes de empezar

En este tutorial, suponemos que has leído la Información general de la plataforma de Messenger y la Información general de los mensajes de Instagram y que has implementado los componentes necesarios.

Necesitarás lo siguiente:

  • El identificador de la página de Facebook de tu empresa o la página de Facebook que está vinculada a tu cuenta profesional de Instagram.
  • Un identificador de acceso a la página solicitado por un usuario que pueda realizar la tarea MESSAGING o MODERATE en la página.
  • Se necesita acceso avanzado para acceder a las conversaciones entre tu empresa y los usuarios que no tienen ningún rol en tu aplicación de mensajes, cuenta profesional de Instagram, página de Facebook o empresa.

En el caso de las conversaciones de Messenger entre los usuarios y tu página, la aplicación necesitará lo siguiente:

En el caso de las conversaciones con mensajes de Instagram entre los usuarios y tu cuenta profesional de Instagram, la aplicación necesitará lo siguiente:

  • Un identificador de acceso a la página solicitado por un usuario que pueda realizar la tarea MESSAGING en la página vinculada a la cuenta empresarial de Instagram.
  • Los permisos instagram_basic, instagram_manage_messages y pages_manage_metadata.
  • Tu aplicación debe pertenecer a una empresa verificada.

Limitaciones

  • En los datos devueltos en una llamada a la API o en la notificación de webhooks, solo se incluirá la URL de la imagen o el vídeo de un recurso compartido.
  • Si tus cuentas se vinculan con claves privadas, como un correo electrónico o un número de teléfono, no podrás recuperar las conversaciones entre dichas cuentas. Solo estarán disponibles las conversaciones entre un usuario de Facebook y una cuenta de Instagram. Este problema se resolverá cuando se haya aprobado el acceso avanzado para tu aplicación. Si tienes varias cuentas vinculadas en el Centro de cuentas de la aplicación de Instagram, podrás recuperar las conversaciones entre todas las cuentas vinculadas.
  • Las conversaciones que se encuentren en la carpeta de solicitudes y que no hayan estado activas durante 30 días no se devolverán en las llamadas a la API.

Puedes utilizar esta API para la sincronización de la bandeja de entrada en conversaciones pasadas si una cuenta empresarial de Instagram se ha conectado recientemente a tu aplicación.

Obtener una lista de conversaciones

Para obtener una lista de conversaciones, envía una solicitud GET al extremo /PAGE-ID/conversations e incluye el parámetro platform establecido en instagram o messenger.

Ejemplo de solicitud

Se ha aplicado formato para mejorar la legibilidad
curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/conversations
    ?platform=PLATFORM
    &access_token=PAGE-ACCESS-TOKEN"

Cuando esta operación se completa correctamente, la aplicación recibirá un objeto JSON con una lista de los identificadores de las conversaciones que hayas entablado con un usuario y la hora de envío del mensaje más reciente.

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

Buscar una conversación con un usuario concreto

Para obtener una conversación entre tu cuenta profesional de Instagram o página de Facebook y un usuario concreto, envía una solicitud GET al extremo /PAGE-ID/conversations con el parámetro platform y los parámetros user_id establecidos en el identificador específico de Instagram o el identificador específico de la página del usuario.

Ejemplo de solicitud

Se ha aplicado formato para mejorar la legibilidad
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"

Cuando esta operación se completa correctamente, la aplicación recibirá el identificador de la conversación.


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

Obtener una lista de mensajes de una conversación

Para obtener una lista de los mensajes de una conversación, envía una solicitud GET al extremo /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"

Cuando esta operación se completa correctamente, la aplicación recibirá una lista de identificadores de mensajes y la hora de creación de cada mensaje.

{
  "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", 
}

Obtener información sobre un mensaje

Para obtener información sobre un mensaje (como el remitente, el destinatario y el contenido del mensaje), envía una solicitud GET al extremo /MESSAGE-ID con los campos que te interesen.

Los campos predeterminados son id y created_time.

Nota: Las consultas al extremo /CONVERSATION-ID devolverán los identificadores de todos los mensajes de una conversación. Sin embargo, solo puedes obtener detalles de los 20 mensajes más recientes de la conversación. Si consultas un mensaje anterior a los 20 últimos, verás un error en el que se indica que el mensaje se ha eliminado. 

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"

Cuando esta operación se completa correctamente, la aplicación recibirá la respuesta JSON siguiente. En este ejemplo, un cliente envía 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 las siguientes referencias:

Ayuda para desarrolladores