Guide d’intégration

Ce guide couvre les principaux concepts nécessaires pour intégrer les endpoints d’interrogation des Direct Messages dans votre application.

Authentification

Les endpoints de DM nécessitent une authentification utilisateur pour accéder aux conversations privées :

Méthode	Description
OAuth 2.0 Authorization Code with PKCE	Recommandé
OAuth 1.0a User Context	Prise en charge pour compatibilité descendante

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

Scopes requis (OAuth 2.0)

Scope	Requis pour
`dm.read`	Lecture des événements de messages privés (DM)
`tweet.read`	Requis avec `dm.read`
`users.read`	Requis avec `dm.read`

Types de conversation

Individuelle

Contient toujours exactement deux participants. Format de l’id de conversation : {smaller_user_id}-{larger_user_id}

Groupe

Deux participants ou plus. La composition des membres peut évoluer dans le temps.

Types d’événements

Événement	Description	Champs clés
`MessageCreate`	Un message a été envoyé	`text`, `sender_id`
`ParticipantsJoin`	Un utilisateur a rejoint le groupe	`participant_ids`, `sender_id`
`ParticipantsLeave`	Un utilisateur a quitté le groupe	`participant_ids`

Exemples d’événements

MessageCreate

{
  "id": "1582838499983564806",
  "event_type": "MessageCreate",
  "text": "Hi everyone.",
  "sender_id": "944480690",
  "dm_conversation_id": "1578398451921985538",
  "created_at": "2022-10-19T20:58:00.000Z"
}

ParticipantsJoin

{
  "id": "1582835469712138240",
  "event_type": "ParticipantsJoin",
  "participant_ids": ["944480690"],
  "sender_id": "17200003",
  "dm_conversation_id": "1578398451921985538",
  "created_at": "2022-10-19T20:45:58.000Z"
}

ParticipantsLeave

{
  "id": "1582838535115067392",
  "event_type": "ParticipantsLeave",
  "participant_ids": ["944480690"],
  "dm_conversation_id": "1578398451921985538",
  "created_at": "2022-10-19T20:58:09.000Z"
}

Champs et expansions

Champs par défaut

Type d’événement	Champs par défaut
MessageCreate	`id`, `event_type`, `text`
ParticipantsJoin/Leave	`id`, `event_type`, `participant_ids`

Champs disponibles

Champ	Description	Événements
`dm_conversation_id`	Identifiant de la conversation	Tous
`created_at`	Horodatage de l’événement	Tous
`sender_id`	Expéditeur / initiateur de l’invitation	MessageCreate, Join
`attachments`	Pièces jointes média	MessageCreate
`referenced_tweets`	Publications partagées	MessageCreate

Expansions disponibles

Expansion	Renvoie
`sender_id`	Objet utilisateur de l’expéditeur
`participant_ids`	Objets utilisateur des participants
`attachments.media_keys`	Objets média
`referenced_tweets.id`	Objets de type Publication

Exemple avec expansions

cURL

curl "https://api.x.com/2/dm_events?\
dm_event.fields=created_at,sender_id,attachments&\
expansions=sender_id,attachments.media_keys&\
user.fields=username,profile_image_url&\
media.fields=url,type" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

# Récupérer des événements de DM avec des expansions
for page in client.dm_events.list(
    dm_event_fields=["created_at", "sender_id", "attachments"],
    expansions=["sender_id", "attachments.media_keys"],
    user_fields=["username", "profile_image_url"],
    media_fields=["url", "type"],
    max_results=100
):
    for event in page.data:
        print(f"Event: {event.event_type} - {event.text}")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

const paginator = client.dmEvents.list({
  dmEventFields: ["created_at", "sender_id", "attachments"],
  expansions: ["sender_id", "attachments.media_keys"],
  userFields: ["username", "profile_image_url"],
  mediaFields: ["url", "type"],
  maxResults: 100,
});

for await (const page of paginator) {
  page.data?.forEach((event) => {
    console.log(`Event: ${event.event_type} - ${event.text}`);
  });
}

Pagination

Les événements de DM sont renvoyés dans l’ordre chronologique inverse (du plus récent au plus ancien) :

cURL

# Première requête
curl "https://api.x.com/2/dm_events?max_results=100" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

# Requête suivante avec un jeton de pagination
curl "https://api.x.com/2/dm_events?max_results=100&pagination_token=NEXT_TOKEN" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

# Le SDK gère automatiquement la pagination
all_events = []

for page in client.dm_events.list(max_results=100):
    if page.data:
        all_events.extend(page.data)

print(f"Found {len(all_events)} DM events")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

async function getAllDMEvents() {
  const allEvents = [];

  // Le SDK gère automatiquement la pagination
  const paginator = client.dmEvents.list({ maxResults: 100 });

  for await (const page of paginator) {
    if (page.data) {
      allEvents.push(...page.data);
    }
  }

  return allEvents;
}

// Utilisation
const events = await getAllDMEvents();
console.log(`Found ${events.length} DM events`);

Les événements datant d’au plus 30 jours sont disponibles.

Compatibilité des ID avec la v1.1

Les identifiants de conversation et d’événement sont partagés entre les endpoints v1.1 et v2. Cela signifie que vous pouvez :

Utiliser la v2 pour récupérer des événements, puis utiliser la v1.1 pour supprimer des messages spécifiques
Utiliser des identifiants de conversation provenant d’URL x.com dans des requêtes d’API

Étapes suivantes

Démarrage rapide

Effectuez votre première requête de recherche de messages directs

Envoyer des DM

Envoyez des messages directs

Référence de l’API

Documentation complète du point de terminaison

Exemples de code

Exemples de code prêts à l’emploi

Vue d’ensemble

Publications

Utilisateurs

Messages privés

Mentions J’aime

Listes

Espaces

Communautés

Notes de la communauté

Tendances

Actualités

Médias

Activité sur X

Utilisation

Connexions de flux

Conformité

Enterprise v2

Flux des J’aime

GNIP 2.0

Guide d’intégration

Authentification

Scopes requis (OAuth 2.0)

Types de conversation

Individuelle

Groupe

Types d’événements

Exemples d’événements

Champs et expansions

Champs par défaut

Champs disponibles

Expansions disponibles

Exemple avec expansions

Compatibilité des ID avec la v1.1

Étapes suivantes

Démarrage rapide

Envoyer des DM

Référence de l’API

Exemples de code