Démarrage rapide

​

Bien démarrer avec les endpoints de gestion des Messages privés

Ce guide de démarrage rapide vous aidera à effectuer votre première requête vers les endpoints de Messages privés à l’aide de Postman, un outil pour gérer et exécuter des requêtes HTTP. Pour en savoir plus sur nos collections Postman, veuillez consulter notre guide Utiliser Postman.

Veuillez consulter notre dépôt GitHub Exemples de code X API v2 si vous souhaitez examiner des exemples en Python. Par ailleurs, les kits de développement logiciel (SDK) de la X Developer Platform seront mis à jour pour prendre en charge ces endpoints de Messages privés.  

Prérequis

Pour suivre ce guide, vous devez disposer d’un ensemble de clés et jetons afin d’authentifier votre requête. Vous pouvez générer ces clés et jetons en suivant ces étapes :

• Inscrivez-vous à un compte développeur et obtenez l’approbation.
• Créez un Project et une App développeur associée dans le developer portal.
• Accédez à la page « Keys and tokens » de votre App pour générer les informations d’identification requises. Assurez-vous d’enregistrer toutes les informations d’identification dans un emplacement sécurisé.

​

Étapes pour créer des requêtes de recherche de messages privés

Dans cet exemple, en une seule requête, nous allons créer une nouvelle conversation de groupe et y ajouter un premier message. Nous ajouterons ensuite un deuxième message à la conversation créée.

​

Première étape : commencer avec un outil ou une bibliothèque

Pour commencer à travailler avec les endpoints de gestion des Messages privés, nous allons utiliser l’outil Postman pour simplifier le processus. Une collection d’exemples de requêtes X API v2, rédigée par XDevelopers, sera utilisée pour explorer six endpoints permettant de créer de nouveaux Messages privés et de lister les événements des conversations en Messages privés.

Bien que la majeure partie de la collection soit préremplie, vous devrez fournir quelques informations basées sur la X App créée pour héberger ces requêtes API. Commençons par charger/mettre à jour la collection.

Pour charger la collection X API v2 de Postman dans votre environnement, veuillez cliquer sur le bouton suivant :

Ajouter X API v2 à Postman

Une fois la collection X API v2 chargée dans Postman, accédez au dossier “Manage Direct Messages”. L’onglet Authorization de ce dossier a été prérempli lorsque c’était possible. Vous devrez mettre à jour quelques paramètres pour renseigner les informations d’authentification de votre X App.

Ce dossier contient également trois endpoints pour créer de nouveaux Messages privés. Notez qu’il existe aussi un dossier “Direct Message lookup” avec trois endpoints disponibles pour récupérer les événements de conversation en Messages privés, notamment l’envoi et la réception de messages, ainsi que les moments où des participants rejoignent et quittent la conversation.

Étant donné que la création de conversations de groupe est une nouvelle fonctionnalité de la X API v2, cet exemple s’y focalise. Nous utiliserons l’exemple “New group DM and conversation”. Cette requête servira à créer une conversation de groupe en Messages privés.

L’étape suivante consiste à s’authentifier auprès de l’endpoint.

​

Deuxième étape : Authentifier votre requête

Pour effectuer correctement une requête vers la X API, vous devez vérifier que vous êtes autorisé à le faire. Pour réussir une requête vers cet endpoint, nous utiliserons l’OAuth 2.0 Authorization Code Flow with PKCE. Vous pouvez générer un access token dans Postman.

Avec Postman, vous pouvez définir la méthode d’authentification au niveau du dossier ou de la requête. Ici, nous allons configurer les paramètres d’authentification au niveau du dossier. Accédez au dossier “Manage Direct Messages”, sélectionnez l’onglet “Authorization” et confirmez que le Type est défini sur “OAuth 2.0”, et que “Add auth data to” est défini sur “Request Headers”. Dans la section “Current Token”, assurez-vous que le “Header Prefix” est défini sur Bearer.

Pour configurer et générer un nouveau token :

1. Créez un nom de token, par exemple “DM lookup”.

2. Confirmez que Grant Type est défini sur Authorization Code (with PKCE).

3. Définissez votre Callback URL. Mettez à jour votre Callback URL pour qu’elle corresponde exactement à la Callback URL associée à votre application dans le v2 Dev Portal. Avec la X App utilisée dans cet exemple, la Callback URL est définie sur https://www.example.com (notez que comme cela doit correspondre exactement, https://example.com ne fonctionnerait pas).

4. Confirmez que Auth URL est défini sur https://x.com/i/oauth2/authorize.

5. Confirmez que Access Token URL est défini sur https://api.x.com/2/oauth2/token.
   Client ID : copiez-collez l’OAuth 2.0 client ID depuis le developer portal.
   Client Secret : vous n’en aurez besoin que si vous utilisez un type d’App qui est un client confidentiel. Le cas échéant, copiez-collez l’OAuth 2.0 Client Secret depuis le developer portal.

6. Confirmez que Scope est défini sur dm.read dm.write tweet.read users.read.

7. Confirmez que State est défini sur “state”.

8. Confirmez que Client Authentication est défini sur Send as Basic Auth header.

9. Cliquez sur “Get New Access Token”, puis sur “Authorize app” dans le cadre du processus “Sign-in with X”.

10. Cliquez sur le bouton “Proceed”, puis sur “Use Token” pour générer un token.

11. Cliquez sur le bouton “Save” pour enregistrer ces paramètres de configuration.

Vous pouvez recevoir un message indiquant que vous n’êtes pas connecté à X. Si vous obtenez cette erreur, connectez-vous dans Postman au compte X pour lequel vous essayez de publier.

Maintenant que ces paramètres OAuth 2.0 ont été définis au niveau du dossier, accédez à chacun des exemples, ouvrez leur onglet “Authorization” et confirmez que leur Type est défini sur “Inherit auth from parent”.

Notez que ce token expirera prochainement et que vous devrez le régénérer en cliquant sur le bouton “Get New Access Token”. Cliquer sur ce bouton déclenchera le processus “Sign-in with X” et générera un nouveau token pour effectuer des requêtes.

​

Étape trois : Récupérer les événements de conversation des Messages privés

Lors de la récupération des événements de conversation de Messages privés avec cet endpoint, vous devez spécifier un ID de conversation. L’ID de conversation fait partie du chemin de l’endpoint : https://api.x.com/2/dm_conversations/:dm_conversation_id/dm_events

Dans Postman, accédez à l’onglet « Params » et saisissez l’ID de la conversation pour laquelle vous souhaitez récupérer des événements dans la section « Path Variables ».

Le paramétrage serait :

Key	Value
dm_conversation_id	1228393702244134912

Avec cette conversation spécifiée, le chemin résultant devient https://api.x.com/2/dm_conversations/1582103724607971328/dm_events

Si vous cliquez sur le bouton « Send », vous recevrez dans votre réponse les champs par défaut de l’objet Message privé : id, text et event_type. Il y aura également un objet « meta » indiquant le nombre de résultats, ainsi que des jetons de pagination permettant de récupérer davantage d’événements s’ils sont disponibles.

{
   "data": [
       {
           "event_type": "MessageCreate",
           "id": "1580705921830768647",
           "text": "bonjour à vous deux, voici une nouvelle conversation de groupe."
       }
   ],
   "meta": {
       "result_count": 1,
       "next_token": "18LAA5FFPEKJA52G0G00ZZZZ",
       "previous_token": "1BLC45FFPEKJA52G0S00ZZZZ"
   }
}

Si vous souhaitez recevoir des champs supplémentaires, vous devrez spécifier ces champs dans votre requête à l’aide des paramètres fields et/ou expansions.

Pour cet exercice, nous demanderons des ensembles supplémentaires de champs de l’objet dm_event :

1. Les champs par défaut de l’objet Direct Message : id, text et event_type.

2. Champs supplémentaires de l’objet Direct Message : dm_conversation_id, created_at, sender_id, attachments, participant_ids, referenced_tweets

Dans Postman, accédez à l’onglet « Params » et ajoutez la paire clé‑valeur suivante au tableau « Query Params » :

Key	Value
dm_event.fields	dm_conversation_id,created_at,sender_id,attachments,participant_ids,referenced_tweets

Vous devriez maintenant voir l’URL suivante à côté du bouton « Send » :

https://api.x.com/2/dm_conversations/:dm_conversation_id/dm_events?dm_event.fields=id,text,event_type,dm_conversation_id,created_at,sender_id,attachments,participant_ids,referenced_tweets

​

Quatrième étape : envoyez votre requête et examinez la réponse

Une fois que tout est en place, cliquez à nouveau sur le bouton « Send », et vous recevrez une réponse similaire à celle ci-dessous. Notez que cette réponse inclut tous les fields dm_event disponibles.

{
   "data": [
       {
           "text": "salut vous deux, voici une nouvelle conversation de groupe.",
           "id": "1580705921830768647",
           "dm_conversation_id": "1580705921830768643",
           "event_type": "MessageCreate",
           "sender_id": "17200003",
           "created_at": "2022-10-13T23:43:54.000Z"
       }
   ],
   "meta": {
       "result_count": 1,
       "next_token": "18LAA5FFPEKJA52G0G00ZZZZ",
       "previous_token": "1BLC45FFPEKJA52G0S00ZZZZ"
   }
}