Eventos

Sobre

Cada evento tiene el mismo sobre; d lleva la carga específica del tipo, descrita a continuación.

Campo	Tipo	Significado
`v`	int	Versión del sobre. Hoy, `1`
`t`	string	Tipo de evento, de la tabla siguiente
`op`	create \| update \| delete	`create`, `update` (enriquecimiento del mismo id) o `delete`
`id`	string	Identidad estable. Deduplica por esto
`ts`	int (ms)	Cuándo ocurrió en X, en ms desde la época Unix. X no indica cuándo cambió un perfil, cuándo se siguió o dejó de seguir a alguien, cuándo llegó un seguidor verificado ni cuándo se borró una publicación: en esos eventos es cuándo lo detectamos
`sid`	string	Posición en el flujo para la repetición; presente en el flujo y en el historial
`target.id`	string	Id numérico en X de la cuenta monitorizada (para `search.match`, del autor de la publicación)
`target.screen_name`	string	Nombre de usuario de la cuenta monitorizada
`target.name`	string	El nombre visible de la cuenta
`d`	object	Carga específica del tipo

Tipos de evento

Tipo	Categoría	Significado
`tweet.create`	Publicaciones	La cuenta publicó algo nuevo
`tweet.reply`	Publicaciones	Respondió a alguien; `reply_to` lleva la publicación a la que se responde, con su texto y sus medios
`tweet.retweet`	Publicaciones	Republicó a alguien; `retweet_of` lleva la publicación original completa
`tweet.quote`	Publicaciones	Citó a alguien; `quoted` lleva la publicación citada completa
`tweet.edit`	Publicaciones	Editó una publicación; el evento lleva la nueva versión y `edit_of` la versión que sustituye
`tweet.delete`	Publicaciones	Una publicación que la cuenta había publicado ya no está
`profile.name`	Perfil	Cambió el nombre visible
`profile.screen_name`	Perfil	Cambió el nombre de usuario
`profile.bio`	Perfil	Cambió la biografía
`profile.location`	Perfil	Cambió la ubicación
`profile.url`	Perfil	Cambió el enlace del perfil
`profile.avatar`	Perfil	Cambió el avatar; `old` y `new` son URL de imagen
`profile.banner`	Perfil	Cambió el banner; `old` y `new` son URL de imagen
`profile.pinned`	Perfil	Cambió la publicación fijada; `tweet` y `old_tweet` llevan las publicaciones en sí
`profile.verified`	Perfil	La insignia de verificación apareció o desapareció
`follow.add`	Grafo de seguimiento	La cuenta empezó a seguir a alguien; `user` es el perfil completo de esa cuenta
`follow.remove`	Grafo de seguimiento	La cuenta dejó de seguir a alguien
`followers.verified.add`	Grafo de seguimiento	Una cuenta verificada empezó a seguirla; `user` lleva biografía, recuentos, ubicación y fecha de alta
`account.status`	Cuenta	La cuenta pasó a protegida, suspendida o no disponible, o volvió a estar activa
`search.match`	Búsqueda	Alguien publicó algo que coincide con una de tus palabras clave; `keyword` dice cuál, `author` es su perfil completo

X no proporciona ninguna marca de tiempo para "empezó a seguir" ni "ganó un seguidor", así que para esos eventos ts es el momento en que detectamos el cambio.

No tienes que recibir todos los tipos de todas las cuentas. Elegir tipos de evento explica cómo recibir solo algunos, por ejemplo solo los nuevos seguidores verificados.

Cargas

Cinco formas de carga cubren los dieciocho tipos.

Carga Tweet

El d de tweet.create, tweet.reply, tweet.retweet y tweet.quote, y la base de search.match.

Campo	Tipo	Significado
`tweet_id`	string	El id de la publicación, como cadena
`kind`	tweet \| reply \| retweet \| quote	Qué clase de publicación es
`text`	string	Texto completo (incluidas las publicaciones largas)
`lang`	string \| null	Idioma detectado por X
`author`	User	La cuenta que la publicó, como User completo — el mismo objeto que el autor de un `search.match`: nombre de usuario, nombre, bio, avatar, banner, contadores, verificación, ubicación, enlace y fecha de alta. En una primera trama escueta es la cuenta tal como se leyó por última vez; el `update` la trae tal como se leyó con la publicación
`reply_to`	Brief+ \| null	Para respuestas: la publicación a la que se responde — un Resumen más `screen_name`, `tweet_id` y `user_id` de su autor
`retweet_of`	Brief \| null	Para republicaciones: la publicación original
`quoted`	Brief \| null	Para citas: la publicación citada
`media`	string[]	URL de imagen simples, una por elemento multimedia
`media_items`	Media[]	Cada elemento multimedia con tipo, variantes de video y dimensiones
`urls`	string[]	Enlaces expandidos de la publicación
`article`	Article \| null	En publicaciones que enlazan un artículo de X: el artículo
`counts`	{reply, rt, like, quote, bookmark}	Recuentos de respuestas, republicaciones, me gusta, citas y marcadores en el momento en que la leímos
`views`	int \| null	Recuento de visualizaciones, cuando X lo expone
`url`	string	Enlace canónico a la publicación
`full`	bool	`false` en una primera trama `create` escueta; `true` una vez que el evento lleva la publicación entera
`kind_final`	bool	`true` cuando `kind` es definitivo. `false` solo en una primera trama escueta cuyo `kind` es `tweet`: la publicación aún puede resultar ser una cita, y el `update` del mismo `id` lo resuelve
`kind_was`	tweet \| null (update only)	Solo en el `update` que fija el tipo de una publicación, y solo cuando la primera trama decía otra cosa: el tipo que tenía esa trama (`tweet` para una publicación que resultó ser una cita)
`edit_of`	Brief \| null	En `tweet.edit`: la versión a la que esta sustituye (su id, y su texto y autor cuando los teníamos)

ejemplo

{
  "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
  }
}

Una primera trama create es deliberadamente escueta: lleva el id, el autor (author, la cuenta tal como se leyó por última vez) y el texto, que puede venir recortado, para poder salir en el momento en que se ve la publicación; url ya apunta a la publicación. En ese momento una cita no siempre se distingue de una publicación original, así que una trama así dice tweet.create con kind_final: false. El update que sigue con el mismo id trae la carga completa de arriba y el tipo definitivo: tweet.quote con kind_was: "tweet" si era una cita.

la misma publicación tal como se entregó por primera vez, antes del enriquecimiento

{
  "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
  }
}

Carga de eliminación

El d de tweet.delete. Solo se envía para una publicación que habíamos visto y que ya no está. Su ts es cuándo se detectó el borrado; la hora de la propia publicación está en su trama create anterior.

Campo	Tipo	Significado
`tweet_id`	string	El id de la publicación eliminada
`url`	string	Dónde solía estar

ejemplo

{
  "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"
  }
}

Carga de cambio de perfil

El d de cada evento profile.*. Para estos, op es update.

Campo	Tipo	Significado
`field`	string	Qué campo del perfil cambió; la misma palabra que sigue a `profile.` en el tipo
`old`	any	El valor anterior
`new`	any	El valor nuevo
`tweet`	Brief (pinned only)	Para `profile.pinned`: la publicación recién fijada
`old_tweet`	Brief (pinned only)	Para `profile.pinned`: la publicación fijada anteriormente, si la teníamos

ejemplo

{
  "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."
  }
}

Carga de seguimiento

El d de follow.add, follow.remove y followers.verified.add.

Campo	Tipo	Significado
`user`	User	La otra cuenta, como Usuario completo

ejemplo

{
  "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
    }
  }
}

Carga de estado de la cuenta

El d de account.status. Un estado es active, protected (publicaciones visibles solo para seguidores aprobados), suspended (por X) o unavailable (desactivada, eliminada o no visible por otro motivo). ts es cuándo detectamos el cambio.

Campo	Tipo	Significado
`old`	active \| protected \| suspended \| unavailable	El estado anterior
`new`	active \| protected \| suspended \| unavailable	El estado actual
`reason`	string \| null	El texto de X, si lo da (por ejemplo `Suspended`)

ejemplo

{
  "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"
  }
}

Carga de coincidencia de búsqueda

El d de search.match: una carga Tweet más tres campos sobre la coincidencia. El target del sobre es el autor de la publicación, que no tiene por qué ser uno de tus objetivos.

Campo	Tipo	Significado
`keyword.id`	int	Id de la palabra clave que coincidió
`keyword.query`	string	Su consulta
`keyword.label`	string \| null	Su etiqueta, si le pusiste una
`author`	User	El perfil completo del autor
`author_is_target`	bool	`true` si el autor es además una cuenta monitorizada en este sistema
`…`	TweetPayload	Todos los campos de la carga Tweet

ejemplo

{
  "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
  }
}