Événements

Enveloppe

Chaque événement a la même enveloppe ; d porte la charge utile propre au type, décrite ci-dessous.

Champ	Type	Signification
`v`	int	Version de l'enveloppe. `1` aujourd'hui
`t`	string	Type d'événement, d'après le tableau ci-dessous
`op`	create \| update \| delete	`create`, `update` (enrichissement du même id) ou `delete`
`id`	string	Identité stable. Dédupliquez sur ce champ
`ts`	int (ms)	Quand cela s'est produit sur X, en ms depuis l'epoch. X ne donne pas le moment d'un changement de profil, d'un abonnement ou désabonnement, d'un nouvel abonné vérifié ni d'une suppression de publication : pour ces événements, c'est le moment où nous l'avons détecté
`sid`	string	Position dans le flux pour le rejeu ; présent sur le flux et dans l'historique
`target.id`	string	Identifiant X numérique du compte surveillé (pour `search.match`, celui de l'auteur de la publication)
`target.screen_name`	string	Nom d'utilisateur du compte surveillé
`target.name`	string	Le nom affiché du compte
`d`	object	Charge utile propre au type

Types d'événements

Type	Catégorie	Signification
`tweet.create`	Publications	Le compte a publié quelque chose de nouveau
`tweet.reply`	Publications	Il a répondu à quelqu'un ; `reply_to` porte la publication à laquelle il répond, avec son texte et ses médias
`tweet.retweet`	Publications	Il a republié quelqu'un ; `retweet_of` porte la publication originale en entier
`tweet.quote`	Publications	Il a cité quelqu'un ; `quoted` porte la publication citée en entier
`tweet.edit`	Publications	Il a modifié une publication ; l'événement porte la nouvelle version, et `edit_of` la version qu'elle remplace
`tweet.delete`	Publications	Une publication que le compte avait publiée a disparu
`profile.name`	Profil	Le nom affiché a changé
`profile.screen_name`	Profil	Le nom d'utilisateur a changé
`profile.bio`	Profil	La bio a changé
`profile.location`	Profil	La localisation a changé
`profile.url`	Profil	Le lien du profil a changé
`profile.avatar`	Profil	L'avatar a changé ; `old` et `new` sont des URL d'images
`profile.banner`	Profil	La bannière a changé ; `old` et `new` sont des URL d'images
`profile.pinned`	Profil	La publication épinglée a changé ; `tweet` et `old_tweet` portent les publications elles-mêmes
`profile.verified`	Profil	Le badge de certification est apparu ou a disparu
`follow.add`	Graphe d'abonnements	Le compte a commencé à suivre quelqu'un ; `user` est le profil complet de ce compte
`follow.remove`	Graphe d'abonnements	Le compte a cessé de suivre quelqu'un
`followers.verified.add`	Graphe d'abonnements	Un compte certifié a commencé à le suivre ; `user` porte bio, compteurs, localisation, date d'inscription
`account.status`	Compte	Le compte est devenu protégé, suspendu ou indisponible, ou de nouveau actif
`search.match`	Recherche	Quelqu'un a publié quelque chose correspondant à l'un de vos mots-clés ; `keyword` dit lequel, `author` est son profil complet

X ne fournit aucun horodatage pour « a commencé à suivre » ou « a gagné un abonné » ; pour ces événements, ts est donc le moment où nous avons détecté le changement.

Vous n'êtes pas obligé de recevoir tous les types de tous les comptes. Choisir les types d'événement explique comment n'en recevoir que certains, par exemple seulement les nouveaux abonnés vérifiés.

Charges utiles

Cinq formes de charge utile couvrent les dix-huit types.

Charge utile Tweet

Le d de tweet.create, tweet.reply, tweet.retweet et tweet.quote, et la base de search.match.

Champ	Type	Signification
`tweet_id`	string	L'identifiant de la publication, sous forme de chaîne
`kind`	tweet \| reply \| retweet \| quote	De quel genre de publication il s'agit
`text`	string	Texte intégral (publications longues comprises)
`lang`	string \| null	Langue détectée par X
`author`	User	Le compte qui l'a publié, en User complet — le même objet que l'auteur d'un `search.match` : nom d'utilisateur, nom, bio, avatar, bannière, compteurs, vérification, localisation, lien et date d'inscription. Sur une première trame allégée, c'est le compte tel que lu en dernier ; l'`update` le porte tel que lu avec la publication
`reply_to`	Brief+ \| null	Pour les réponses : la publication à laquelle on répond — un Brief plus `screen_name`, `tweet_id` et `user_id` de son auteur
`retweet_of`	Brief \| null	Pour les republications : la publication originale
`quoted`	Brief \| null	Pour les citations : la publication citée
`media`	string[]	URL d'images simples, une par élément média
`media_items`	Media[]	Chaque élément média avec son type, ses variantes vidéo et ses dimensions
`urls`	string[]	Liens développés dans la publication
`article`	Article \| null	Pour les publications qui renvoient vers un article X : l'article
`counts`	{reply, rt, like, quote, bookmark}	Nombre de réponses, republications, j'aime, citations et signets au moment de notre lecture
`views`	int \| null	Nombre de vues, quand X l'expose
`url`	string	Lien canonique vers la publication
`full`	bool	`false` sur une première trame `create` allégée ; `true` une fois que l'événement porte la publication entière
`kind_final`	bool	`true` quand `kind` est définitif. `false` seulement sur une première trame allégée dont le `kind` est `tweet` : la publication peut encore se révéler être une citation, et l'`update` sur le même `id` tranche
`kind_was`	tweet \| null (update only)	Seulement sur l'`update` qui fixe le type d'une publication, et seulement si la première trame disait autre chose : le type qu'avait cette trame (`tweet` pour une publication qui s'est révélée être une citation)
`edit_of`	Brief \| null	Sur `tweet.edit` : la version que celle-ci remplace (son identifiant, et son texte et son auteur quand nous les avions)

exemple

{
  "v": 1,
  "t": "tweet.create",
  "op": "create",
  "id": "tweet:2097879002992070835",
  "ts": 1789012345678,
  "sid": "1789012346012-0",
  "target": {
    "id": "1652541",
    "screen_name": "Reuters",
    "name": "Reuters"
  },
  "d": {
    "tweet_id": "2097879002992070835",
    "kind": "tweet",
    "text": "Ash-covered shoes and a president in crisis…",
    "lang": "en",
    "author": {
      "id": "1652541",
      "screen_name": "Reuters",
      "name": "Reuters",
      "bio": "Top and breaking news, pictures and videos from Reuters.",
      "avatar": "https://pbs.twimg.com/profile_images/1874154135869616128/nJDmubGJ_normal.jpg",
      "banner": "https://pbs.twimg.com/profile_banners/1652541/1573687397",
      "followers": 25900000,
      "following": 1150,
      "tweets": 1080000,
      "location": "Around the world",
      "url": "https://www.reuters.com",
      "verified": true,
      "verified_type": "Business",
      "protected": false,
      "created_at": "2007-03-20T17:46:05Z",
      "category": null
    },
    "reply_to": null,
    "retweet_of": null,
    "quoted": null,
    "media": [
      "https://pbs.twimg.com/media/….jpg"
    ],
    "media_items": [
      {
        "type": "photo",
        "url": "https://pbs.twimg.com/media/….jpg",
        "expanded_url": "https://x.com/Reuters/status/2097879002992070835/photo/1",
        "width": 1200,
        "height": 675
      }
    ],
    "urls": [
      "https://reut.rs/…"
    ],
    "counts": {
      "reply": 12,
      "rt": 40,
      "like": 131,
      "quote": 3,
      "bookmark": 9
    },
    "views": 20411,
    "url": "https://x.com/Reuters/status/2097879002992070835",
    "full": true,
    "kind_final": true
  }
}

Une première trame create est volontairement allégée : elle porte l'identifiant, l'auteur (author, le compte tel que lu en dernier) et le texte, éventuellement raccourci, afin de pouvoir partir dès que la publication est vue ; url pointe déjà vers la publication. À ce moment, une citation ne se distingue pas toujours d'une publication originale : une telle trame indique donc tweet.create avec kind_final: false. L'update qui suit sur le même id porte la charge complète ci-dessus et le type définitif : tweet.quote avec kind_was: "tweet" s'il s'agissait d'une citation.

la même publication telle qu'elle a été livrée en premier, avant enrichissement

{
  "v": 1,
  "t": "tweet.create",
  "op": "create",
  "id": "tweet:2097879002992070835",
  "ts": 1789012345678,
  "sid": "1789012346012-0",
  "target": {
    "id": "1652541",
    "screen_name": "Reuters",
    "name": "Reuters"
  },
  "d": {
    "tweet_id": "2097879002992070835",
    "kind": "tweet",
    "text": "Ash-covered shoes and a president in crisis…",
    "author": {
      "id": "1652541",
      "screen_name": "Reuters",
      "name": "Reuters",
      "bio": "Top and breaking news, pictures and videos from Reuters.",
      "avatar": "https://pbs.twimg.com/profile_images/1874154135869616128/nJDmubGJ_normal.jpg",
      "banner": "https://pbs.twimg.com/profile_banners/1652541/1573687397",
      "followers": 25900000,
      "following": 1150,
      "tweets": 1080000,
      "location": "Around the world",
      "url": "https://www.reuters.com",
      "verified": true,
      "verified_type": "Business",
      "protected": false,
      "created_at": "2007-03-20T17:46:05Z",
      "category": null
    },
    "url": "https://x.com/Reuters/status/2097879002992070835",
    "full": false,
    "kind_final": false
  }
}

Charge utile de suppression

Le d de tweet.delete. Envoyé uniquement pour une publication que nous avions vue et qui a maintenant disparu. Son ts est le moment où la suppression a été détectée ; l'heure de la publication elle-même figure dans sa trame create antérieure.

Champ	Type	Signification
`tweet_id`	string	L'identifiant de la publication supprimée
`url`	string	Où elle se trouvait

exemple

{
  "v": 1,
  "t": "tweet.delete",
  "op": "delete",
  "id": "tweet:2097879002992070835:delete",
  "ts": 1789012345678,
  "sid": "…",
  "target": {
    "id": "1652541",
    "screen_name": "Reuters",
    "name": "Reuters"
  },
  "d": {
    "tweet_id": "2097879002992070835",
    "url": "https://x.com/Reuters/status/2097879002992070835"
  }
}

Charge utile de changement de profil

Le d de chaque événement profile.*. op vaut update pour ceux-ci.

Champ	Type	Signification
`field`	string	Quel champ du profil a changé ; le même mot que celui qui suit `profile.` dans le type
`old`	any	La valeur précédente
`new`	any	La nouvelle valeur
`tweet`	Brief (pinned only)	Pour `profile.pinned` : la publication nouvellement épinglée
`old_tweet`	Brief (pinned only)	Pour `profile.pinned` : la publication épinglée précédente, si nous l'avions

exemple

{
  "v": 1,
  "t": "profile.bio",
  "op": "update",
  "id": "profile:1652541:bio:9c1d2e3f4a5b",
  "ts": 1789012400000,
  "sid": "…",
  "target": {
    "id": "1652541",
    "screen_name": "Reuters",
    "name": "Reuters"
  },
  "d": {
    "field": "bio",
    "old": "Top news and analysis from around the world.",
    "new": "Top news, analysis and video from around the world."
  }
}

Charge utile d'abonnement

Le d de follow.add, follow.remove et followers.verified.add.

Champ	Type	Signification
`user`	User	L'autre compte, sous forme d'Utilisateur complet

exemple

{
  "v": 1,
  "t": "follow.add",
  "op": "create",
  "id": "follow:44196397:12:add:496948",
  "ts": 1789012400000,
  "sid": "…",
  "target": {
    "id": "44196397",
    "screen_name": "elonmusk",
    "name": "Elon Musk"
  },
  "d": {
    "user": {
      "id": "12",
      "screen_name": "jack",
      "name": "jack",
      "bio": "…",
      "avatar": "https://pbs.twimg.com/profile_images/…",
      "banner": null,
      "followers": 6400000,
      "following": 4200,
      "tweets": 29000,
      "location": "",
      "url": null,
      "verified": true,
      "verified_type": "blue",
      "protected": false,
      "created_at": "2006-03-21T20:50:14Z",
      "category": null
    }
  }
}

Charge de statut du compte

Le d de account.status. Un statut vaut active, protected (publications visibles des seuls abonnés approuvés), suspended (par X) ou unavailable (désactivé, supprimé ou invisible pour une autre raison). ts est le moment où nous avons détecté le changement.

Champ	Type	Signification
`old`	active \| protected \| suspended \| unavailable	Le statut d'avant
`new`	active \| protected \| suspended \| unavailable	Le statut actuel
`reason`	string \| null	Le libellé de X, s'il en donne un (par exemple `Suspended`)

exemple

{
  "v": 1,
  "t": "account.status",
  "op": "update",
  "id": "account:9000002:status:active>suspended:497010",
  "ts": 1789236000000,
  "sid": "…",
  "target": {
    "id": "9000002",
    "screen_name": "some_account",
    "name": "Some Account"
  },
  "d": {
    "old": "active",
    "new": "suspended",
    "reason": "Suspended"
  }
}

Charge utile de correspondance de recherche

Le d de search.match : une charge utile Tweet plus trois champs sur la correspondance. Le target de l'enveloppe est l'auteur de la publication, qui n'est pas nécessairement l'une de vos cibles.

Champ	Type	Signification
`keyword.id`	int	Identifiant du mot-clé qui a correspondu
`keyword.query`	string	Sa requête
`keyword.label`	string \| null	Son libellé, si vous en avez défini un
`author`	User	Le profil complet de l'auteur
`author_is_target`	bool	`true` si l'auteur est aussi un compte surveillé sur ce système
`…`	TweetPayload	Tous les champs de la charge utile Tweet

exemple

{
  "v": 1,
  "t": "search.match",
  "op": "create",
  "id": "search:12:2097900000000000000",
  "ts": 1789012500000,
  "sid": "…",
  "target": {
    "id": "9000001",
    "screen_name": "some_trader",
    "name": "Some Trader"
  },
  "d": {
    "tweet_id": "2097900000000000000",
    "kind": "tweet",
    "text": "$SOL breaking out…",
    "lang": "en",
    "author": {
      "id": "9000001",
      "screen_name": "some_trader",
      "name": "Some Trader",
      "bio": "…",
      "followers": 1200,
      "verified": false,
      "…": "…"
    },
    "keyword": {
      "id": 12,
      "query": "($SOL OR \"Solana\") -filter:retweets",
      "label": "solana"
    },
    "author_is_target": false,
    "media": [],
    "media_items": [],
    "urls": [],
    "url": "https://x.com/some_trader/status/2097900000000000000",
    "full": true
  }
}