diff --git a/docs.json b/docs.json index 9d56d2225..82a9a6451 100644 --- a/docs.json +++ b/docs.json @@ -845,6 +845,7 @@ "pages": [ "x-api/activity/introduction", "x-api/activity/quickstart", + "x-api/activity/event-payloads", "x-api/activity/activity-stream", "x-api/activity/create-x-activity-subscription", "x-api/activity/deletes-x-activity-subscription", diff --git a/enterprise-api/llms.txt b/enterprise-api/llms.txt index c30770c3c..284d067ac 100644 --- a/enterprise-api/llms.txt +++ b/enterprise-api/llms.txt @@ -22,6 +22,7 @@ - [Activity Stream](https://docs.x.com/x-api/activity/activity-stream.md): Reference documentation for the endpoint and related functionality. - [Create X Activity Subscription](https://docs.x.com/x-api/activity/create-x-activity-subscription.md): Reference documentation for the endpoint and related functionality. - [Deletes X Activity Subscription](https://docs.x.com/x-api/activity/deletes-x-activity-subscription.md): Reference documentation for the endpoint and related functionality. +- [Event payloads](https://docs.x.com/x-api/activity/event-payloads.md): Sample JSON payloads for X Activity API events - [Get X Activity Subscriptions](https://docs.x.com/x-api/activity/get-x-activity-subscriptions.md): Reference documentation for the endpoint and related functionality. - [Introduction](https://docs.x.com/x-api/activity/introduction.md): The X Activity API (XAA) endpoint group allows developers to tap in to activity events happening on the X Platform. A - [Quickstart](https://docs.x.com/x-api/activity/quickstart.md) diff --git a/x-api/activity/event-payloads.mdx b/x-api/activity/event-payloads.mdx new file mode 100644 index 000000000..fb68d95e2 --- /dev/null +++ b/x-api/activity/event-payloads.mdx @@ -0,0 +1,1124 @@ +--- +title: X Activity API event payload examples +sidebarTitle: Event payloads +description: "Sample JSON payloads for X Activity API events, including posts, likes, follows, profile updates, chat, DMs, mutes, blocks, Spaces, news, and OAuth revokes." +keywords: ["activity API payloads", "X Activity event examples", "post.create", "post.delete", "like.create", "follow.follow", "dm.sent", "chat.received", "oauth.revoke", "activity stream payloads"] +--- + +Events delivered by the X Activity API (via the [persistent HTTP stream](/x-api/activity/activity-stream) or [webhooks](/x-api/webhooks/introduction)) share a common envelope: + +| Field | Description | +| --- | --- | +| `event_uuid` | Unique identifier for this event delivery | +| `filter` | The filter that matched (for example `user_id` or `keyword`) | +| `event_type` | The subscribed event type | +| `tag` | Optional tag from your subscription (when set) | +| `payload` | Event-specific data | +| `includes` | Optional expanded objects (users, tweets, and so on) when available | + +```json +{ + "data": { + "event_uuid": "2080388949189468542", + "filter": { + "user_id": "1830023695835787264" + }, + "event_type": "post.create", + "tag": "my post create", + "payload": {}, + "includes": {} + } +} +``` + +The examples below are representative real-world payloads. Field availability can vary based on account settings, expansions, and the object state at delivery time. See the [introduction](/x-api/activity/introduction) for the full list of supported event types and authentication requirements. + +--- + +## Post events + +### `post.create` + +Fired when the filtered user creates a Post. The `payload` is a Post object; `includes` may contain related users and tweets. + +```json +{ + "data": { + "event_uuid": "2080388949189468542", + "filter": { + "user_id": "1830023695835787264" + }, + "event_type": "post.create", + "tag": "my post create", + "payload": { + "paid_partnership": false, + "possibly_sensitive": false, + "id": "2080388949189468542", + "display_text_range": [ + 0, + 4 + ], + "conversation_id": "2080388949189468542", + "edit_history_tweet_ids": [ + "2080388949189468542" + ], + "text": "test", + "author_id": "1830023695835787264", + "created_at": "2026-07-23T20:25:51.000Z", + "edit_controls": { + "edits_remaining": 5, + "edits_remaining_str": "5", + "is_edit_eligible": true, + "editable_until": "2026-07-23T21:25:51.000Z" + }, + "lang": "en", + "reply_settings": "everyone", + "public_metrics": { + "retweet_count": 0, + "retweet_count_str": "0", + "reply_count": 0, + "reply_count_str": "0", + "like_count": 0, + "like_count_str": "0", + "quote_count": 0, + "quote_count_str": "0", + "bookmark_count": 0, + "bookmark_count_str": "0", + "impression_count": 0, + "impression_count_str": "0" + } + }, + "includes": { + "users": [ + { + "affiliation": { + "user_id": [ + "783214" + ], + "badge_url": "https://pbs.twimg.com/profile_images/1955359038532653056/OSHY3ewP_bigger.jpg", + "url": "https://twitter.com/X", + "description": "X" + }, + "is_identity_verified": false, + "description": "Dev Platform @X", + "id": "1830023695835787264", + "username": "mike_rosinsky", + "name": "Mike Rosinsky", + "entities": { + "url": { + "urls": [ + { + "start": 0, + "start_str": "0", + "end": 23, + "end_str": "23", + "url": "https://t.co/xDAbc9N7Eo", + "expanded_url": "https://m-rosinsky.github.io/", + "display_url": "m-rosinsky.github.io" + } + ] + }, + "description": { + "mentions": [ + { + "start": 13, + "start_str": "13", + "end": 15, + "end_str": "15", + "username": "X" + } + ] + } + }, + "protected": false, + "verified_type": "blue", + "profile_image_url": "https://pbs.twimg.com/profile_images/1830023799045050368/NMKeg1VL_normal.jpg", + "profile_banner_url": "https://pbs.twimg.com/profile_banners/1830023695835787264/1779629491", + "public_metrics": { + "followers_count": 2726, + "followers_count_str": "2726", + "following_count": 265, + "following_count_str": "265", + "tweet_count": 672, + "tweet_count_str": "672", + "listed_count": 41, + "listed_count_str": "41", + "like_count": 902, + "like_count_str": "902", + "media_count": 91, + "media_count_str": "91" + }, + "created_at": "2024-08-31T23:23:51.000Z", + "pinned_tweet_id": "1979992230132691280", + "verified": true, + "url": "https://t.co/xDAbc9N7Eo", + "most_recent_tweet_id": "2080388949189468542" + } + ], + "tweets": [ + { + "paid_partnership": false, + "possibly_sensitive": false, + "id": "2080388949189468542", + "display_text_range": [ + 0, + 4 + ], + "conversation_id": "2080388949189468542", + "edit_history_tweet_ids": [ + "2080388949189468542" + ], + "text": "test", + "author_id": "1830023695835787264", + "created_at": "2026-07-23T20:25:51.000Z", + "edit_controls": { + "edits_remaining": 5, + "edits_remaining_str": "5", + "is_edit_eligible": true, + "editable_until": "2026-07-23T21:25:51.000Z" + }, + "lang": "en", + "reply_settings": "everyone", + "public_metrics": { + "retweet_count": 0, + "retweet_count_str": "0", + "reply_count": 0, + "reply_count_str": "0", + "like_count": 0, + "like_count_str": "0", + "quote_count": 0, + "quote_count_str": "0", + "bookmark_count": 0, + "bookmark_count_str": "0", + "impression_count": 0, + "impression_count_str": "0" + } + } + ] + } + } +} +``` + +### `post.delete` + +Fired when the filtered user deletes a Post. The `payload` contains the deleted Post ID and author ID. + +```json +{ + "data": { + "event_uuid": "4548373934783614104", + "filter": { + "user_id": "1830023695835787264" + }, + "event_type": "post.delete", + "tag": "my post deletes", + "payload": { + "id": "2080388949189468542", + "author_id": "1830023695835787264" + }, + "includes": { + "users": [ + { + "data": { + "created_at": "2024-08-31T23:23:51.000Z", + "username": "mike_rosinsky", + "is_identity_verified": false, + "url": "https://t.co/xDAbc9N7Eo", + "id": "1830023695835787264", + "protected": false, + "profile_banner_url": "https://pbs.twimg.com/profile_banners/1830023695835787264/1779629491", + "public_metrics": { + "followers_count": 2726, + "followers_count_str": "2726", + "following_count": 265, + "following_count_str": "265", + "tweet_count": 671, + "tweet_count_str": "671", + "listed_count": 41, + "listed_count_str": "41", + "like_count": 902, + "like_count_str": "902", + "media_count": 91, + "media_count_str": "91" + }, + "verified": true, + "entities": { + "url": { + "urls": [ + { + "start": 0, + "start_str": "0", + "end": 23, + "end_str": "23", + "url": "https://t.co/xDAbc9N7Eo", + "expanded_url": "https://m-rosinsky.github.io/", + "display_url": "m-rosinsky.github.io" + } + ] + }, + "description": { + "mentions": [ + { + "start": 13, + "start_str": "13", + "end": 15, + "end_str": "15", + "username": "X" + } + ] + } + }, + "verified_type": "blue", + "affiliation": { + "badge_url": "https://pbs.twimg.com/profile_images/1955359038532653056/OSHY3ewP_bigger.jpg", + "url": "https://twitter.com/X", + "description": "X" + }, + "name": "Mike Rosinsky", + "profile_image_url": "https://pbs.twimg.com/profile_images/1830023799045050368/NMKeg1VL_normal.jpg", + "description": "Dev Platform @X" + } + } + ] + } + } +} +``` + +### `post.mention.create` + +Fired when someone @mentions the filtered user in a Post. Private event — requires user-context authentication. + +```json +{ + "data": { + "event_uuid": "2080389492192489925", + "filter": { + "user_id": "1830023695835787264" + }, + "event_type": "post.mention.create", + "tag": "my post mentions", + "payload": { + "text": "test @mike_rosinsky", + "id": "2080389492192489925", + "created_at": "2026-07-23T20:28:01.000Z", + "paid_partnership": false, + "lang": "en", + "display_text_range": [ + 0, + 19 + ], + "possibly_sensitive": false, + "entities": { + "mentions": [ + { + "start": 5, + "start_str": "5", + "end": 19, + "end_str": "19", + "username": "mike_rosinsky", + "id": "1830023695835787264" + } + ] + }, + "edit_controls": { + "edits_remaining": 5, + "edits_remaining_str": "5", + "is_edit_eligible": true, + "editable_until": "2026-07-23T21:28:01.000Z" + }, + "conversation_id": "2080389492192489925", + "author_id": "1034202272312504320", + "edit_history_tweet_ids": [ + "2080389492192489925" + ], + "public_metrics": { + "retweet_count": 0, + "retweet_count_str": "0", + "reply_count": 0, + "reply_count_str": "0", + "like_count": 0, + "like_count_str": "0", + "quote_count": 0, + "quote_count_str": "0", + "bookmark_count": 0, + "bookmark_count_str": "0", + "impression_count": 0, + "impression_count_str": "0" + }, + "reply_settings": "everyone" + }, + "includes": { + "users": [ + { + "is_identity_verified": false, + "profile_image_url": "https://pbs.twimg.com/profile_images/1975969068881747968/Vkl44BSn_normal.jpg", + "username": "mr_the2nd", + "profile_banner_url": "https://pbs.twimg.com/profile_banners/1034202272312504320/1539277728", + "description": "yo im a dog!! bark bark", + "verified_type": "none", + "id": "1034202272312504320", + "protected": false, + "location": "SF", + "public_metrics": { + "followers_count": 106, + "followers_count_str": "106", + "following_count": 4, + "following_count_str": "4", + "tweet_count": 17117891, + "tweet_count_str": "17117891", + "listed_count": 5, + "listed_count_str": "5", + "like_count": 9, + "like_count_str": "9", + "media_count": 0, + "media_count_str": "0" + }, + "most_recent_tweet_id": "2080389492192489925", + "url": "https://t.co/p9lDSgbSNh", + "name": "MrGigglesWorthThe2nd", + "entities": { + "url": { + "urls": [ + { + "start": 0, + "start_str": "0", + "end": 23, + "end_str": "23", + "url": "https://t.co/p9lDSgbSNh", + "expanded_url": "http://x.com", + "display_url": "x.com" + } + ] + } + }, + "verified": false, + "created_at": "2018-08-27T22:13:31.000Z" + }, + { + "affiliation": { + "badge_url": "https://pbs.twimg.com/profile_images/1955359038532653056/OSHY3ewP_bigger.jpg", + "url": "https://twitter.com/X", + "user_id": [ + "783214" + ], + "description": "X" + }, + "is_identity_verified": false, + "profile_image_url": "https://pbs.twimg.com/profile_images/1830023799045050368/NMKeg1VL_normal.jpg", + "username": "mike_rosinsky", + "profile_banner_url": "https://pbs.twimg.com/profile_banners/1830023695835787264/1779629491", + "description": "Dev Platform @X", + "verified_type": "blue", + "pinned_tweet_id": "1979992230132691280", + "id": "1830023695835787264", + "protected": false, + "public_metrics": { + "followers_count": 2726, + "followers_count_str": "2726", + "following_count": 265, + "following_count_str": "265", + "tweet_count": 671, + "tweet_count_str": "671", + "listed_count": 41, + "listed_count_str": "41", + "like_count": 902, + "like_count_str": "902", + "media_count": 91, + "media_count_str": "91" + }, + "most_recent_tweet_id": "2080030420951797910", + "url": "https://t.co/xDAbc9N7Eo", + "name": "Mike Rosinsky", + "entities": { + "url": { + "urls": [ + { + "start": 0, + "start_str": "0", + "end": 23, + "end_str": "23", + "url": "https://t.co/xDAbc9N7Eo", + "expanded_url": "https://m-rosinsky.github.io/", + "display_url": "m-rosinsky.github.io" + } + ] + }, + "description": { + "mentions": [ + { + "start": 13, + "start_str": "13", + "end": 15, + "end_str": "15", + "username": "X" + } + ] + } + }, + "verified": true, + "created_at": "2024-08-31T23:23:51.000Z" + } + ], + "tweets": [ + { + "text": "test @mike_rosinsky", + "id": "2080389492192489925", + "created_at": "2026-07-23T20:28:01.000Z", + "paid_partnership": false, + "lang": "en", + "display_text_range": [ + 0, + 19 + ], + "possibly_sensitive": false, + "entities": { + "mentions": [ + { + "start": 5, + "start_str": "5", + "end": 19, + "end_str": "19", + "username": "mike_rosinsky", + "id": "1830023695835787264" + } + ] + }, + "edit_controls": { + "edits_remaining": 5, + "edits_remaining_str": "5", + "is_edit_eligible": true, + "editable_until": "2026-07-23T21:28:01.000Z" + }, + "conversation_id": "2080389492192489925", + "author_id": "1034202272312504320", + "edit_history_tweet_ids": [ + "2080389492192489925" + ], + "public_metrics": { + "retweet_count": 0, + "retweet_count_str": "0", + "reply_count": 0, + "reply_count_str": "0", + "like_count": 0, + "like_count_str": "0", + "quote_count": 0, + "quote_count_str": "0", + "bookmark_count": 0, + "bookmark_count_str": "0", + "impression_count": 0, + "impression_count_str": "0" + }, + "reply_settings": "everyone" + } + ] + } + } +} +``` + +--- + +## Like events + +### `like.create` + +Fired when the filtered user likes a Post, or when one of their Posts is liked. Private event — requires user-context authentication. Supports an optional `direction` filter (`inbound` or `outbound`). + +The `payload` is a like object with the following fields: + +| Field | Description | +| --- | --- | +| `id` | Like event ID | +| `liked_tweet_id` | ID of the Post that was liked | +| `tweet_author_id` | Author of the liked Post | +| `created_at` | Creation time of the liked Post (when available) | +| `timestamp_ms` | Event timestamp in milliseconds (when available) | + +--- + +## Follow events + +### `follow.follow` + +Fired when the filtered user follows another user, or is followed. The `payload` includes `source` (the follower) and `target` (the user being followed). + +```json +{ + "data": { + "event_uuid": "-5425377595780808323", + "filter": { + "user_id": "1830023695835787264" + }, + "event_type": "follow.follow", + "tag": "my follows", + "payload": { + "source": { + "data": { + "is_identity_verified": false, + "profile_banner_url": "https://pbs.twimg.com/profile_banners/1830023695835787264/1779629491", + "id": "1830023695835787264", + "affiliation": { + "url": "https://twitter.com/X", + "badge_url": "https://pbs.twimg.com/profile_images/1955359038532653056/OSHY3ewP_bigger.jpg", + "description": "X" + }, + "public_metrics": { + "followers_count": 2728, + "followers_count_str": "2728", + "following_count": 265, + "following_count_str": "265", + "tweet_count": 671, + "tweet_count_str": "671", + "listed_count": 41, + "listed_count_str": "41", + "like_count": 903, + "like_count_str": "903", + "media_count": 91, + "media_count_str": "91" + }, + "created_at": "2024-08-31T23:23:51.000Z", + "verified_type": "blue", + "entities": { + "url": { + "urls": [ + { + "start": 0, + "start_str": "0", + "end": 23, + "end_str": "23", + "url": "https://t.co/xDAbc9N7Eo", + "expanded_url": "https://m-rosinsky.github.io/", + "display_url": "m-rosinsky.github.io" + } + ] + }, + "description": { + "mentions": [ + { + "start": 13, + "start_str": "13", + "end": 15, + "end_str": "15", + "username": "X" + } + ] + } + }, + "username": "mike_rosinsky", + "profile_image_url": "https://pbs.twimg.com/profile_images/1830023799045050368/NMKeg1VL_normal.jpg", + "protected": false, + "verified": true, + "url": "https://t.co/xDAbc9N7Eo", + "description": "Dev Platform @X", + "name": "Mike Rosinsky" + } + }, + "target": { + "data": { + "is_identity_verified": true, + "profile_banner_url": "https://pbs.twimg.com/profile_banners/1389913567671975937/1711058670", + "id": "1389913567671975937", + "affiliation": { + "url": "https://twitter.com/MyDoge", + "badge_url": "https://pbs.twimg.com/profile_images/1656530956801523719/SC7nEKMa_bigger.png", + "description": "MyDoge" + }, + "public_metrics": { + "followers_count": 1886119, + "followers_count_str": "1886119", + "following_count": 1019, + "following_count_str": "1019", + "tweet_count": 58417, + "tweet_count_str": "58417", + "listed_count": 6581, + "listed_count_str": "6581", + "like_count": 116304, + "like_count_str": "116304", + "media_count": 34087, + "media_count_str": "34087" + }, + "created_at": "2021-05-05T12:03:43.000Z", + "verified_type": "blue", + "username": "cb_doge", + "profile_image_url": "https://pbs.twimg.com/profile_images/1498070100393754625/C2V-fbll_normal.jpg", + "protected": false, + "verified": true, + "url": "", + "description": "", + "name": "DogeDesigner" + } + } + } + } +} +``` + +### `follow.unfollow` + +Fired when the filtered user unfollows another user, or is unfollowed. Same `source` / `target` shape as `follow.follow`. + +```json +{ + "data": { + "event_uuid": "4926763473571172316", + "filter": { + "user_id": "1830023695835787264" + }, + "event_type": "follow.unfollow", + "tag": "my unfollows", + "payload": { + "source": { + "data": { + "created_at": "2024-08-31T23:23:51.000Z", + "username": "mike_rosinsky", + "is_identity_verified": false, + "url": "https://t.co/xDAbc9N7Eo", + "id": "1830023695835787264", + "protected": false, + "profile_banner_url": "https://pbs.twimg.com/profile_banners/1830023695835787264/1779629491", + "public_metrics": { + "followers_count": 2728, + "followers_count_str": "2728", + "following_count": 264, + "following_count_str": "264", + "tweet_count": 671, + "tweet_count_str": "671", + "listed_count": 41, + "listed_count_str": "41", + "like_count": 903, + "like_count_str": "903", + "media_count": 91, + "media_count_str": "91" + }, + "verified": true, + "entities": { + "url": { + "urls": [ + { + "start": 0, + "start_str": "0", + "end": 23, + "end_str": "23", + "url": "https://t.co/xDAbc9N7Eo", + "expanded_url": "https://m-rosinsky.github.io/", + "display_url": "m-rosinsky.github.io" + } + ] + }, + "description": { + "mentions": [ + { + "start": 13, + "start_str": "13", + "end": 15, + "end_str": "15", + "username": "X" + } + ] + } + }, + "verified_type": "blue", + "affiliation": { + "badge_url": "https://pbs.twimg.com/profile_images/1955359038532653056/OSHY3ewP_bigger.jpg", + "url": "https://twitter.com/X", + "description": "X" + }, + "name": "Mike Rosinsky", + "profile_image_url": "https://pbs.twimg.com/profile_images/1830023799045050368/NMKeg1VL_normal.jpg", + "description": "Dev Platform @X" + } + }, + "target": { + "data": { + "created_at": "2021-05-05T12:03:43.000Z", + "username": "cb_doge", + "is_identity_verified": true, + "url": "", + "id": "1389913567671975937", + "protected": false, + "profile_banner_url": "https://pbs.twimg.com/profile_banners/1389913567671975937/1711058670", + "public_metrics": { + "followers_count": 1886118, + "followers_count_str": "1886118", + "following_count": 1019, + "following_count_str": "1019", + "tweet_count": 58417, + "tweet_count_str": "58417", + "listed_count": 6581, + "listed_count_str": "6581", + "like_count": 116304, + "like_count_str": "116304", + "media_count": 34087, + "media_count_str": "34087" + }, + "verified": true, + "verified_type": "blue", + "affiliation": { + "badge_url": "https://pbs.twimg.com/profile_images/1656530956801523719/SC7nEKMa_bigger.png", + "url": "https://twitter.com/MyDoge", + "description": "MyDoge" + }, + "name": "DogeDesigner", + "profile_image_url": "https://pbs.twimg.com/profile_images/1498070100393754625/C2V-fbll_normal.jpg", + "description": "" + } + } + } + } +} +``` + +--- + +## Profile events + +All `profile.update.*` events share a `before` / `after` payload shape. + +Supported types: `profile.update.bio`, `profile.update.profile_picture`, `profile.update.banner_picture`, `profile.update.screenname`, `profile.update.handle`, `profile.update.geo`, `profile.update.url`, `profile.update.verified_badge`, `profile.update.affiliate_badge`. + +### `profile.update.bio` + +```json +{ + "data": { + "event_uuid": "-2101258703069165209", + "filter": { + "user_id": "1830023695835787264" + }, + "event_type": "profile.update.bio", + "tag": "my bio updates", + "payload": { + "before": "Dev Platform @X", + "after": "Developer Platform @X" + } + } +} +``` + +--- + +## Chat events (XChat) + +Encrypted chat payloads include opaque encoded fields used by the XChat client libraries. Private events — require user-context authentication. + +### `chat.received` + +```json +{ + "data": { + "event_uuid": "8511582263942905822", + "filter": { + "user_id": "1830023695835787264" + }, + "event_type": "chat.received", + "tag": "my chat received", + "payload": { + "conversation_token": "eyJhbGciOiJIUzI1NiJ9.eyJyZXF1ZXN0aW5nVXNlciI6ICIxODMwMDIzNjk1ODM1Nzg3MjY0IiwgInJlY2lwaWVudCI6ICIxMDM0MjAyMjcyMzEyNTA0MzIwIiwgInZhbGlkU2luY2VNU2VjIjogIjE3NDU4ODQ4MDAwMDAifQ.86ymJsmru5KJtNvlvNXCErgMeevqaNBgBvLiSZa_kbo", + "id": "e4f4d3fc-8bbf-4928-92eb-e5058d6bb6f6", + "created_at_msec": "1784841183370", + "sender_id": "1034202272312504320", + "conversation_id": "1034202272312504320:1830023695835787264", + "conversation_key_version": "1768236281331", + "encoded_event": "CwABAAAAEzIwODA0MDA4MjUyMjcxMDAxNjALAAIAAAAkZTRmNGQzZmMtOGJiZi00OTI4LTkyZWItZTUwNThkNmJiNmY2CwADAAAAEzEwMzQyMDIyNzIzMTI1MDQzMjALAAQAAAAnMTAzNDIwMjI3MjMxMjUwNDMyMDoxODMwMDIzNjk1ODM1Nzg3MjY0CwAFAAAA12V5SmhiR2NpT2lKSVV6STFOaUo5LmV5SnlaWEYxWlhOMGFXNW5WWE5sY2lJNklDSXhPRE13TURJek5qazFPRE0xTnpnM01qWTBJaXdnSW5KbFkybHdhV1Z1ZENJNklDSXhNRE0wTWpBeU1qY3lNekV5TlRBME16SXdJaXdnSW5aaGJHbGtVMmx1WTJWTlUyVmpJam9nSWpFM05EVTRPRFE0TURBd01EQWlmUS44NnltSnNtcnU1S0p0TnZsdk5YQ0VyZ01lZXZxYU5CZ0J2TGlTWmFfa2JvCwAGAAAADTE3ODQ4NDExODMzNzAMAAcMAAELAGQAAABTzxVCBCVAlguLYySJdcYhpgpUgQYshT8ZDGTu+ukrdsGGBQ26N5r2/TNd7FJ/znc64yz9gv6u6xdA4IlWu+C4ScjGYgJ+7A8nLxDREFtYvlmqlDQLAGUAAAANMTc2ODIzNjI4MTMzMQIAZgECAGkACABqAAAAAQwAbAsAAQAAACBKpTut+m1aRnpYRpLv2RT2EaZGCqyjz3jp9zZ2ldrO6QsAAgAAAEjpfQJPSWghOYDoroi35e0Au4Lp5ClsN0brEmBVp7wwZo6qX3PbnSsBD2tqV8gk7JDSMTvSMjndOjk/MMHwGsYDt6Fn9yNJ+NoAAgBtAAAADAAJCwABAAAAVjZJSzlTWklNWEJlNVNGY0I3dkdaSmQ1QTVFYjVNTHZud3JoVUZmQkd2NFM1R3NTWDNXV1BHdUluWFZOZlNsYTM2RWpYUVEvUi9IaHNBKzJoUEFFWTdBCwACAAAADTE3NjUzODI2MzQ4MTcLAAMAAAABNwsABAAAAHxNRmt3RXdZSEtvWkl6ajBDQVFZSUtvWkl6ajBEQVFjRFFnQUVKMmMrM0JZWnM3WkNFWS9VUENwbVF4Sk85djZGSmpldXN2bVNaTy9KRWF5OG9GMStvWFhsSFY1NWtYNGJLNi96RmlqTkt2cTFZUmIwaXQweVhxYmdsQT09DwAFDAAAAAELAAEAAAATMTAzNDIwMjI3MjMxMjUwNDMyMAsAAgAAAA0xNzY1MzgyNjM0ODE3CwADAAAAfE1Ga3dFd1lIS29aSXpqMENBUVlJS29aSXpqMERBUWNEUWdBRUoyYyszQllaczdaQ0VZL1VQQ3BtUXhKTzl2NkZKamV1c3ZtU1pPL0pFYXk4b0YxK29YWGxIVjU1a1g0Yks2L3pGaWpOS3ZxMVlSYjBpdDB5WHFiZ2xBPT0AAAIACwELAA0AAAADMC0xAA==", + "conversation_key_change_event": "CwABAAAAEzIwMTA3NTQ4MTkxMTY0NDk5MDULAAIAAAAkNGNlNjQ1ZDItYTg5YS00OTlmLThiZGUtZTBhMWY0M2QxOTFmCwADAAAAEzE4MzAwMjM2OTU4MzU3ODcyNjQLAAQAAAAnMTAzNDIwMjI3MjMxMjUwNDMyMDoxODMwMDIzNjk1ODM1Nzg3MjY0CwAFAAAA12V5SmhiR2NpT2lKSVV6STFOaUo5LmV5SnlaWEYxWlhOMGFXNW5WWE5sY2lJNklDSXhPRE13TURJek5qazFPRE0xTnpnM01qWTBJaXdnSW5aaGJHbGtVMmx1WTJWTlUyVmpJam9nSWpFM05EVTRPRFE0TURBd01EQWlmUS44NnltSnNtcnU1S0p0TnZsdk5YQ0VyZ01lZXZxYU5CZ0J2TGlTWmFfa2JvCwAGAAAADTE3NjgyMzYyODE1NTkMAAcMAAMLAAEAAAANMTc2ODIzNjI4MTMzMQ8AAgwAAAACCwABAAAAEzEwMzQyMDIyNzIzMTI1MDQzMjALAAIAAACYQkVzU1pNTTZxMEhPM0FRVjlXWk52cWh0YndyblFpeE1zcEo5VkVZNmpvMVR2cFV1SmxjaE9GNVgxMFUrUStFRmMvZWZjMlpjYnRmSFR6ZFlzSDN2VExXdENJZE1qR1orZ0JGc0o4cEF1cmx6clR6ZkFPeVNPNWlYZEhBeVJ6c085TlV0TGZnUjJ4TWxJRVA2Y2M4bk1nUT0LAAMAAAANMTc2NTM4MjYzNDgxNwALAAEAAAATMTgzMDAyMzY5NTgzNTc4NzI2NAsAAgAAAJhCRDdHZEdXYklaaHdQaEFQaFYwVktoKyswR2poR3l5QXp0Yk1jL0ZHSWYvbCtSYThpU3lhV2tROFpSVVJtT25aRnN5VzNwMjRiMFp1QWg3dkNjZlpOV2dOZ1hpQUJIZmYxL1RpVFdLZ1FkM1liR0dyakV6eHJlZ0NmRWxRZmhaTFBDaEttQ0orb01wM2svL2RrRUhoSXNvPQsAAwAAAA0xNzM2NzIzODI4NjY3AAAADAAJCwABAAAAVlJpL1BsYndGK3Z4Yjdjb3BFSGgzOGNVdmx2cSt1cVp2eWRybVd3T2lBWE80c09mbm94MUUvM1U1RVV6QjBGL0RjMGkzNGNEejBXNjBXdFpTWnkrZUJBCwACAAAADTE3MzY3MjM4Mjg2NjcLAAMAAAABNAsABAAAAHxNRmt3RXdZSEtvWkl6ajBDQVFZSUtvWkl6ajBEQVFjRFFnQUV5eFFZKzNDSTJsd01GNUVxUldjNlhNUm5ZbVRuYVFYaFF5MW96Y2h6MElRbjd1aTVyeTFVU3pTY1Q5MDBXeVRQa05tU3ZHK004dHh6KzhZNVdmMGdaUT09AAA=", + "message_event_signature": { + "public_key_version": "1765382634817", + "signature": "6IK9SZIMXBe5SFcB7vGZJd5A5Eb5MLvnwrhUFfBGv4S5GsSX3WWPGuInXVNfSla36EjXQQ/R/HhsA+2hPAEY7A", + "signature_version": "7", + "signing_public_key": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEJ2c+3BYZs7ZCEY/UPCpmQxJO9v6FJjeusvmSZO/JEay8oF1+oXXlHV55kX4bK6/zFijNKvq1YRb0it0yXqbglA==" + } + } + } +} +``` + +### `chat.sent` + +```json +{ + "data": { + "event_uuid": "3723060601307155846", + "filter": { + "user_id": "1830023695835787264" + }, + "event_type": "chat.sent", + "tag": "my chat sent", + "payload": { + "conversation_token": "eyJhbGciOiJIUzI1NiJ9.eyJyZXF1ZXN0aW5nVXNlciI6ICIxODMwMDIzNjk1ODM1Nzg3MjY0IiwgInJlY2lwaWVudCI6ICIxMDM0MjAyMjcyMzEyNTA0MzIwIiwgInZhbGlkU2luY2VNU2VjIjogIjE3NDU4ODQ4MDAwMDAifQ.86ymJsmru5KJtNvlvNXCErgMeevqaNBgBvLiSZa_kbo", + "id": "8e75466b-56ec-4e88-bddf-b18f7cc6030e", + "created_at_msec": "1784841233939", + "sender_id": "1830023695835787264", + "conversation_id": "1034202272312504320:1830023695835787264", + "conversation_key_version": "1768236281331", + "encoded_event": "CwABAAAAEzIwODA0MDEwMzczMzMyMzc3NjALAAIAAAAkOGU3NTQ2NmItNTZlYy00ZTg4LWJkZGYtYjE4ZjdjYzYwMzBlCwADAAAAEzE4MzAwMjM2OTU4MzU3ODcyNjQLAAQAAAAnMTAzNDIwMjI3MjMxMjUwNDMyMDoxODMwMDIzNjk1ODM1Nzg3MjY0CwAFAAAA12V5SmhiR2NpT2lKSVV6STFOaUo5LmV5SnlaWEYxWlhOMGFXNW5WWE5sY2lJNklDSXhPRE13TURJek5qazFPRE0xTnpnM01qWTBJaXdnSW5KbFkybHdhV1Z1ZENJNklDSXhNRE0wTWpBeU1qY3lNekV5TlRBME16SXdJaXdnSW5aaGJHbGtVMmx1WTJWTlUyVmpJam9nSWpFM05EVTRPRFE0TURBd01EQWlmUS44NnltSnNtcnU1S0p0TnZsdk5YQ0VyZ01lZXZxYU5CZ0J2TGlTWmFfa2JvCwAGAAAADTE3ODQ4NDEyMzM5MzkMAAcMAAELAGQAAABTH3krC1zh+3xP3AFJAdsXAzyU+i28GsAnsxk9LHLIAkYOcRpiEaP4ajkqrZ9PgxuqhA3+nsvJYyGDPHxeH+Wop/15BXDMmwGt6S259l3odPepvEMLAGUAAAANMTc2ODIzNjI4MTMzMQIAZgECAGkACABqAAAAAQwAbAsAAQAAACB948bZ8lP62xtQFXYtMh1V2xrDLFa7kwSnsXLgwLydVAsAAgAAAEgNfFI7/1jMfU7qQ0sfzSMEnapZn+9JlopoOmO9vm7FjZwEQgtk0E6A8ZxhUCSWN8xxb6k2aK417KxvDO5C6iD7DKy3mwc6phYAAgBtAAAADAAJCwABAAAAVk1hbnVSdkJ1cGlwMzhYemdTNzMzVjl4Vm4vNis0dWd1TXd2TWErWVVEUWlESXhWaFZiYVFjTitiS3liUFJCQ2o3SVB1UmkyUVF6UnZQZzdXcTlaaFB3CwACAAAADTE3MzY3MjM4Mjg2NjcLAAMAAAABNwsABAAAAHxNRmt3RXdZSEtvWkl6ajBDQVFZSUtvWkl6ajBEQVFjRFFnQUV5eFFZKzNDSTJsd01GNUVxUldjNlhNUm5ZbVRuYVFYaFF5MW96Y2h6MElRbjd1aTVyeTFVU3pTY1Q5MDBXeVRQa05tU3ZHK004dHh6KzhZNVdmMGdaUT09DwAFDAAAAAELAAEAAAATMTgzMDAyMzY5NTgzNTc4NzI2NAsAAgAAAA0xNzM2NzIzODI4NjY3CwADAAAAfE1Ga3dFd1lIS29aSXpqMENBUVlJS29aSXpqMERBUWNEUWdBRXl4UVkrM0NJMmx3TUY1RXFSV2M2WE1SblltVG5hUVhoUXkxb3pjaHowSVFuN3VpNXJ5MVVTelNjVDkwMFd5VFBrTm1TdkcrTTh0eHorOFk1V2YwZ1pRPT0AAAIACwELAA0AAAADMC0yAA==", + "conversation_key_change_event": "CwABAAAAEzIwMTA3NTQ4MTkxMTY0NDk5MDULAAIAAAAkNGNlNjQ1ZDItYTg5YS00OTlmLThiZGUtZTBhMWY0M2QxOTFmCwADAAAAEzE4MzAwMjM2OTU4MzU3ODcyNjQLAAQAAAAnMTAzNDIwMjI3MjMxMjUwNDMyMDoxODMwMDIzNjk1ODM1Nzg3MjY0CwAFAAAA12V5SmhiR2NpT2lKSVV6STFOaUo5LmV5SnlaWEYxWlhOMGFXNW5WWE5sY2lJNklDSXhPRE13TURJek5qazFPRE0xTnpnM01qWTBJaXdnSW5aaGJHbGtVMmx1WTJWTlUyVmpJam9nSWpFM05EVTRPRFE0TURBd01EQWlmUS44NnltSnNtcnU1S0p0TnZsdk5YQ0VyZ01lZXZxYU5CZ0J2TGlTWmFfa2JvCwAGAAAADTE3NjgyMzYyODE1NTkMAAcMAAMLAAEAAAANMTc2ODIzNjI4MTMzMQ8AAgwAAAACCwABAAAAEzEwMzQyMDIyNzIzMTI1MDQzMjALAAIAAACYQkVzU1pNTTZxMEhPM0FRVjlXWk52cWh0YndyblFpeE1zcEo5VkVZNmpvMVR2cFV1SmxjaE9GNVgxMFUrUStFRmMvZWZjMlpjYnRmSFR6ZFlzSDN2VExXdENJZE1qR1orZ0JGc0o4cEF1cmx6clR6ZkFPeVNPNWlYZEhBeVJ6c085TlV0TGZnUjJ4TWxJRVA2Y2M4bk1nUT0LAAMAAAANMTc2NTM4MjYzNDgxNwALAAEAAAATMTgzMDAyMzY5NTgzNTc4NzI2NAsAAgAAAJhCRDdHZEdXYklaaHdQaEFQaFYwVktoKyswR2poR3l5QXp0Yk1jL0ZHSWYvbCtSYThpU3lhV2tROFpSVVJtT25aRnN5VzNwMjRiMFp1QWg3dkNjZlpOV2dOZ1hpQUJIZmYxL1RpVFdLZ1FkM1liR0dyakV6eHJlZ0NmRWxRZmhaTFBDaEttQ0orb01wM2svL2RrRUhoSXNvPQsAAwAAAA0xNzM2NzIzODI4NjY3AAAADAAJCwABAAAAVlJpL1BsYndGK3Z4Yjdjb3BFSGgzOGNVdmx2cSt1cVp2eWRybVd3T2lBWE80c09mbm94MUUvM1U1RVV6QjBGL0RjMGkzNGNEejBXNjBXdFpTWnkrZUJBCwACAAAADTE3MzY3MjM4Mjg2NjcLAAMAAAABNAsABAAAAHxNRmt3RXdZSEtvWkl6ajBDQVFZSUtvWkl6ajBEQVFjRFFnQUV5eFFZKzNDSTJsd01GNUVxUldjNlhNUm5ZbVRuYVFYaFF5MW96Y2h6MElRbjd1aTVyeTFVU3pTY1Q5MDBXeVRQa05tU3ZHK004dHh6KzhZNVdmMGdaUT09AAA=", + "message_event_signature": { + "public_key_version": "1736723828667", + "signature": "ManuRvBupip38XzgS733V9xVn/6+4uguMwvMa+YUDQiDIxVhVbaQcN+bKybPRBCj7IPuRi2QQzRvPg7Wq9ZhPw", + "signature_version": "7", + "signing_public_key": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEyxQY+3CI2lwMF5EqRWc6XMRnYmTnaQXhQy1ozchz0IQn7ui5ry1USzScT900WyTPkNmSvG+M8txz+8Y5Wf0gZQ==" + } + } + } +} +``` + +### `chat.conversation_join` + +Fired when a user joins an encrypted chat conversation. The payload shape matches other chat events (conversation identity and encoded crypto material). Private event — requires user-context authentication. + +--- + +## Legacy DM events + +Legacy (unencrypted) DM events. Private events — require user-context authentication. + +### `dm.sent` + +```json +{ + "data": { + "event_uuid": "3653776467229295171", + "filter": { + "user_id": "1830023695835787264" + }, + "event_type": "dm.sent", + "tag": "my dm sent", + "payload": { + "direct_message_events": [ + { + "type": "message_create", + "id": "2080401635629769111", + "created_timestamp": "1784841376616", + "message_create": { + "target": { + "recipient_id": "260907612" + }, + "sender_id": "1830023695835787264", + "message_data": { + "text": "test", + "entities": { + "hashtags": [], + "symbols": [], + "user_mentions": [], + "urls": [] + } + } + } + } + ], + "users": { + "1830023695835787264": { + "data": { + "username": "mike_rosinsky", + "protected": false, + "description": "Developer Platform @X", + "name": "Mike Rosinsky", + "created_at": "2024-08-31T23:23:51.000Z", + "public_metrics": { + "followers_count": 2728, + "followers_count_str": "2728", + "following_count": 265, + "following_count_str": "265", + "tweet_count": 671, + "tweet_count_str": "671", + "listed_count": 41, + "listed_count_str": "41", + "like_count": 907, + "like_count_str": "907", + "media_count": 91, + "media_count_str": "91" + }, + "affiliation": { + "badge_url": "https://pbs.twimg.com/profile_images/1955359038532653056/OSHY3ewP_bigger.jpg", + "description": "X", + "url": "https://twitter.com/X" + }, + "entities": { + "url": { + "urls": [ + { + "start": 0, + "start_str": "0", + "end": 23, + "end_str": "23", + "url": "https://t.co/xDAbc9MzOQ", + "expanded_url": "https://m-rosinsky.github.io/", + "display_url": "m-rosinsky.github.io" + } + ] + }, + "description": { + "mentions": [ + { + "start": 19, + "start_str": "19", + "end": 21, + "end_str": "21", + "username": "X" + } + ] + } + }, + "verified": true, + "profile_image_url": "https://pbs.twimg.com/profile_images/1830023799045050368/NMKeg1VL_normal.jpg", + "url": "https://t.co/xDAbc9MzOQ", + "profile_banner_url": "https://pbs.twimg.com/profile_banners/1830023695835787264/1779629491", + "is_identity_verified": false, + "id": "1830023695835787264", + "verified_type": "blue" + } + }, + "260907612": { + "data": { + "username": "united", + "protected": false, + "description": "You’ve landed at the ✨official account✨ for United Airlines, where everyone is the main character on our flights. DM directly for assistance.", + "name": "United Airlines", + "created_at": "2011-03-04T21:23:11.000Z", + "public_metrics": { + "followers_count": 1177763, + "followers_count_str": "1177763", + "following_count": 35460, + "following_count_str": "35460", + "tweet_count": 1394090, + "tweet_count_str": "1394090", + "listed_count": 6195, + "listed_count_str": "6195", + "like_count": 11495, + "like_count_str": "11495", + "media_count": 4046, + "media_count_str": "4046" + }, + "entities": { + "url": { + "urls": [ + { + "start": 0, + "start_str": "0", + "end": 23, + "end_str": "23", + "url": "https://t.co/672Qvc9oMM", + "expanded_url": "http://united.com", + "display_url": "united.com" + } + ] + } + }, + "verified": true, + "profile_image_url": "https://pbs.twimg.com/profile_images/1605596728966713345/6eXslF13_normal.jpg", + "url": "https://t.co/672Qvc9oMM", + "profile_banner_url": "https://pbs.twimg.com/profile_banners/260907612/1718042549", + "is_identity_verified": false, + "id": "260907612", + "verified_type": "business" + } + } + } + } + } +} +``` + +### `dm.received` + +Fired when the filtered user receives an unencrypted DM. Same payload shape as `dm.sent` (`direct_message_events` plus a `users` map). Private event — requires user-context authentication. + +### `dm.read` + +Fired when a participant reads the filtered user's unencrypted DM (read receipt). Private event — requires user-context authentication. + +### `dm.indicate_typing` + +Fired when a participant is typing a message to the filtered user. Private event — requires user-context authentication. + +--- + +## News events + +### `news.new` + +Enterprise and Partner only. Filter by `keyword`. The `payload` includes Grok-curated news fields: + +| Field | Description | +| --- | --- | +| `category` | News category | +| `headline` | Headline text | +| `hook` | Short hook / teaser | +| `summary` | Longer summary | + +--- + +## Spaces events + +### `spaces.start` + +Fired when the filtered user starts a Space. + +### `spaces.end` + +Fired when the filtered user ends a Space. + +--- + +## Mute events + +Mute events use a `source` / `target` user pair similar to follow events. Private events — require user-context authentication with the `mute.read` scope. The `user_id` filter matches the user performing the mute or unmute. + +### `mute.mute` + +### `mute.unmute` + +--- + +## Block events + +Block events use a `source` / `target` user pair similar to follow events. Private events — require user-context authentication with the `block.read` scope. The `user_id` filter matches the user performing the block or unblock. + +### `block.block` + +### `block.unblock` + +--- + +## OAuth events + +### `oauth.revoke` + +Fired when a user revokes your application's access. The `filter` may be empty. Use this to clean up local state for the revoked user. + +```json +{ + "data": { + "event_uuid": "5934540941047412905", + "filter": {}, + "event_type": "oauth.revoke", + "payload": { + "date_time": "2026-07-23T21:44:05+00:00", + "user_id": "1830023695835787264", + "app_id": "29820954" + } + } +} +``` + +--- + +## Next steps + + + + Supported event types, privacy, and authentication + + + Create a subscription and receive events + + + Connect to the persistent HTTP stream + + + Deliver activity events to your webhook URL + + diff --git a/x-api/activity/introduction.mdx b/x-api/activity/introduction.mdx index 1db116dde..1eb44f2cf 100644 --- a/x-api/activity/introduction.mdx +++ b/x-api/activity/introduction.mdx @@ -20,7 +20,7 @@ The X Activity API currently supports the following delivery mechanisms to send ## Supported event types -Currently, X Activity API supports the following event types, organized by category: +Currently, X Activity API supports the following event types, organized by category. For sample JSON for each type, see [Event payloads](/x-api/activity/event-payloads). ### Post events @@ -145,6 +145,14 @@ Block events are triggered when the filtered user blocks or unblocks another use **Private events:** Block events are private and require user-context (OAuth 2.0) authentication with the `block.read` scope. The `user_id` filter matches the user performing the block or unblock — you cannot subscribe to notifications about a user *being* blocked. See [Event privacy and authentication](#event-privacy-and-authentication) below. +### OAuth events + +OAuth events are triggered when a user revokes your application's access. + +| Event Name | Description | Filters | +| --- | --- | --- | +| `oauth.revoke` | Fired when a user revokes app authorization | none | + In future releases, XAA will expand to support additional event types including social interactions, content engagement, monetization features, and more. We will continue to update our docs when new event types become available. ## Event privacy and authentication @@ -214,9 +222,12 @@ To access these endpoints, you will need: Learn more about getting access to the X API v2 endpoints in our [getting started guide](/x-api/getting-started/getting-access). -
+
+
diff --git a/x-api/activity/quickstart.mdx b/x-api/activity/quickstart.mdx index 9e8047d23..740228d24 100644 --- a/x-api/activity/quickstart.mdx +++ b/x-api/activity/quickstart.mdx @@ -286,6 +286,9 @@ curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \ ## Next steps + + Sample JSON for each activity event type + Full endpoint documentation diff --git a/x-api/llms.txt b/x-api/llms.txt index a0a9501e9..f0a23486c 100644 --- a/x-api/llms.txt +++ b/x-api/llms.txt @@ -22,6 +22,7 @@ - [Create X Activity Subscription](https://docs.x.com/x-api/activity/create-x-activity-subscription.md): Reference documentation for the endpoint and related functionality. - [Delete X Activity Subscriptions By Ids](https://docs.x.com/x-api/activity/delete-x-activity-subscriptions-by-ids.md): Reference documentation for the endpoint and related functionality. - [Deletes X Activity Subscription](https://docs.x.com/x-api/activity/deletes-x-activity-subscription.md): Reference documentation for the endpoint and related functionality. +- [Event payloads](https://docs.x.com/x-api/activity/event-payloads.md): Sample JSON payloads for X Activity API events - [Get X Activity Subscriptions](https://docs.x.com/x-api/activity/get-x-activity-subscriptions.md): Reference documentation for the endpoint and related functionality. - [Introduction](https://docs.x.com/x-api/activity/introduction.md): import { Button } from '/snippets/button.mdx'; The X Activity API (XAA) endpoint group allows developers to tap in to - [Quickstart](https://docs.x.com/x-api/activity/quickstart.md)