Guide d’intégration

Concepts clés et bonnes pratiques pour l’envoi de messages privés (DM)

Ce guide présente les principaux concepts à connaître pour intégrer les endpoints de gestion des Messages privés à votre application.

---

Authentification

Les endpoints de DM requièrent une authentification utilisateur :

Méthode	Description
OAuth 2.0 Authorization Code with PKCE	Recommandé
OAuth 1.0a User Context	Compatibilité héritée

L’authentification App-only n’est pas prise en charge. Tous les Messages privés restent privés.

Portées requises (OAuth 2.0)

Portée	Obligatoire pour
dm.write	Envoyer et supprimer des messages
dm.read	Obligatoire avec dm.write
tweet.read	Obligatoire avec les portées dm
users.read	Obligatoire avec les portées dm

---

Aperçu des endpoints

Method	Endpoint	Description
POST	/2/dm_conversations/with/:participant_id/messages	Envoyer un message individuel
POST	/2/dm_conversations	Créer une conversation de groupe
POST	/2/dm_conversations/:dm_conversation_id/messages	Ajouter un message à la conversation
DELETE	/2/dm_events/:event_id	Supprimer un message

---

Envoi de messages

Message individuel

Envoyez un message à un utilisateur spécifique. Ouvre une nouvelle conversation si aucune n’existe :

cURL

shellscript

curl -X POST "https://api.x.com/2/dm_conversations/with/9876543210/messages" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello!"}'

Conversation de groupe

Créez un nouveau groupe et envoyez le premier message :

cURL

shellscript

curl -X POST "https://api.x.com/2/dm_conversations" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_type": "Group",
    "participant_ids": ["944480690", "906948460078698496"],
    "message": {"text": "Bienvenue dans notre groupe !"}
  }'

Le champ conversation_type doit être défini sur "Group" (respect de la casse obligatoire).

Ajouter à une conversation existante

Envoyez un message dans n’importe quelle conversation à laquelle vous participez :

cURL

shellscript

curl -X POST "https://api.x.com/2/dm_conversations/1582103724607971328/messages" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Another message"}'

---

Pièces jointes de médias

Joignez un média (photo, vidéo ou GIF) par message.

1. Téléverser un média

   Utilisez le Media Upload endpoint pour téléverser votre fichier et obtenir un media_id.

2. Inclure dans le message

   {
     "text": "Check out this image!",
     "attachments": [{"media_id": "1583157113245011970"}]
   }
   

• L’utilisateur authentifié doit avoir téléversé le média
• Le média reste disponible pendant 24 heures après son téléversement
• Une seule pièce jointe par message est prise en charge

---

Partage de Publications

Incluez une Publication dans votre message en ajoutant l’URL de la Publication au texte de celui-ci :

{
  "text": "Have you seen this? https://x.com/XDevelopers/status/1580559079470145536"
}

La réponse comprendra un champ referenced_tweets contenant l’identifiant de la Publication.

---

Exigences relatives aux messages

Champ	Obligatoire	Remarques
text	Oui*	Obligatoire s’il n’y a pas de pièces jointes
attachments	Oui*	Obligatoire s’il n’y a pas de texte

*Au moins l’un de text ou attachments doit être fourni.

---

Compatibilité des identifiants avec v1.1

Les identifiants de conversation et d’événement sont partagés entre les points de terminaison v1.1 et v2. Cela permet des flux de travail hybrides :

• Créer des messages avec v2
• Supprimer des messages avec v1.1 (pas encore disponible en v2)
• Faire référence aux identifiants de conversation à partir d’URL x.com

---

Gestion des erreurs

Statut	Erreur	Solution
400	Requête invalide	Vérifiez le format du corps de la requête
401	Non autorisé	Vérifiez le jeton d’accès
403	Accès refusé	Vérifiez les scopes et les autorisations de l’utilisateur
429	Trop de requêtes	Attendez puis réessayez

Problèmes courants

Impossible d’envoyer un message à l’utilisateur

Le destinataire peut avoir configuré ses paramètres de DM pour empêcher les messages d’utilisateurs inconnus, ou peut vous avoir bloqué.

Échec de la pièce jointe du média

Assurez-vous que le média a été téléversé par le même utilisateur authentifié et qu’il a été téléversé il y a moins de 24 heures.

Échec de la création du groupe

Vérifiez que tous les id des participants sont valides et que les utilisateurs autorisent les invitations à des DM de groupe.

---

Prochaines étapes

Démarrage rapide

Envoyez votre premier message privé

Recherche de messages privés

Récupérez les conversations de messages privés

Téléchargement de médias

Téléversez des médias à joindre

Référence de l’API

Documentation complète du point de terminaison