Plateforme Messenger

API Conversations pour la plateforme Messenger

Ce document explique comment obtenir des informations sur vos conversations dans Messenger et Instagram Messaging. Vous pouvez obtenir :

  • Une liste des conversations pour votre Page Facebook ou votre compte professionnel Instagram
  • Une liste des messages dans chaque conversation
  • Des détails sur chaque message, y compris la date d’envoi et l’expéditeur

Avant de commencer

Ce tutoriel suppose que vous avez lu la Présentation de la plateforme Messenger et la Présentation d’Instagram Messaging et que vous avez implémenté les composants nécessaires.

Vous aurez besoin des éléments suivants :

  • L’ID de la Page Facebook de votre entreprise ou de la Page Facebook liée à votre compte professionnel Instagram
  • Un token d’accès de Page demandé par une personne autorisée à effectuer la tâche MESSAGING ou MODERATE sur la Page
  • Un accès avancé est nécessaire pour accéder aux conversations entre votre entreprise et les personnes qui n’ont pas de rôle sur votre application de messages, votre compte professionnel Instagram, votre Page Facebook ou votre entreprise

Pour les conversations Messenger entre les utilisateur·ices et votre Page, votre application aura besoin de ce qui suit :

Pour les conversations Instagram Messaging entre les utilisateur·ices et votre compte professionnel Instagram, votre application aura besoin de ce qui suit :

  • Un token d’accès à la Page demandé par une personne qui peut effectuer la tâcheMESSAGING sur la Page liée à votre compte business Instagram
  • Les autorisations instagram_basic, instagram_manage_messages et pages_manage_metadata
  • Votre application doit être détenue par une entreprise vérifiée

Limites

  • Seule l’URL de l’image ou de la vidéo d’un partage sera incluse dans les données renvoyées lors d’un appel à l’API ou dans la notification webhooks.
  • Si vos comptes sont associés à l’aide de clés privées, telles qu’un e-mail ou un numéro de téléphone, vous ne pourrez pas récupérer les conversations entre ces comptes. Seules les conversations entre un·e utilisateur·ice Facebook et un compte Instagram seront disponibles. Ce problème disparaît lorsqu’un accès avancé est accordé à votre application. Si vous avez plusieurs comptes associés dans l’Espace Comptes sur l’application Instagram, vous pourrez récupérer les conversations entre tous les comptes associés.
  • Les conversations qui se trouvent dans le dossier des invitations et qui n’ont pas été actives pendant 30 jours ne seront pas renvoyées dans les appels d’API.

Vous pouvez utiliser cette API pour synchroniser les anciennes conversations de la messagerie quand un compte business Instagram se connecte pour la première fois à votre application.

Obtenir la liste des conversations

Pour obtenir la liste des conversations, envoyez une requête GET au point de terminaison /PAGE-ID/conversations et incluez le paramètre platform défini sur instagram ou messenger.

Exemple de requête

Formaté pour plus de lisibilité
curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/conversations
    ?platform=PLATFORM
    &access_token=PAGE-ACCESS-TOKEN"

En cas de succès, votre application recevra un objet JSON contenant une liste d’ID pour les conversations que vous entretenez avec une personne et l’heure du dernier message envoyé.

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

Trouver une conversation avec un·e utilisateur·ice spécifique

Pour converser entre votre compte professionnel Instagram ou une Page Facebook et une personne, envoyez une requête GET au point de terminaison /PAGE-ID/conversations avec le paramètre platform et les paramètres user_id définis sur l’ID spécifique d’Instagram ou de la Page de la personne.

Exemple de requête

Formaté pour plus de lisibilité
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"

En cas de succès, votre application recevra l’ID de la conversation.


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

Obtenir la liste des messages d’une conversation

Pour obtenir la liste des messages d’une conversation, envoyez une requête GET au point de terminaison /CONVERSATION-ID et incluez le champ messages.

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

En cas de succès, votre application recevra une liste d’ID de messages et l’heure de création de chaque message.

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

Obtenir des informations sur un message

Pour obtenir des informations sur un message, telles que l’expéditeur·ice, le/la destinataire et le contenu du message, envoyez une requête GET au point de terminaison /MESSAGE-ID avec les champs qui vous intéressent.

Les champs par défaut sont id et created_time.

Remarque : les requêtes envoyées au point de terminaison /CONVERSATION-ID renvoient tous les ID de message d’une conversation. Cependant, vous pourrez uniquement obtenir les détails des 20 derniers messages de la conversation. Si vous recherchez un message plus ancien, une erreur indiquant que le message a été supprimé apparaîtra. 

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"

En cas de succès, l’application reçoit la réponse JSON ci-dessous. Dans cet exemple, un·e client·e a envoyé un message en texte brut à votre compte professionnel 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!"
}

En savoir plus

Consultez nos pages de référence pour :

Assistance pour les équipes chargées du développement