Account Activity API v2 소개 및 개요 안내

Account Activity API(AAA)는 지원 중단 예정입니다. 앞으로는 실시간 사용자 활동 전달을 위해 X Activity API(XAA)를 확인하세요.

Account Activity API(AAA)는 웹훅을 통해 X 사용자 계정과 관련된 실시간 이벤트를 받을 수 있는 방법을 제공합니다. 사전 구성된 웹훅에 특정 사용자 계정을 구독함으로써, 애플리케이션은 단일 연결을 통해 소유 또는 구독된 하나 이상의 계정에서 Post, 다이렉트 메시지, 좋아요, 팔로우, 차단 등 다양한 활동에 대한 알림을 받을 수 있습니다. 이 API는 일반적으로 사용자 액션에 즉각적으로 반응해야 하거나 사용자 활동을 기반으로 최신 상태를 유지해야 하는 애플리케이션을 구축하는 데 사용됩니다.

개요

웹훅 전달

이벤트가 서버로 실시간으로 전달됩니다

실시간

X의 속도로 데이터를 전달 — 폴링이 필요 없음

포괄적

Post, DM, 팔로우, 좋아요, 차단, 뮤트 등

구독 기반

사용자 계정을 구독하여 모든 활동을 받음

작동 방식

웹훅 등록 — V2 Webhooks API를 통해 웹훅 URL을 등록합니다
사용자 구독 — 웹훅에 사용자 구독을 추가합니다
이벤트 수신 — JSON 페이로드가 포함된 POST 요청으로 활동 이벤트를 받습니다
이벤트 처리 — 애플리케이션에서 이벤트를 처리하고 200 OK로 응답합니다

활동 유형

웹훅 등록의 각 사용자 구독에 대해 아래 관련 활동을 모두 받게 됩니다:

Post (사용자별)
Post 삭제 (사용자별)
@멘션 (사용자에 대한)
답글 (사용자에 대한 또는 사용자로부터)
리포스트 (사용자별 또는 사용자에 대한)
인용 Post (사용자별 또는 사용자에 대한)
인용 Post의 리포스트 (사용자별 또는 사용자에 대한)
좋아요 (사용자별 또는 사용자에 대한)
팔로우 (사용자별 또는 사용자에 대한)
언팔로우 (사용자별 또는 사용자에 대한)
차단 (사용자별 또는 사용자에 대한)
차단 해제 (사용자별 또는 사용자에 대한)
뮤트 (사용자별 또는 사용자에 대한)
뮤트 해제 (사용자별 또는 사용자에 대한)
다이렉트 메시지 발송 (사용자별)
다이렉트 메시지 수신 (사용자별)
입력 표시기 (사용자에 대한)
읽음 확인 (사용자에 대한)
구독 취소 (사용자별)

Account Activity API를 통해서는 홈 타임라인 데이터를 전달하지 않습니다. 이 데이터를 가져오려면 User ID로 User Posts 타임라인 조회 엔드포인트를 사용하세요.Account Activity API에서 반환되는 Post는 월간 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, 리트윗, 답글, 인용 트윗)

{
  "for_user_id": "2244994945",
  "tweet_create_events": [
    {
      <Tweet Object>
    }
  ]
}

tweet_create_events (@멘션)

{
  "for_user_id": "2244994945",
  "user_has_blocked": "false",
  "tweet_create_events": [
    {
      <Tweet Object>
    }
  ]
}

favorite_events

{
  "for_user_id": "2244994945",
  "favorite_events": [{
    "id": "a7ba59eab0bfcba386f7acedac279542",
    "created_at": "Mon Mar 26 16:33:26 +0000 2018",
    "timestamp_ms": 1522082006140,
    "favorited_status": {
      <Tweet Object>
    },
    "user": {
      <User Object>
    }
  }]
}

follow_events

{
  "for_user_id": "2244994945",
  "follow_events": [{
    "type": "follow",
    "created_timestamp": "1517588749178",
    "target": {
      <User Object>
    },
    "source": {
      <User Object>
    }
  }]
}

unfollow_events

{
  "for_user_id": "2244994945",
  "follow_events": [{
    "type": "unfollow",
    "created_timestamp": "1517588749178",
    "target": {
      <User Object>
    },
    "source": {
      <User Object>
    }
  }]
}

block_events

{
  "for_user_id": "2244994945",
  "block_events": [{
    "type": "block",
    "created_timestamp": "1518127020304",
    "source": {
      <User Object>
    },
    "target": {
      <User Object>
    }
  }]
}

unblock_events

{
  "for_user_id": "2244994945",
  "block_events": [{
    "type": "unblock",
    "created_timestamp": "1518127020304",
    "source": {
      <User Object>
    },
    "target": {
      <User Object>
    }
  }]
}

mute_events

{
  "for_user_id": "2244994945",
  "mute_events": [
    {
      "type": "mute",
      "created_timestamp": "1518127020304",
      "source": {
        <User Object>
      },
      "target": {
        <User Object>
      }
    }
  ]
}

unmute_events

{
  "for_user_id": "2244994945",
  "mute_events": [
    {
      "type": "unmute",
      "created_timestamp": "1518127020304",
      "source": {
        <User Object>
      },
      "target": {
        <User Object>
      }
    }
  ]
}

user_event

{
  "user_event": {
    "revoke": {
      "date_time": "2018-05-24T09:48:12+00:00",
      "target": {
        "app_id": "13090192"
      },
      "source": {
        "user_id": "63046977"
      }
    }
  }
}

direct_message_events

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

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

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

{
  "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 페이로드의 예입니다:

{
  "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 사용의 장점은 무엇인가요?

Account Activity API는 웹훅을 사용하여 열린 연결(스트리밍 API와 달리)이나 잦은 폴링(REST API와 달리) 없이도 실시간으로 데이터를 전달합니다. 장점은 다음과 같습니다:

속도 — X의 속도로 데이터를 전달합니다.
단순함 — Post, @멘션, 답글, 리포스트, 인용 트윗, 좋아요, DM, 팔로우, 차단, 뮤트를 포함한 모든 계정 이벤트를 단일 웹훅 연결을 통해 제공합니다.
확장성 — 관리 대상 계정의 모든 활동을 속도 제한이나 이벤트 상한 없이 지원합니다(Enterprise 등급).

개발, 스테이징, 프로덕션 환경이 필요합니다. 가능한가요?

네! V2 Webhooks API를 통해 여러 웹훅 URL을 등록하고 구독을 별도로 관리할 수 있습니다.

설정을 위한 단계별 가이드가 있나요?

네! Account Activity API 빠른 시작, 웹훅 시작 가이드, 그리고 Account Activity API 샘플 애플리케이션을 참조하세요.

Account Activity API에는 어떤 인증이 필요한가요?

인증 요구사항은 엔드포인트에 따라 다릅니다:

사용자별 작업(예: 사용자 구독)에는 OAuth 1.0a(3-legged OAuth 흐름)가 필요합니다.
앱 수준 작업(예: 구독 목록 조회/삭제, 구독 수)에는 OAuth2 App Only Bearer Token이 필요합니다.

자세한 내용은 인증 섹션을 검토하세요.

서로 상호작용하는 사용자들에게 구독하면 중복 활동을 받게 되나요?

네. 앱에 사용자 A와 사용자 B에 대한 구독이 있고, 사용자 A가 Post에서 사용자 B를 멘션하면 웹훅은 두 개의 이벤트를 받습니다(사용자별로 하나씩). for_user_id 필드를 사용하여 구독을 식별하세요.

전달되는 활동을 제한하기 위해 엔드포인트의 /all/을 대체할 수 있나요?

아니요. /all/ 제품이 유일한 옵션이며, 지원되는 모든 이벤트 유형을 전달합니다.

세 개의 웹훅에 접근할 수 있다면 각 앱마다 세 개의 웹훅을 사용할 수 있나요?

웹훅 한도는 앱별이 아니라 계정 수준에서 설정됩니다. 예를 들어, 세 개의 웹훅과 두 개의 앱이 있는 경우 한 앱에 두 개의 웹훅을, 다른 앱에 하나를 사용할 수 있지만 각 앱에 세 개씩 사용할 수는 없습니다.

API 레퍼런스 인덱스

목적	V2 엔드포인트
계정의 이벤트에 애플리케이션을 구독	`POST /2/account_activity/webhooks/:webhook_id/subscriptions/all`
현재 활성 구독 수 반환	`GET /2/account_activity/subscriptions/count`
웹훅이 계정에 구독되어 있는지 확인	`GET /2/account_activity/webhooks/:webhook_id/subscriptions/all`
현재 활성 구독 목록 반환	`GET /2/account_activity/webhooks/:webhook_id/subscriptions/all/list`
앱 전용 OAuth로 구독 비활성화	`DELETE /2/account_activity/webhooks/:webhook_id/subscriptions/:user_id/all`
리플레이 작업 생성	`POST /2/account_activity/replay/webhooks/:webhook_id/subscriptions/all`

웹훅 관리 엔드포인트(등록, 조회, 검증, 삭제)에 대해서는 V2 Webhooks API 문서를 참조하세요.

시작하기

사전 요구 사항

승인된 개발자 계정
Developer Console 내의 프로젝트 및 앱
공개적으로 접근 가능한 HTTPS 웹훅 엔드포인트
Account Activity API에 대한 Enterprise 또는 Pay Per Use 접근 권한

빠른 시작

구독을 설정하고 이벤트 수신 시작

Webhooks API

웹훅 등록 및 관리

마이그레이션 가이드

레거시 Enterprise에서 v2로 마이그레이션

활동 스트림

웹훅에 대한 스트리밍 대안

Getting Started

Products

Fundamentals

Partners & Customers

Resources

Account Activity API v2 소개 및 개요 안내

개요

웹훅 전달

실시간

포괄적

구독 기반

작동 방식

활동 유형

기능 요약

Account Activity 데이터 객체 구조

사용 가능한 활동

페이로드 예시

tweet_create_events (Post, 리트윗, 답글, 인용 트윗)

tweet_create_events (@멘션)

favorite_events

follow_events

unfollow_events

block_events

unblock_events

mute_events

unmute_events

user_event

direct_message_events

direct_message_indicate_typing_events

direct_message_mark_read_events

tweet_delete_events

롱폼 Post 지원

자주 묻는 질문

API 레퍼런스 인덱스

시작하기

빠른 시작

Webhooks API

마이그레이션 가이드

활동 스트림

​개요

웹훅 전달

실시간

포괄적

구독 기반

​작동 방식

​활동 유형

​기능 요약

​Account Activity 데이터 객체 구조

​사용 가능한 활동

​페이로드 예시

​tweet_create_events (Post, 리트윗, 답글, 인용 트윗)

​tweet_create_events (@멘션)

​favorite_events

​follow_events

​unfollow_events

​block_events

​unblock_events

​mute_events

​unmute_events

​user_event

​direct_message_events

​direct_message_indicate_typing_events

​direct_message_mark_read_events

​tweet_delete_events

​롱폼 Post 지원

​자주 묻는 질문

​API 레퍼런스 인덱스

​시작하기

빠른 시작

Webhooks API

마이그레이션 가이드

활동 스트림

개요

작동 방식

활동 유형

기능 요약

Account Activity 데이터 객체 구조

사용 가능한 활동

페이로드 예시

tweet_create_events (Post, 리트윗, 답글, 인용 트윗)

tweet_create_events (@멘션)

favorite_events

follow_events

unfollow_events

block_events

unblock_events

mute_events

unmute_events

user_event

direct_message_events

direct_message_indicate_typing_events

direct_message_mark_read_events

tweet_delete_events

롱폼 Post 지원

자주 묻는 질문

API 레퍼런스 인덱스

시작하기