> ## Documentation Index > Fetch the complete documentation index at: https://docs.x.com/llms.txt > Use this file to discover all available pages before exploring further. # Account Activity API v2 소개 및 개요 안내 > Account Activity API(AAA)는 X의 계정 활동 이벤트를 웹훅으로 실시간 수신하는 방법을 제공합니다. X API v2 스탠다드 티어의 계정 활동(account activity)에 관한 공식 API 레퍼런스 문서입니다. export const Button = ({href, children}) => { return
; }; Account Activity API(AAA)는 지원 중단 예정입니다. 앞으로는 실시간 사용자 활동 전달을 위해 [X Activity API(XAA)](/x-api/activity/introduction)를 확인하세요. Account Activity API(AAA)는 웹훅을 통해 X 사용자 계정과 관련된 실시간 이벤트를 받을 수 있는 방법을 제공합니다. 사전 구성된 웹훅에 특정 사용자 계정을 구독함으로써, 애플리케이션은 단일 연결을 통해 소유 또는 구독된 하나 이상의 계정에서 Post, 다이렉트 메시지, 좋아요, 팔로우, 차단 등 다양한 활동에 대한 알림을 받을 수 있습니다. 이 API는 일반적으로 사용자 액션에 즉각적으로 반응해야 하거나 사용자 활동을 기반으로 최신 상태를 유지해야 하는 애플리케이션을 구축하는 데 사용됩니다. ## 개요 이벤트가 서버로 실시간으로 전달됩니다 X의 속도로 데이터를 전달 — 폴링이 필요 없음 Post, DM, 팔로우, 좋아요, 차단, 뮤트 등 사용자 계정을 구독하여 모든 활동을 받음 *** ## 작동 방식 1. **웹훅 등록** — [V2 Webhooks API](/x-api/webhooks/introduction)를 통해 웹훅 URL을 등록합니다 2. **사용자 구독** — 웹훅에 사용자 구독을 추가합니다 3. **이벤트 수신** — JSON 페이로드가 포함된 POST 요청으로 활동 이벤트를 받습니다 4. **이벤트 처리** — 애플리케이션에서 이벤트를 처리하고 `200 OK`로 응답합니다 *** ## 활동 유형 웹훅 등록의 각 사용자 구독에 대해 아래 관련 활동을 모두 받게 됩니다: * **Post** (사용자별) * **Post 삭제** (사용자별) * **@멘션** (사용자에 대한) * **답글** (사용자에 대한 또는 사용자로부터) * **리포스트** (사용자별 또는 사용자에 대한) * **인용 Post** (사용자별 또는 사용자에 대한) * **인용 Post의 리포스트** (사용자별 또는 사용자에 대한) * **좋아요** (사용자별 또는 사용자에 대한) * **팔로우** (사용자별 또는 사용자에 대한) * **언팔로우** (사용자별 또는 사용자에 대한) * **차단** (사용자별 또는 사용자에 대한) * **차단 해제** (사용자별 또는 사용자에 대한) * **뮤트** (사용자별 또는 사용자에 대한) * **뮤트 해제** (사용자별 또는 사용자에 대한) * **다이렉트 메시지 발송** (사용자별) * **다이렉트 메시지 수신** (사용자별) * **입력 표시기** (사용자에 대한) * **읽음 확인** (사용자에 대한) * **구독 취소** (사용자별) Account Activity API를 통해서는 홈 타임라인 데이터를 전달하지 않습니다. 이 데이터를 가져오려면 [User ID로 User Posts 타임라인 조회](/x-api/users/get-posts) 엔드포인트를 사용하세요. Account Activity API에서 반환되는 Post는 월간 [Post cap](/x-api/fundamentals/post-cap)에 포함됩니다. *** ## 기능 요약 | 등급 | 고유 구독 수 | 웹훅 수 | | :---------- | :------ | :--- | | Pay Per Use | 3 | 1 | | Enterprise | 5000+ | 5+ | *** ## Account Activity 데이터 객체 구조 | 객체 | 세부 정보 | | :-------------- | :-------------------------------------------------------- | | `for_user_id` | 이벤트와 관련된 사용자 구독을 식별합니다. | | `is_blocked_by` | (조건부) 멘션을 한 사용자가 구독된 사용자에 의해 차단된 경우 Post 멘션 이벤트에서만 표시됩니다. | | `source` | 활동을 수행하는 사용자(예: 팔로우, 차단 또는 뮤트하는 사용자). | | `target` | 활동이 적용되는 사용자(예: 팔로우되거나 차단되거나 뮤트되는 사용자). | ### 사용 가능한 활동 | 메시지 유형 | 세부 정보 | | :-------------------------------------- | :--------------------------------------------------- | | `tweet_create_events` | Post, 리트윗, 답글, @멘션, 인용 트윗 또는 인용 트윗의 리트윗에 대한 Post 상태. | | `favorite_events` | 사용자 및 대상이 포함된 좋아요 이벤트. | | `follow_events` | 사용자 및 대상이 포함된 팔로우 이벤트. | | `unfollow_events` | 사용자 및 대상이 포함된 언팔로우 이벤트. | | `block_events` | 사용자 및 대상이 포함된 차단 이벤트. | | `unblock_events` | 사용자 및 대상이 포함된 차단 해제 이벤트. | | `mute_events` | 사용자 및 대상이 포함된 뮤트 이벤트. | | `unmute_events` | 사용자 및 대상이 포함된 뮤트 해제 이벤트. | | `user_event` | 사용자가 앱 인증을 제거할 때 발생하는 취소 이벤트(구독 자동 삭제). | | `direct_message_events` | 발송 또는 수신된 메시지에 대한 DM 상태. | | `direct_message_indicate_typing_events` | 사용자 및 대상이 포함된 DM 입력 이벤트. | | `direct_message_mark_read_events` | 사용자 및 대상이 포함된 DM 읽음 이벤트. | | `tweet_delete_events` | 규정 준수를 위한 삭제된 Post 알림. | *** ## 페이로드 예시 각 Account Activity 이벤트에 대한 페이로드 예시입니다. ### tweet\_create\_events (Post, 리트윗, 답글, 인용 트윗) ```json theme={null} { "for_user_id": "2244994945", "tweet_create_events": [ { } ] } ``` ### tweet\_create\_events (@멘션) ```json theme={null} { "for_user_id": "2244994945", "user_has_blocked": "false", "tweet_create_events": [ { } ] } ``` ### favorite\_events ```json theme={null} { "for_user_id": "2244994945", "favorite_events": [{ "id": "a7ba59eab0bfcba386f7acedac279542", "created_at": "Mon Mar 26 16:33:26 +0000 2018", "timestamp_ms": 1522082006140, "favorited_status": { }, "user": { } }] } ``` ### follow\_events ```json theme={null} { "for_user_id": "2244994945", "follow_events": [{ "type": "follow", "created_timestamp": "1517588749178", "target": { }, "source": { } }] } ``` ### unfollow\_events ```json theme={null} { "for_user_id": "2244994945", "follow_events": [{ "type": "unfollow", "created_timestamp": "1517588749178", "target": { }, "source": { } }] } ``` ### block\_events ```json theme={null} { "for_user_id": "2244994945", "block_events": [{ "type": "block", "created_timestamp": "1518127020304", "source": { }, "target": { } }] } ``` ### unblock\_events ```json theme={null} { "for_user_id": "2244994945", "block_events": [{ "type": "unblock", "created_timestamp": "1518127020304", "source": { }, "target": { } }] } ``` ### mute\_events ```json theme={null} { "for_user_id": "2244994945", "mute_events": [ { "type": "mute", "created_timestamp": "1518127020304", "source": { }, "target": { } } ] } ``` ### unmute\_events ```json theme={null} { "for_user_id": "2244994945", "mute_events": [ { "type": "unmute", "created_timestamp": "1518127020304", "source": { }, "target": { } } ] } ``` ### user\_event ```json theme={null} { "user_event": { "revoke": { "date_time": "2018-05-24T09:48:12+00:00", "target": { "app_id": "13090192" }, "source": { "user_id": "63046977" } } } } ``` ### direct\_message\_events ```json theme={null} { "for_user_id": "4337869213", "direct_message_events": [{ "type": "message_create", "id": "954491830116155396", "created_timestamp": "1516403560557", "message_create": { "target": { "recipient_id": "4337869213" }, "sender_id": "3001969357", "source_app_id": "13090192", "message_data": { "text": "Hello World!", "entities": { "hashtags": [], "symbols": [], "user_mentions": [], "urls": [] } } } }], "apps": { "13090192": { "id": "13090192", "name": "FuriousCamperTestApp1", "url": "https://x.com/furiouscamper" } }, "users": { "3001969357": { "id": "3001969357", "created_timestamp": "1422556069340", "name": "Jordan Brinks", "screen_name": "furiouscamper", "location": "Boulder, CO", "description": "Alter Ego - X PE opinions-are-my-own", "url": "https://t.co/SnxaA15ZuY", "protected": false, "verified": false, "followers_count": 22, "friends_count": 45, "statuses_count": 494, "profile_image_url_https": "https://pbs.twimg.com/profile_images/851526626785480705/cW4WTi7C_normal.jpg" }, "4337869213": { "id": "4337869213", "created_timestamp": "1448312972328", "name": "Harrison Test", "screen_name": "Harris_0ff", "location": "Burlington, MA", "protected": false, "verified": false, "followers_count": 8, "friends_count": 8, "statuses_count": 240, "profile_image_url_https": "https://abs.twimg.com/sticky/default_profile_images/default_profile_normal.png" } } } ``` ### direct\_message\_indicate\_typing\_events ```json theme={null} { "for_user_id": "4337869213", "direct_message_indicate_typing_events": [{ "created_timestamp": "1518127183443", "sender_id": "3284025577", "target": { "recipient_id": "3001969357" } }], "users": { "3001969357": { "id": "3001969357", "created_timestamp": "1422556069340", "name": "Jordan Brinks", "screen_name": "furiouscamper", "location": "Boulder, CO", "description": "Alter Ego - X PE opinions-are-my-own", "url": "https://t.co/SnxaA15ZuY", "protected": false, "verified": false, "followers_count": 23, "friends_count": 47, "statuses_count": 509, "profile_image_url_https": "https://pbs.twimg.com/profile_images/851526626785480705/cW4WTi7C_normal.jpg" }, "3284025577": { "id": "3284025577", "created_timestamp": "1437281176085", "name": "Bogus Bogart", "screen_name": "bogusbogart", "protected": true, "verified": false, "followers_count": 1, "friends_count": 4, "statuses_count": 35, "profile_image_url_https": "https://pbs.twimg.com/profile_images/763383202857779200/ndvZ96mE_normal.jpg" } } } ``` ### direct\_message\_mark\_read\_events ```json theme={null} { "for_user_id": "4337869213", "direct_message_mark_read_events": [{ "created_timestamp": "1518452444662", "sender_id": "199566737", "target": { "recipient_id": "3001969357" }, "last_read_event_id": "963085315333238788" }], "users": { "199566737": { "id": "199566737", "created_timestamp": "1286429788000", "name": "Le Braat", "screen_name": "LeBraat", "location": "Denver, CO", "description": "data by day @X, design by dusk", "protected": false, "verified": false, "followers_count": 299, "friends_count": 336, "statuses_count": 752, "profile_image_url_https": "https://pbs.twimg.com/profile_images/936652894371119105/YHEozVAg_normal.jpg" }, "3001969357": { "id": "3001969357", "created_timestamp": "1422556069340", "name": "Jordan Brinks", "screen_name": "furiouscamper", "location": "Boulder, CO", "description": "Alter Ego - X PE opinions-are-my-own", "url": "https://t.co/SnxaA15ZuY", "protected": false, "verified": false, "followers_count": 23, "friends_count": 48, "statuses_count": 510, "profile_image_url_https": "https://pbs.twimg.com/profile_images/851526626785480705/cW4WTi7C_normal.jpg" } } } ``` ### tweet\_delete\_events ```json theme={null} { "for_user_id": "930524282358325248", "tweet_delete_events": [ { "status": { "id": "1045405559317569537", "user_id": "930524282358325248" }, "timestamp_ms": "1432228155593" } ] } ``` *** ## 롱폼 Post 지원 V2 Account Activity API는 280자를 초과하는 **롱폼** Post를 지원합니다. 롱폼 Post가 `tweet_create_events` 페이로드에 포함되면, `text` 필드에는 처음 140자(또는 그 이하)가 담기고 `truncated` 필드는 `true`로 설정됩니다. Post의 전체 콘텐츠는 `extended_tweet` 객체에 전달되며, 여기에는 다음이 포함됩니다: * `full_text` — 280자 제한을 넘어서는 문자까지 포함한 Post 전체 텍스트. * `entities` — 280자 이후에 등장하는 것을 포함하여 전체 텍스트에 나타나는 모든 엔터티(예: 해시태그, URL, 사용자 멘션, 심볼). * `display_text_range` — 전체 텍스트를 고려한 표시할 문자 범위. 이를 통해 애플리케이션은 텍스트 뒤쪽에 나타나는 멘션이나 기타 엔터티를 포함한 롱폼 Post의 전체 콘텐츠를 처리할 수 있습니다. 다음은 롱폼 Post에 대한 `tweet_create_events` 페이로드의 예입니다: ```json theme={null} { "for_user_id": "1603419180975409153", "tweet_create_events": [ { "created_at": "Mon May 19 14:01:46 +0000 2025", "id": 1924465506158879000, "id_str": "1924465506158878979", "text": "The Antikythera Mechanism: A Window into Ancient Ingenuity Discovered in 1901 among the wreckage of a Roman ship of… https://t.co/bzbEKj8cd8", "display_text_range": [0, 140], "truncated": true, "user": { ... }, "extended_tweet": { "full_text": "The Antikythera Mechanism: A Window into Ancient Ingenuity Discovered in 1901 among the wreckage of a Roman ship off the Greek island of Antikythera...", "display_text_range": [0, 2051], "entities": { "hashtags": [], "urls": [], "user_mentions": [ { "screen_name": "xai", "name": "xAI", "id": 1661523610111193000, "id_str": "1661523610111193088", "indices": [2032, 2036] }, { "screen_name": "HistoryInPics", "name": "History Photographed", "id": 1582853809, "id_str": "1582853809", "indices": [2037, 2051] } ], "symbols": [] } }, "entities": { "hashtags": [], "urls": [ { "url": "https://t.co/bzbEKj8cd8", "expanded_url": "https://twitter.com/i/web/status/1924465506158878979", "display_url": "twitter.com/i/web/status/1…", "indices": [117, 140] } ], "user_mentions": [], "symbols": [] } } ] } ``` *** ## 자주 묻는 질문 Account Activity API는 웹훅을 사용하여 열린 연결(스트리밍 API와 달리)이나 잦은 폴링(REST API와 달리) 없이도 실시간으로 데이터를 전달합니다. 장점은 다음과 같습니다: * **속도** — X의 속도로 데이터를 전달합니다. * **단순함** — Post, @멘션, 답글, 리포스트, 인용 트윗, 좋아요, DM, 팔로우, 차단, 뮤트를 포함한 모든 계정 이벤트를 단일 웹훅 연결을 통해 제공합니다. * **확장성** — 관리 대상 계정의 모든 활동을 속도 제한이나 이벤트 상한 없이 지원합니다(Enterprise 등급). 네! [V2 Webhooks API](/x-api/webhooks/introduction)를 통해 여러 웹훅 URL을 등록하고 구독을 별도로 관리할 수 있습니다. 네! [Account Activity API 빠른 시작](/x-api/account-activity/quickstart), [웹훅 시작 가이드](/x-api/webhooks/quickstart), 그리고 [Account Activity API 샘플 애플리케이션](https://github.com/xdevplatform/account-activity-dashboard-enterprise/tree/master)을 참조하세요. 인증 요구사항은 엔드포인트에 따라 다릅니다: * **사용자별 작업**(예: 사용자 구독)에는 **OAuth 1.0a**(3-legged OAuth 흐름)가 필요합니다. * **앱 수준 작업**(예: 구독 목록 조회/삭제, 구독 수)에는 **OAuth2 App Only Bearer Token**이 필요합니다. 자세한 내용은 [인증 섹션](/fundamentals/authentication/overview)을 검토하세요. 네. 앱에 사용자 A와 사용자 B에 대한 구독이 있고, 사용자 A가 Post에서 사용자 B를 멘션하면 웹훅은 두 개의 이벤트를 받습니다(사용자별로 하나씩). `for_user_id` 필드를 사용하여 구독을 식별하세요. 아니요. `/all/` 제품이 유일한 옵션이며, 지원되는 모든 이벤트 유형을 전달합니다. 웹훅 한도는 앱별이 아니라 계정 수준에서 설정됩니다. 예를 들어, 세 개의 웹훅과 두 개의 앱이 있는 경우 한 앱에 두 개의 웹훅을, 다른 앱에 하나를 사용할 수 있지만 각 앱에 세 개씩 사용할 수는 없습니다. *** ## API 레퍼런스 인덱스 | 목적 | V2 엔드포인트 | | :------------------ | :-------------------------------------------------------------------------------------------------------------------------- | | 계정의 이벤트에 애플리케이션을 구독 | [`POST /2/account_activity/webhooks/:webhook_id/subscriptions/all`](/x-api/account-activity/create-subscription) | | 현재 활성 구독 수 반환 | [`GET /2/account_activity/subscriptions/count`](/x-api/account-activity/get-subscription-count) | | 웹훅이 계정에 구독되어 있는지 확인 | [`GET /2/account_activity/webhooks/:webhook_id/subscriptions/all`](/x-api/account-activity/validate-subscription) | | 현재 활성 구독 목록 반환 | [`GET /2/account_activity/webhooks/:webhook_id/subscriptions/all/list`](/x-api/account-activity/get-subscriptions) | | 앱 전용 OAuth로 구독 비활성화 | [`DELETE /2/account_activity/webhooks/:webhook_id/subscriptions/:user_id/all`](/x-api/account-activity/delete-subscription) | | 리플레이 작업 생성 | [`POST /2/account_activity/replay/webhooks/:webhook_id/subscriptions/all`](/x-api/account-activity/create-replay-job) | 웹훅 관리 엔드포인트(등록, 조회, 검증, 삭제)에 대해서는 [V2 Webhooks API 문서](/x-api/webhooks/introduction)를 참조하세요. *** ## 시작하기 **사전 요구 사항** * 승인된 [개발자 계정](https://developer.x.com/en/portal/petition/essential/basic-info) * Developer Console 내의 [프로젝트 및 앱](/resources/fundamentals/developer-apps) * 공개적으로 접근 가능한 HTTPS 웹훅 엔드포인트 * Account Activity API에 대한 Enterprise 또는 Pay Per Use 접근 권한 구독을 설정하고 이벤트 수신 시작 웹훅 등록 및 관리 레거시 Enterprise에서 v2로 마이그레이션 웹훅에 대한 스트리밍 대안