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 effectuer des requêtes HTTP. Pour en savoir plus sur nos collections Postman, veuillez consulter notre guide Utilisation de Postman,

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

Prérequis

Pour suivre ce guide, vous aurez besoin 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 gérer les demandes de message privé

Dans cet exemple, en une seule requête, nous créerons une nouvelle conversation de groupe et y ajouterons 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 afin de simplifier le processus. Une collection d’exemples de requêtes X API v2, rédigée par XDev, 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 détails liés à 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 dans votre environnement Postman, 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, et vous pouvez mettre à jour quelques paramètres pour renseigner les détails 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 l’entrée et la sortie des participants à la conversation.

Comme la création de conversations de groupe est une nouvelle fonctionnalité intéressante de la X API v2, cet exemple s’y concentrera. 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 avez l’autorisation de le faire. Pour réussir une requête vers cet endpoint, nous utiliserons 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 détails d’authentification au niveau du dossier.

Accédez au dossier “Manage Direct Messages”, sélectionnez l’onglet “Authorization” et confirmez que 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 “header Prefix” est défini sur Bearer.

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

1. Créez un nom de jeton, par exemple “Manage DMs”.

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 et 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 et 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 et 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 cliquez 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 jeton.

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, vous devrez vous connecter, dans Postman, au compte X pour le compte duquel vous essayez de publier.

Maintenant que ces détails OAuth 2.0 ont été définis au niveau du dossier, ouvrez chacun des exemples, puis leur onglet « Authorization », et vérifiez que le champ Type est réglé sur « Inherit auth from parent ».

Notez que ce token expirera bientôt et que vous devrez en générer un nouveau en cliquant sur le bouton « Get New Access Token ». Cliquer sur ce bouton lancera le processus « Sign-in with X » et générera un nouveau token pour effectuer des requêtes.

​

Étape 3 : spécifier les participants à la conversation de Message privé et le contenu du message

Accédez à l’onglet « Body » et mettez à jour l’objet JSON d’exemple. Définissez l’attribut participant_ids sur les comptes auxquels vous souhaitez envoyer le Message privé.

{ "message": {"text": "Hello to just you two, this is a new group conversation."}, "participant_ids": ["944480690","906948460078698496"], "conversation_type": "Group" }

​

Quatrième étape : envoyez votre requête et passez en revue la réponse

Une fois tout configuré, cliquez sur le bouton « Send » ; vous recevrez une réponse semblable à l’exemple ci-dessous. Rappel : si votre access token a expiré depuis sa création ci-dessus, vous pouvez revenir à l’onglet Authorization du dossier et cliquer sur « Get New Access Token » pour générer un nouveau jeton.

{
   "data": {
       "dm_conversation_id": "1582103724607971328",
       "dm_event_id": "1582103724607971332"
   }
}

Si l’objet « data » de la réponse contient un dm_conversation_id et un dm_event_id, vous avez bien créé une nouvelle conversation de Messages privés. Pour commencer à consulter les événements associés à cette conversation, rendez-vous sur le guide Bien démarrer de la recherche de Messages privés.

​

Cinquième étape : ajouter un autre message à cette conversation de groupe

Sélectionnez maintenant l’exemple « Add DM to conversation », puis l’onglet « Params ». Sous « Path Variables », mettez à jour dm_conversation_id avec l’ID de la conversation que vous avez créée ci-dessus.

Key	Value
dm_conversation_id	1582103724607971328

En utilisant cet ID de conversation, le chemin de requête se résoudra en : https://api.x.com/2/dm_conversations/1582103724607971328/messages

Mettez également à jour l’onglet « Body » avec un JSON de requête contenant le texte du message que vous souhaitez envoyer :

{
   "text": "Ajout d'un nouveau message à notre conversation de groupe..."
}

Une fois tout configuré, cliquez sur le bouton « Send », et vous recevrez une réponse similaire à l’exemple suivant :

{
   "data": {
       "dm_conversation_id": "1582103724607971328",
       "dm_event_id": "1582106224379559940"
   }
}