Passer au contenu principal
Les endpoints des Messages privés v2 introduisent les conversations et les événements de conversation en tant qu’objets centraux de la X API, et établissent une distinction entre les conversations 1‑1 et les conversations de groupe. Les conversations 1‑1 ont toujours deux, et seulement deux, participants, tandis que les conversations de groupe peuvent en avoir deux ou plus, avec des appartenances susceptibles d’évoluer.    Cette page présente plusieurs outils et concepts clés dont vous devez tenir compte lors de l’intégration des endpoints de recherche des Messages privés à votre système. Nous avons divisé la page en deux sections :

​
Concepts clés

​
Conversations de Messages privés

Tous les Messages privés font partie d’une conversation de Messages privés. Ces conversations peuvent être en tête-à-tête ou en groupe. Cette version fournit les endpoints de base nécessaires pour créer des Messages privés et récupérer les événements associés aux conversations de Messages privés. Toutes les conversations ont un dm_conversation_id unique, et les événements qui composent une conversation ont chacun un dm_event_id unique.   Les endpoints de recherche des Messages privés offrent des méthodes pour récupérer les événements associés aux conversations. Ces endpoints GET permettent de récupérer les messages qui composent une conversation et, pour les conversations de groupe, de savoir qui a rejoint ou quitté ces conversations. Cette première version de la recherche de Messages privés inclut trois méthodes GET :
  • GET /2/dm_conversations/with/:participant_id/dm_events - Récupère les événements de Messages privés associés à une conversation en tête-à-tête. Le paramètre de chemin :participant_id est l’ID utilisateur numérique du compte en conversation avec l’utilisateur authentifié qui effectue cette requête.  
  • GET /2/dm_conversations/:dm_conversation_id/dm_events - Récupère les événements de Messages privés associés à un ID de conversation spécifique, tel qu’indiqué par le paramètre de chemin :dm_conversation_id. Les IDs de conversations en tête-à-tête et de groupe sont pris en charge.  
  • GET /2/dm_events - Récupère les événements de Messages privés associés à l’utilisateur authentifié, pour les conversations en tête-à-tête comme de groupe. Des événements datant jusqu’à 30 jours sont disponibles.  
Ces endpoints GET prennent tous en charge la récupération de dm_events par type d’événement via le paramètre de requête event_types. Actuellement, trois types d’événements de conversation sont pris en charge :
  • MessageCreate - Créé lorsqu’un nouveau Message privé est envoyé. Cet objet d’événement peut inclure l’heure et le texte du message, ainsi que l’ID du compte de l’expéditeur, et les IDs de la conversation et de l’événement. 
  • ParticipantsJoin - Créé lorsqu’un nouveau participant rejoint une conversation de groupe. Cet objet dm_event inclut l’ID du participant qui rejoint, ainsi que l’horodatage created_at et le sender_id de l’événement « invite ». 
  • ParticipantsLeave - Créé lorsqu’un participant quitte une conversation. Cet objet d’événement inclut l’ID du participant qui quitte, ainsi que l’heure de l’événement. 
Pour plus d’informations, consultez les références de l’API de recherche des Messages privés.

​
Identifiants de conversation et d’événement partagés entre v1.1 et v2

Un concept important est que les identifiants de conversation et d’événement sont partagés entre les versions v1.1 et v2 de la plateforme X. Cela signifie que les deux versions peuvent être utilisées conjointement. Par exemple, les endpoints des Messages privés v1.1 proposent des méthodes pour récupérer un seul événement et pour supprimer des événements, des méthodes qui ne sont pas encore disponibles avec v2. Étant donné que les id sont communs entre v1.1 et v2, vous pouvez effectuer des requêtes v1.1 à partir des id fournis par v2, ou en vous référant aux identifiants de conversation affichés dans les URL de conversation de l’application X.  

​
Champs et expansions des événements de messages privés

La X API v2 permet aux utilisateurs de sélectionner précisément quelles data ils souhaitent récupérer depuis l’API à l’aide d’un ensemble d’outils appelés fields et expansions. Par exemple, les endpoints de recherche de messages privés prennent en charge les champs dm_events suivants :
  • id, event_type et text sont les valeurs par défaut pour les événements MessageCreate. 
  • id, event_type et participant_ids sont les valeurs par défaut pour les événements ParticipantsJoin et ParticipantsLeave.
  • dm_conversation_id et created_at sont disponibles pour tous les événements.
  • attachments et referenced_tweets sont disponibles pour les événements MessageCreate. 
  • sender_id est disponible pour les événements MessageCreate et ParticipantsJoin. 
  • participant_ids est disponible pour les événements ParticipantsJoin et ParticipantsLeave. 
De plus, les endpoints de recherche de messages privés prennent en charge les expansions suivantes :
  • sender_id - Étend l’objet utilisateur associé à la personne qui a envoyé le message ou qui a invité quelqu’un à la conversation. 
  • referenced_tweets.id - Étend l’Objet Post si le texte du message privé inclut un lien vers un Post. 
  • attachments.media_keys - Étend l’objet Media si le message privé inclut une pièce jointe média. 
  • participant_ids - Étend l’objet utilisateur associé à la personne qui a rejoint ou quitté une conversation de groupe.
Comme les expansions incluent des objets Posts, utilisateurs et Media, vous pouvez également utiliser les paramètres de requête tweet.fields, user.fields et media.fields. Consultez notre guide sur la façon d’utiliser les fields et expansions pour plus d’informations.

​
Types d’événements de conversation

Vous trouverez ci-dessous des exemples d’objets JSON pour les types d’événements de messages privés MessageCreate, ParticipantsJoin et ParticipantsLeave. Champs disponibles pour l’objet dm_event : id, text, event_type, dm_conversation_id, created_at, sender_id, attachments, referenced_tweets, participant_ids. Consultez la section Fields and Expansion pour plus de détails sur la sélection de ces champs dans vos requêtes. Exemple d’événement MessageCreate : Avec tous les champs dm_event spécifiés, voici la réponse pour un message privé texte simple : { "text": "Hi everyone.", "sender_id": "944480690", "dm_conversation_id": "1578398451921985538", "id": "1582838499983564806", "event_type": "MessageCreate", "created_at": "2022-10-19T20:58:00.000Z" } Exemple d’événement ParticipantsJoin : Avec tous les champs dm_event spécifiés, voici la réponse pour un participant rejoignant une conversation : { "participant_ids": [ "944480690" ], "sender_id": "17200003", "dm_conversation_id": "1578398451921985538", "id": "1582835469712138240", "event_type": "ParticipantsJoin", "created_at": "2022-10-19T20:45:58.000Z" } Exemple d’événement ParticipantsLeave : Avec tous les champs dm_event spécifiés, voici la réponse pour un participant quittant une conversation : { "participant_ids": [ "944480690" ], "dm_conversation_id": "1578398451921985538", "id": "1582838535115067392", "event_type": "ParticipantsLeave", "created_at": "2022-10-19T20:58:09.000Z" }

​
Authentification

Tous les endpoints de la X API v2 exigent que vous authentifiiez vos requêtes à l’aide d’un ensemble d’identifiants, également appelés clés et jetons. Tous les Messages privés sont confidentiels et nécessitent une autorisation utilisateur pour y accéder.  Ces endpoints de Messages privés nécessitent l’utilisation de OAuth 2.0 Authorization Flow with PKCE ou de 1.0a User Context, ce qui signifie que vous devez utiliser un ensemble d’API Keys et des user Access Tokens pour effectuer une requête réussie. Les Access Tokens doivent être associés à l’utilisateur pour le compte duquel vous effectuez la demande. Si vous souhaitez générer un ensemble d’Access Tokens pour un autre utilisateur, celui-ci doit autoriser ou authentifier votre App à l’aide du flux OAuth à 3 étapes. Veuillez noter que le user-context OAuth peut être délicat à utiliser. Si vous n’êtes pas familier avec cette méthode d’authentification, nous vous recommandons d’utiliser une bibliothèque ou un outil comme Postman pour authentifier correctement vos requêtes.  OAuth 2.0 Authorization Code with PKCE offre un meilleur contrôle de la portée d’une application et des flux d’autorisation sur plusieurs appareils. OAuth 2.0 vous permet de choisir des scopes granulaires spécifiques qui vous accordent des autorisations précises au nom d’un utilisateur. Les endpoints de recherche de Messages privés requièrent ces scopes : dm.read, post.read, user.read Pour activer OAuth 2.0 dans votre App, vous devez l’activer dans les paramètres d’authentification de votre App, disponibles dans la section App settings du developer portal.

​
Developer portal, Projects, and developer Apps

Pour obtenir un ensemble d’informations d’authentification compatibles avec les endpoints de la X API v2, vous devez disposer d’un compte développeur approuvé, créer un Project au sein de ce compte, puis créer une App développeur dans ce Project. Vous pourrez ensuite retrouver vos clés et jetons dans votre App développeur. 

​
Limites de taux

Chaque jour, des milliers de développeurs envoient des requêtes à la X API. Pour gérer le volume de ces requêtes, des limites de taux sont appliquées à chaque endpoint afin de restreindre le nombre de requêtes que vous pouvez effectuer pour le compte de votre App ou d’un utilisateur authentifié. Les endpoints de consultation des Messages privés sont soumis à des limites de taux au niveau utilisateur, ce qui signifie que l’utilisateur authentifié pour lequel vous effectuez la requête ne peut effectuer qu’un certain nombre de requêtes avec votre X App. Il existe une limite de taux utilisateur de 300 requêtes par 15 minutes pour les méthodes GET. Ces limites de taux sont partagées entre les endpoints GET.  Ces endpoints utilisent la pagination afin que les réponses soient renvoyées rapidement. Lorsque le nombre de résultats dépasse ce qui peut être envoyé dans une seule réponse (jusqu’à 100 événements), vous devrez paginer. Utilisez le paramètre max_results pour indiquer le nombre de résultats à renvoyer par page et le paramètre pagination_token pour récupérer la page suivante. Pour en savoir plus, consultez notre guide de pagination. Outils utiles Voici quelques outils que nous vous encourageons à explorer lorsque vous travaillez avec les endpoints de recherche de Messages privés :  Postman Postman est un excellent outil pour tester un endpoint. Chaque requête Postman inclut tous les paramètres de chemin et de corps afin de vous aider à comprendre rapidement ce qui est disponible. Pour en savoir plus sur nos collections Postman, veuillez consulter notre page Utiliser Postman.  Exemples de code Des exemples de code Python pour les endpoints Messages privés de la v2 sont disponibles dans notre dépôt X API v2 sample code GitHub. Le dossier “Manage-Direct-Messages” contient des exemples pour les méthodes POST, et le dossier “Direct-Messages-lookup” contient des exemples pour les méthodes GET. XDev Software Development Kits (SDKs) Ces bibliothèques sont en cours de mise à jour pour les endpoints Messages privés de la v2 et devraient être prêtes bientôt : Bibliothèques tierces Un nombre croissant de bibliothèques tierces sont développées par notre communauté. Elles sont conçues pour vous aider à démarrer, et plusieurs devraient bientôt prendre en charge les endpoints Messages privés de la v2. Vous pouvez trouver une bibliothèque compatible avec les endpoints v2 en recherchant l’étiquette de version appropriée.
⌘I