Passer au contenu principal
Les endpoints des Messages privés v2 introduisent les conversations et les événements de conversation comme objets essentiels de la X API, et distinguent les conversations en tête-à-tête des conversations de groupe. Les conversations en tête-à-tête ont toujours deux, et seulement deux, participants, tandis que les conversations de groupe peuvent en compter 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 gestion des Messages privés dans 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 des conversations en tête-à-tête ou des conversations de 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 cette conversation ont tous un dm_event_id unique.   Les endpoints de gestion des Messages privés proposent trois méthodes POST pour créer de nouveaux messages et les ajouter aux conversations :
  • POST /2/dm_conversations/with/:participant_id/messages - Crée un Message privé en tête-à-tête. Cette méthode ajoute le message à une conversation en tête-à-tête existante ou en crée une nouvelle. Le paramètre de chemin :participant_id correspond à l’id utilisateur du compte destinataire.  Voici un exemple de corps de requête JSON pour l’envoi d’un Message privé en tête-à-tête :
{
   "text": "Bonjour, juste à vous. Ceci apparaîtra comme une nouvelle conversation si nous ne nous sommes jamais écrit, ou sera ajouté à notre fil de discussion existant. "
}
  • POST /2/dm_conversations - Crée une nouvelle conversation de groupe et y ajoute un message direct. Ces requêtes nécessitent une liste de participants à la conversation. Notez que vous pouvez créer plusieurs conversations avec la même liste de participants. Ces requêtes renverront toujours un nouvel id de conversation. Ci-dessous figure un exemple de corps de requête JSON pour créer une nouvelle conversation de groupe et y ajouter un message direct. Notez que cela nécessite un champ “conversation_type” qui doit être défini sur “Group” (sensible à la casse).
{
   "message": {"text": "Bonjour à vous deux, ceci est une nouvelle conversation de groupe."},
   "participant_ids": ["944480690","906948460078698496"],
   "conversation_type": "Group"
}
  • POST /2/dm_conversations/:dm_conversation_id/messages - Crée un message privé et l’ajoute à une conversation existante. Le paramètre de chemin :dm_conversation_id correspond à l’id de la conversation à laquelle le message sera ajouté. Cette méthode peut être utilisée pour ajouter un message aussi bien aux conversations en tête-à-tête qu’aux conversations de groupe. Voici un exemple de corps de requête JSON pour envoyer un message privé à la fois dans des conversations en tête-à-tête et des conversations de groupe :
{
   "text": "Voici un nouveau message."
}
Ces méthodes POST permettent d’attacher un seul élément média. Les corps de requête POST doivent inclure le ou les champs “text” et “attachments”. L’attribut “text” est requis si le champ “attachments” n’est pas inclus, et le champ “attachments” est requis si le champ “text” n’est pas inclus. Voir la section suivante pour plus d’informations. Pour en savoir plus, consultez les références de l’API 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 en v1.1 proposent des méthodes permettant de récupérer un événement unique et de supprimer des événements. Ces méthodes 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 id de conversation affichés dans les URL de conversation sur l’application X.  

​
Inclusion de pièces jointes multimédias et référence aux Posts

Les endpoints de gestion des Messages privés prennent tous en charge l’ajout d’un élément multimédia (photo, vidéo ou GIF). L’ajout d’un média nécessite un id de média généré par l’endpoint v1.1 Upload media. L’utilisateur authentifié qui envoie le Message privé doit également avoir téléversé le média. Une fois téléversé, le média est disponible pendant 24 heures pour être joint au message. Pour illustrer l’inclusion d’un média, voici un exemple de corps de requête JSON : 
{
 "text": "Voici une photo...",
 "attachments": [{"media_id": "1583157113245011970}]
}
L’événement MessageCreate résultant inclura les metadata suivantes : 
{
    "attachments": {
        "media_keys": [
            "5_1583157113245011970"
        ]
    }
}
Vous pouvez également inclure des Posts en ajoutant l’URL du Post dans le texte du message. Pour illustrer l’inclusion de Posts dans des messages, voici un exemple de corps de requête JSON : 
{
 "text": "Voici le Tweet dont je parlais : https://x.com/SnowBotDev/status/1580559079470145536"
}
L’événement MessageCreate résultant inclura les metadata suivantes : 
{
    "referenced_tweets": [
        {
            "id": "1580559079470145536"
        }
    ]
}

​
Authentification

Tous les endpoints X API v2 exigent d’authentifier 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 de l’utilisateur pour y accéder. Ces endpoints de Messages privés exigent 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 Access Tokens utilisateur pour effectuer une requête avec succès. Les Access Tokens doivent être associés à l’utilisateur pour le compte duquel vous effectuez la requête. 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 contexte utilisateur OAuth peut être délicat à utiliser. Si vous n’êtes pas familier avec cette méthode d’authentification, nous recommandons d’utiliser une bibliothèque ou un outil comme Postman pour authentifier correctement vos requêtes. OAuth 2.0 Authorization Code with PKCE permet 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 portées fines et spécifiques, qui vous confèrent des autorisations précises au nom d’un utilisateur. Les endpoints de lookup des Messages privés nécessitent ces portées : dm.write, dm.read, tweet.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 et Apps développeur

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é, configurer 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 considérable 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 au nom de votre App ou d’un utilisateur authentifié.  Les endpoints de gestion des Messages privés sont soumis à des limites de taux à la fois au niveau utilisateur et au niveau X App. Cela signifie que l’utilisateur authentifié pour lequel vous effectuez la requête ne peut envoyer qu’un certain nombre de messages avec votre X App. En outre, une limite quotidienne s’applique au nombre de Messages privés que votre X App peut envoyer.  Une limite de taux utilisateur de 200 requêtes/messages par 15 minutes s’applique aux méthodes POST. Les utilisateurs sont également limités à 1000 Messages privés par 24 heures. Par ailleurs, les X Apps ont une limite de 15000 messages par 24 heures. Ces limites de taux sont partagées entre les endpoints POST.  Outils utiles Voici quelques outils que nous vous encourageons à explorer lorsque vous travaillez avec les endpoints de recherche des 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 pour vous aider à comprendre rapidement ce qui est disponible. Pour en savoir plus sur nos collections Postman, consultez la page Utiliser Postman.  Exemples de code Des exemples de code Python pour les endpoints v2 des Messages privés sont disponibles dans notre dépôt X API v2 sample code GitHub repository. 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 v2 des Messages privés 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 v2 des Messages privés. Vous pouvez trouver une bibliothèque compatible avec les endpoints v2 en recherchant la balise de version appropriée.
⌘I