Account Activity API: 엔터프라이즈

이 엔드포인트에는 게시물 편집 메타데이터가 포함되도록 업데이트되었습니다. 해당 메타데이터에 대해서는 “게시물 편집” 기초 페이지에서 자세히 알아보세요. 이 엔드포인트는 다이렉트 메시지 엔드포인트와 함께 자주 사용됩니다. 새로운 v2 다이렉트 메시지 엔드포인트를 출시했습니다. 엔터프라이즈 및 프리미엄 Account Activity API는 v2 1:1 메시지를 지원하지만, 아직 그룹 대화는 지원하지 않습니다.

개요 Enterprise Account Activity API는 웹훅을 통해 사용자 계정과 관련된 실시간 활동을 구독할 수 있는 기능을 제공합니다. 즉, 단일 연결로 보유하거나 구독 중인 하나 이상의 계정에서 실시간 게시물, 다이렉트 메시지, 기타 계정 이벤트를 수신할 수 있습니다. 웹훅 등록 시 각 사용자 구독에 대해 아래의 모든 관련 활동을 수신합니다:

활동 유형
* 게시물(사용자 기준) * 게시물 삭제(사용자 기준) * @멘션(사용자 대상) * 답글(사용자에게 또는 사용자로부터) * 리포스트(사용자에 의한 또는 사용자를 대상으로 한) * 인용 게시물(사용자에 의한 또는 사용자를 대상으로 한) * 인용 게시물의 리포스트(사용자에 의한 또는 사용자를 대상으로 한) * 좋아요(사용자에 의한 또는 사용자를 대상으로 한) * 팔로우(사용자에 의한 또는 사용자를 대상으로 한) * 언팔로우(사용자 기준)	* 차단(사용자 기준) * 차단 해제(사용자 기준) * 뮤트(사용자 기준) * 뮤트 해제(사용자 기준) * 다이렉트 메시지 발신(사용자 기준) * 다이렉트 메시지 수신(사용자 기준) * 입력 중 표시(사용자에게) * 읽음 확인(사용자에게) * 구독 취소(사용자 기준)

활동 유형

* 게시물(사용자 기준)

* 게시물 삭제(사용자 기준)
* @멘션(사용자 대상)
* 답글(사용자에게 또는 사용자로부터)
* 리포스트(사용자에 의한 또는 사용자를 대상으로 한)
* 인용 게시물(사용자에 의한 또는 사용자를 대상으로 한)
* 인용 게시물의 리포스트(사용자에 의한 또는 사용자를 대상으로 한)
* 좋아요(사용자에 의한 또는 사용자를 대상으로 한)
* 팔로우(사용자에 의한 또는 사용자를 대상으로 한)

* 언팔로우(사용자 기준)

* 차단(사용자 기준)
* 차단 해제(사용자 기준)
* 뮤트(사용자 기준)
* 뮤트 해제(사용자 기준)
* 다이렉트 메시지 발신(사용자 기준)
* 다이렉트 메시지 수신(사용자 기준)
* 입력 중 표시(사용자에게)
* 읽음 확인(사용자에게)
* 구독 취소(사용자 기준)

참고 - Account Activity API를 통해 홈 타임라인 데이터는 제공되지 않습니다. 이 데이터를 가져오려면 GET statuses/home_timeline을 사용하세요.

동영상 시리즈

Account Activity API를 빠르게 익히려면 4부작 동영상 시리즈를 확인하세요!

기능 요약

티어	가격	고유 구독 수	웹훅 수	안정성 및 활동 복구
Enterprise	영업팀에 문의	최대 500개+	3개 이상	재시도 및 리플레이

궁금한 점이 있거나 오류가 발생하나요?
- 자주 묻는 질문 또는 오류 해결 가이드를 읽어보세요.
샘플 코드를 살펴보세요:
- Enterprise Account Activity API 대시보드: Account Activity API의 Enterprise 티어를 사용해 웹훅 이벤트를 표시하고 리플레이 기능을 포함한 Node 웹 앱입니다.
- SnowBot 챗봇: Enterprise Account Activity 및 Direct Message API를 기반으로 만든 Ruby 웹 앱입니다.

웹훅과 구독 사용자 관리

⏱ 읽는 데 10분 Enterprise Account Activity API는 귀하의 서비스에 구독된 X 계정과 관련된 이벤트가 발생할 때마다 웹훅 기반 JSON 메시지를 제공합니다. X는 해당 활동을 등록된 웹훅으로 전달합니다. 다음 단계에서는 웹훅과 구독 사용자를 관리하는 방법을 알아봅니다. 웹훅과 구독 사용자를 등록, 조회, 제거하는 방법을 다룹니다. 다양한 API 엔드포인트에 요청을 보내기 위해 간단한 cURL 명령을 사용할 것입니다. cURL은 URL 구문을 사용해 요청을 가져오거나 전송하는 명령줄 도구입니다. 필요한 사항:

등록된 X 앱 - 여기에서 등록
베어러 토큰 - 자세히 알아보기
Challenge-Response Check(CRC)를 통과하는 웹훅 - 자세히 알아보기
Enterprise 계정 - 여기에서 신청

시작하기 전에 X의 Account Activity API를 시작하는 데 도움이 되는 샘플 웹 앱과 보조 스크립트를 제공하는 GitHub 리포지토리를 확인하시기 바랍니다.

웹훅 관리:

웹훅을 사용하면 단일 연결로 사용자 계정과 관련된 실시간 활동을 구독할 수 있습니다.

웹훅 추가
웹훅 보기
웹훅 제거

해당 애플리케이션 컨텍스트에 대해 새 웹훅 URL 등록부터 시작하겠습니다.저장 전에 CRC 요청으로 URL이 검증됩니다. 웹훅을 등록한 후에는 나중에 필요하므로 웹훅 ID를 반드시 기록해 두세요.다음 항목을 수정한 뒤 아래 cURL 요청을 명령줄에 복사해 실행하세요:

URL <URL> 예: https://yourdomain.com/webhooks/twitter/
Consumer key <CONSUMER_KEY> 예: xvz1evFS4wEEPTGEFPHBog

Access token <ACCESS_TOKEN> 예: 370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb

curl --request POST --url 'https://api.x.com/1.1/account_activity/webhooks.json?url=<URL>' --header 'authorization: OAuth oauth_consumer_key="<CONSUMER_KEY>", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="<ACCESS_TOKEN>", oauth_version="1.0"'

구독 사용자 관리:

Webhook을 등록한 후 Account Activity API에 구독 사용자를 추가하여 해당 사용자의 계정 활동 수신을 시작할 수 있습니다.

구독 추가
구독 보기
구독 제거

모든 이벤트 유형을 받기 위해 사용자 구독부터 진행하겠습니다.아래 cURL 요청에서 다음 항목을 변경한 뒤 명령줄에 복사하세요:

Webhook ID <:WEBHOOK_ID> 예: 1234567890
Consumer key name <CONSUMER_KEY> 예: xvz1evFS4wEEPTGEFPHBog

구독 대상 사용자의 액세스 토큰 <SUBSCRIBING_USER'S_ACCESS_TOKEN> 예: 370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb

curl --request POST --url https://api.x.com/1.1/account_activity/webhooks/<:WEBHOOK_ID>/subscriptions/all.json --header 'authorization: OAuth oauth_consumer_key="<CONSUMER_KEY>", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="<SUBSCRIBING_USER'S_ACCESS_TOKEN>", oauth_version="1.0"'

잘하셨습니다! 이제 webhook과 구독 사용자를 관리할 수 있습니다.

참고 문서

Account Activity API 동영상 가이드

이 가이드에서는 Account Activity API의 프리미엄 및 엔터프라이즈 티어에서 제공되는 기능을 알아봅니다. 영상이 끝날 때까지 다음 기능을 학습하게 됩니다.

웹훅 등록
사용자 구독 추가
사용자 구독 제거
계정 활동 수신
계정 활동 재생

질문이 있으신가요? 오류가 발생했나요?
- 자주 묻는 질문 또는 오류 해결 가이드를 확인하세요.
샘플 코드를 살펴보세요:
- Enterprise Account Activity API 대시보드: Account Activity API의 엔터프라이즈 티어로 웹훅 이벤트를 표시하고 Replay 기능을 제공하는 Node 웹 앱입니다.
- SnowBot 챗봇: 엔터프라이즈 Account Activity 및 Direct Message API를 기반으로 만든 Ruby 웹 앱입니다.

Enterprise

웹후크 시작하기

Account Activity API는 개발자가 직접 개발·배포·호스팅하는 웹 앱으로 계정 이벤트를 전송하는 웹후크 기반 API입니다. 이벤트 컨슈머 애플리케이션에서 웹후크 이벤트를 받기 전에 챙겨야 할 ‘하부 구성’ 관련 사항이 몇 가지 있습니다. 아래 설명처럼 X 앱을 생성하고 Account Activity API 접근 권한을 얻은 뒤, 웹후크 이벤트를 처리하는 웹 앱을 개발해야 합니다.

1. X 앱을 생성하세요.

개발자 포털에서 승인된 개발자 계정으로 X 앱을 생성하세요. 회사 대표로 앱을 만들 경우 기업용 X 계정으로 생성할 것을 권장합니다. 개발자 계정을 신청하려면 여기를 클릭하세요.
앱 페이지의 permissions 탭에서 “Read, Write and Access direct messages”를 활성화하세요.
“Keys and Access Tokens” 탭에서 앱의 Consumer Key (API Key)와 Consumer Token (API Secret)을 메모해 두세요.
같은 탭에서 앱의 Access Token and Access Token Secret을 생성하세요. 이 액세스 토큰은 X가 계정 이벤트를 전송할 webhook URL을 등록하는 데 필요합니다.
X Sign-in과 X API에서 사용자 컨텍스트가 작동하는 방식이 익숙하지 않다면 Obtaining Access Tokens를 확인하세요. 이벤트를 수신할 계정을 추가할 때 해당 계정의 액세스 토큰으로 구독하게 됩니다.
개발자 포털의 “Apps” 페이지에 표시된 앱의 숫자형 ID를 기록해 두세요. Account Activity API 액세스를 신청할 때 이 앱 ID가 필요합니다.

2. Account Activity API 액세스 얻기

X 앱을 만든 후 다음 단계는 Account Activity API 액세스를 신청하는 것입니다. Account Activity API는 Enterprise에서만 제공되므로 아래 링크를 통해 신청서를 제출해야 합니다.

3. 웹훅 컨슈머 앱 개발

Account Activity API 액세스를 받은 후에는 X 웹훅 이벤트를 수신할 웹 앱을 개발하고 배포 및 호스팅해야 합니다.

이벤트 수신용 웹훅으로 사용할 URL을 갖춘 웹 앱을 만드세요. 이는 서버에 배포되어 들어오는 X 웹훅 이벤트를 수신하는 엔드포인트입니다.
- URI path는 전적으로 선택 사항입니다. 다음 예시는 유효합니다: https://mydomain.com_/service/listen_
- 다양한 소스의 웹훅을 수신하는 경우 일반적인 패턴은 다음과 같습니다: https://mydomain.com/webhook/twitter
- 지정된 URL에는 포트를 명시할 수 없다는 점에 유의하세요(https://mydomain.com:5000/NoWorkie).
Securing Webhooks 가이드에서 설명했듯이, 첫 단계는 X Challenge Response Check(CRC) GET 요청을 수신하고 올바르게 형식화된 JSON으로 응답하는 코드를 작성하는 것입니다.
웹훅 URL을 등록하세요. /webhooks.json?url= 엔드포인트에 POST 요청을 보냅니다. 이 요청을 보내면 X가 웹 앱에 CRC 요청을 전송합니다. 웹훅이 성공적으로 등록되면 응답에 웹훅 id가 포함됩니다. 이 웹훅 id는 이후 Account Activity API에 일부 요청을 할 때 필요합니다.
X는 등록한 URL로 계정 웹훅 이벤트를 전송합니다. 웹 앱이 들어오는 이벤트에 대한 POST 요청을 처리할 수 있는지 확인하세요. 이러한 이벤트는 JSON으로 인코딩됩니다. 예시 웹훅 JSON 페이로드는 HERE를 참조하세요.
웹 앱이 준비되면 다음 단계는 활동을 수신할 계정을 추가하는 것입니다. 계정을 추가(또는 삭제)할 때는 계정 id를 참조하여 POST 요청을 보냅니다. 자세한 내용은 구독 추가 가이드를 참조하세요.

4. 설정 검증

앱과 webhook이 올바르게 구성되었는지 확인하려면, 앱이 구독 중인 X 계정 중 하나가 올린 게시물을 즐겨찾기하세요. 구독자가 받는 각 즐겨찾기마다 webhook URL로의 POST 요청을 통해 favorite_events를 수신해야 합니다.
구독을 추가한 뒤 이벤트가 전송되기 시작하기까지 최대 10초가 걸릴 수 있습니다.

중요 사항

webhook URL을 등록할 때 웹 앱은 소비자 토큰과 시크릿, 그리고 앱 소유자의 사용자 액세스 토큰과 시크릿으로 인증해야 합니다.
모든 수신 Direct Message는 webhook을 통해 전달됩니다. 또한 POST direct_messages/events/new (message_create)로 전송된 모든 Direct Message도 webhook을 통해 전달됩니다. 이는 웹 앱이 다른 클라이언트를 통해 전송된 Direct Message도 파악할 수 있도록 하기 위함입니다.
모든 webhook 이벤트에는 해당 이벤트가 어떤 구독에 대해 전달되었는지를 나타내는 for_user_id 사용자 ID가 포함됩니다.
동일한 대화에서 두 사용자가 웹 앱으로 Direct Message를 사용 중인 경우, webhook은 중복 이벤트 두 개(각 사용자별 1개)를 수신합니다. 웹 앱은 이를 처리해야 합니다.
동일한 webhook URL을 공유하는 웹 앱이 둘 이상이고 동일한 사용자가 각 앱에 매핑되어 있다면, 동일한 이벤트가 webhook으로 여러 번 전송됩니다(웹 앱마다 한 번씩).
경우에 따라 webhook이 중복 이벤트를 받을 수 있습니다. webhook 앱은 이에 내결함성을 갖추고 이벤트 ID로 중복을 제거해야 합니다.
Quick Reply 요청 직후 바로 응답이 온다고 기대하지 마세요. 사용자는 Quick Reply 요청을 무시하고 기존 Direct Message로 응답할 수 있습니다. 또한 사용자는 메시지 스레드에서 이전에 응답하지 않았던 요청에 대해 Quick Reply로 응답할 수도 있습니다.
예제 코드:
- Enterprise Account Activity API 대시보드, Account Activity API의 엔터프라이즈 등급을 사용해 webhook 이벤트를 표시하고 Replay 기능을 포함한 Node 웹 앱입니다.
- SnowBot 챗봇, Account Activity 및 Direct Message API를 기반으로 만든 Ruby 웹 앱입니다. 이 코드베이스에는 Account Activity API webhook 설정을 돕는 스크립트가 포함되어 있습니다.

웹훅 보안

X의 웹훅 기반 API는 웹훅 서버의 보안을 확인하는 두 가지 방법을 제공합니다:

챌린지-응답 검증을 통해 X가 웹훅 이벤트를 수신하는 웹앱의 소유권을 확인합니다.
각 POST 요청의 서명 헤더를 통해 수신된 웹훅이 X에서 전송된 것임을 확인할 수 있습니다.

챌린지-응답 검사

앱과 웹훅 URL의 소유자가 모두 본인임을 확인하기 위해 X는 CRC(Challenge-Response Check)를 수행합니다. 이는 순환 중복 검사(cyclic redundancy check)와 혼동하면 안 됩니다. CRC가 전송되면 X는 ;crc_token 매개변수가 포함된 GET 요청을 웹 앱에 보냅니다. 이 요청을 수신하면 웹 앱은 crc_token 매개변수와 앱의 Consumer Secret(아래 참조)을 기반으로 암호화된 response_token을 생성해야 합니다. response_token은 JSON으로 인코딩되어야 하며(아래 예시 참조) 3초 이내에 반환되어야 합니다. 성공 시 웹훅 id가 반환됩니다. 웹훅 URL을 등록할 때 CRC가 전송되므로, CRC 응답 코드를 구현하는 것이 첫 번째 필수 단계입니다. 웹훅이 설정된 후에는, X가 마지막으로 성공적인 응답을 받은 시점으로부터 대략 24시간마다 CRC를 트리거합니다. 필요할 경우 웹훅 id로 PUT 요청을 보내 CRC를 수동으로 트리거할 수도 있습니다. 이는 웹훅 애플리케이션을 개발하거나 새 코드를 배포하고 서비스를 재시작한 뒤에 유용합니다. _crc_token_은 들어오는 각 CRC 요청마다 변경되며, 계산 시 메시지로 사용하고 Consumer Secret을 키로 사용해야 합니다. 응답이 3초 이내에 반환되지 않거나 응답이 유효하지 않은 경우, 등록된 웹훅으로 이벤트 전송이 중지됩니다.

CRC 요청은 다음과 같은 경우에 발생합니다:

웹훅 URL을 등록할 때
웹훅 URL을 검증하기 위해 대략 매시간
PUT 요청으로 CRC를 수동으로 트리거할 수 있습니다. 웹훅 클라이언트를 개발할 때 CRC 응답을 구현하는 과정에서 CRC를 수동으로 트리거하는 절차도 함께 계획하세요.

응답 요구 사항:

crc_token과 앱 Consumer Secret을 사용해 생성한 base64 인코딩 HMAC SHA-256 해시
유효한 response_token 및 JSON 형식
3초 미만의 지연 시간
200 HTTP 응답 코드

언어별 HMAC 라이브러리

Python에서의 응답 토큰 생성 예시:

다음은 Python 2.7 Flask 웹앱에서 챌린지 응답 검사에 올바르게 응답하는 라우트를 정의한 예시입니다.

import base64
import hashlib
import hmac
import json


\# GET 요청 라우트를 정의합니다
@app.route('/webhooks/twitter', methods=\['GET'\])
def webhook_challenge():

  # 수신된 토큰과 소비자 비밀키로 HMAC SHA-256 해시를 생성합니다
  sha256\_hash\_digest = hmac.new(TWITTER\_CONSUMER\_SECRET, msg=request.args.get('crc_token'), digestmod=hashlib.sha256).digest()

  # base64로 인코딩한 해시로 응답 데이터를 구성합니다
  response = {
    'response\_token': 'sha256=' + base64.b64encode(sha256\_hash_digest)
  }

  # 올바른 형식의 JSON 응답을 반환합니다
  return json.dumps(response)

예시 JSON 응답:

위와 같이 라우트를 정의했다면 웹 브라우저에서 https://your-app-domain/webhooks/twitter?crc_token=foo 로 이동할 때 아래와 유사한 응답을 웹앱이 반환해야 합니다.

{
  "response_token": "sha256=x0mYd8hz2goCTfcNAaMqENy2BFgJJfJOb4PdvTffpwg="
}

기타 예시:

여기는 Node/JS로 작성된 CRC 응답 메서드 예시입니다.
여기는 Ruby로 작성된 CRC 응답 메서드 예시입니다(generate_crc_response 및 CRC 이벤트를 수신하는 /GET 경로를 참고하세요).

선택적 시그니처 헤더 검증

X로부터 POST 요청을 받거나 웹훅을 생성하기 위해 GET 요청을 보내거나 수동 CRC를 수행하기 위해 GET 요청을 보낼 때, 해시 시그니처가 헤더의 x-twitter-webhooks-signature로 전달됩니다. 이 시그니처는 데이터의 출처가 X인지 확인하는 데 사용할 수 있습니다. POST 해시 시그니처는 sha256=으로 시작하며, 이는 HMAC SHA-256을 사용해 X 앱 Consumer Secret과 페이로드를 서명했음을 나타냅니다. GET 해시는 쿼리 매개변수 문자열 crc_token=

token&amp;nonce=

nonce 에서 계산됩니다. 요청 검증 단계

Consumer secret과 수신된 페이로드 본문으로 해시를 생성합니다.
생성한 해시를 base64로 인코딩된 x-twitter-webhooks-signature 값과 비교합니다. 타이밍 공격에 대한 취약성을 줄이기 위해 compare_digest와 같은 메서드를 사용하세요.

추가 보안 지침

다음은 웹 애플리케이션에서 고려해야 할 추가 보안 지침입니다. 이를 구현하지 않아도 웹훅은 정상적으로 동작하지만, X 정보보안팀에서 강력히 권장합니다. 아래 권장 사항이 생소하다면 서버 관리자와 상의하세요.

X 집계 네트워크 블록

보안을 강화하려면 다음 집계 네트워크 블록을 허용 목록(allowlist)에 추가하는 것이 좋습니다:

199.59.148.0/22
199.16.156.0/22
192.133.77.0/26
64.63.15.0/24
64.63.31.0/24
64.63.47.0/24
202.160.128.0/24
202.160.129.0/24
202.160.130.0/24

권장 서버 구성

ssllabs.com 테스트에서 “A” 등급 받기
TLS 1.2 활성화
Forward Secrecy 활성화
SSLv2 비활성화
SSLv3 비활성화(POODLE 취약점 대비)
TLS 1.0 비활성화
TLS 1.1 비활성화
TLS 압축 비활성화
세션 티켓 키를 주기적으로 교체하지 않는 경우 세션 티켓 비활성화
SSL 구성에서 “ssl_prefer_server_ciphers” 또는 “SSLHonorCipherOrder” 옵션을 “on”으로 설정
암호 제품군 목록이 다음과 같은 최신 목록인지 확인: ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES128-SHA256:AES128-SHA:AES256-GCM-SHA384:AES256-SHA256:AES256-SHA:ECDHE-RSA-DES-CBC3-SHA:DES-CBC3-SHA

웹훅과 구독 관리

웹후크 생성 및 변경

웹후크 URL을 변경하려면 기존 웹후크를 삭제한 뒤 새 웹후크를 생성해야 합니다. 이때 새 웹후크에 사용자 구독을 다시 추가해야 합니다.

Webhook 구성 관리 엔드포인트:


Method	Enterprise
Webhook URL 등록 / webhook_id 생성	POST webhooks
모든 Webhook URL과 해당 상태 반환	GET webhooks
앱의 현재 Webhook 구성 삭제	DELETE webhooks/:webhook_id
CRC 요청 수동 트리거	PUT webhooks/:webhook_id

왜 웹훅 URL만 업데이트할 수 없나요?

웹훅 구성은 왜 변경할 수 없나요? X는 보안을 매우 중요하게 여깁니다. 웹훅 URL이 변경되었다면 애플리케이션의 consumer key와 consumer secret이 노출되었을 가능성이 있습니다. 새 웹훅 구성을 생성하도록 요구하면 사용자 이벤트에 다시 구독해야 하며, 이 과정에는 악의적인 주체가 보유하고 있을 가능성이 낮은 액세스 토큰이 필요합니다. 결과적으로 다른 사람이 사용자의 비공개 정보를 수신할 가능성이 줄어듭니다.

사용자 구독 추가 및 제거

엔터프라이즈 티어에서는 수천 개의 구독을 지원합니다. 이미 계정 담당자가 있는 경우 문의 사항을 해당 담당자에게 직접 문의하세요. 엔터프라이즈 API 액세스를 신청하려면 여기를 클릭하세요.

구독 관리 엔드포인트


Method	Enterprise
새 사용자 구독 추가	POST webhooks/:webhook_id/subscriptions/all
사용자 구독 조회	GET webhooks/:webhook_id/subscriptions/all
활성 구독 전체 목록 반환	GET webhooks/:webhook_id/subscriptions/all/list
애플리케이션 전용 OAuth를 사용하여 사용자 구독 비활성화	DELETE webhooks/:webhook_id/subscriptions/:user_id/all.json

Account Activity API: Enterprise

참고: API를 사용하기 전에 X가 귀하의 Developer 앱에 대해 Account Activity API 접근 권한을 활성화해야 합니다. 이를 위해 인증에 사용할 App ID를 계정 매니저 또는 기술 지원 팀과 공유하세요.

Account Activity API는 단일 연결을 통해 구독된 모든 계정의 실시간 활동을 수신할 수 있도록, 사용자 구독을 생성하고 관리할 수 있게 해 주는 엔드포인트 컬렉션으로 구성됩니다. Account Activity API에는 두 가지 인증 방법이 제공됩니다(OAuth 1.0a 및 OAuth 2.0 Bearer Token). 어떤 인증 방법을 사용할지는 호출하는 엔드포인트에 따라 달라집니다.


설명	엔드포인트	OAuth 1.0a (사용자 컨텍스트)	OAuth 2.0 베어러 토큰(애플리케이션 전용)
지정된 애플리케이션 컨텍스트에 새 webhook URL 등록	POST account_activity/webhooks	✓
지정된 애플리케이션의 모든 URL과 해당 상태 반환	GET account_activity/webhooks		✓
특정 webhook의 URL에 대해 CRC(Challenge Response Check) 트리거	PUT account_activity/webhooks/:webhook_id	✓
애플리케이션을 사용자의 계정 이벤트에 구독	POST account_activity/webhooks/:webhook_id/subscriptions/all	✓ *
현재 활성 구독 수 반환	GET account_activity/subscriptions/count		✓
webhook 구성이 사용자의 이벤트에 구독되어 있는지 확인	GET account_activity/webhooks/:webhook_id/subscriptions/all	✓ *
현재 활성 구독 목록 반환	GET account_activity/webhooks/:webhook_id/subscriptions/all/list		✓
webhook 삭제	DELETE account_activity/webhooks/:webhook_id	✓
[사용 중단됨] 제공된 사용자 컨텍스트 및 애플리케이션에 대한 구독 비활성화	DELETE account_activity/webhooks/:webhook_id/subscriptions/all	✓ *
애플리케이션 전용 OAuth를 사용하여 구독 비활성화	DELETE /account_activity/webhooks/:webhook_id/subscriptions/:user_id/all.json		✓
활동을 webhook으로 재전달	POST /1.1/account_activity/replay/webhooks/:webhook_id/subscriptions/all.json		✓

*_ 인증에는 구독 사용자의 액세스 토큰이 필요합니다. _ OAuth 1.0a 사용자 컨텍스트 인증이 필요한 엔드포인트의 경우 요청을 인증하려면 다음 자격 증명이 필요합니다:

Consumer Keys(API Key 및 Secret)
Access Tokens(Access Token 및 Secret)

다음 세 엔드포인트의 경우 애플리케이션 컨텍스트에서 쓰기 작업을 수행합니다(X 사용자는 관여하지 않음). 따라서 제공해야 하는 액세스 토큰은 사용 중인 Developer 앱에 속한 것입니다. 이는 개발자 포털에서 해당 앱의 “Keys and tokens” 탭에서 직접 생성할 수 있습니다.

POST account_activity/webhooks: 지정된 애플리케이션 컨텍스트에 대해 새 webhook URL을 등록합니다
PUT account_activity/webhooks/:webhook_id: 특정 webhook의 URL에 대해 CRC(Challenge Response Check)를 수행합니다
DELETE account_activity/webhooks/:webhook_id: webhook을 삭제합니다

반면 다음 세 가지 엔드포인트는 애플리케이션이 X 사용자를 대신해 보호된 데이터(예: 다이렉트 메시지)에 접근할 수 있도록 요청합니다. 따라서 해당 구독 사용자에게 속한 액세스 토큰을 제공해야 합니다. 필요한 액세스 토큰은 3-legged OAuth 플로우를 통해 발급받을 수 있습니다(참고: OAuth 1.0a: 사용자의 액세스 토큰을 얻는 방법). 이 엔드포인트들은 위 표에서 별표(*)로 표시되어 있습니다.

POST account_activity/webhooks/:webhook_id/subscriptions/all: 애플리케이션을 사용자의 계정 이벤트에 구독시킵니다
GET account_activity/webhooks/:webhook_id/subscriptions/all: webhook 구성이 사용자 이벤트에 구독되어 있는지 확인합니다
DELETE account_activity/webhooks/:webhook_id/subscriptions/all: 제공된 사용자 컨텍스트와 애플리케이션에 대한 구독을 비활성화합니다 [사용 중단]

유의하세요: Developer 앱이 “Read, Write, and Direct Messages”로 활성화되어 있는지 확인하세요. 이 설정은 개발자 계정의 Projects & Apps 섹션에서 선택한 Developer 앱의 “App permissions”에서 변경할 수 있습니다. 권한 설정을 변경한 후에는 앱 자격 증명을 다시 생성해야 합니다.

Account Activity API로 제공되는 모든 엔드포인트 목록과 관련 설명, 인증 구현 예제를 포함한 예시 cURL 요청은 API 참조 문서에서 확인할 수 있습니다. 추가 정보는 Enterprise Account Activity API를 시작하는 데 도움이 되는 XDev의 샘플 웹 앱 및 보조 스크립트를 확인하세요.

유의하세요: API를 사용하기 전에 X가 귀하의 Developer 앱에 대해 Account Activity API 액세스를 활성화해야 합니다. 이를 위해 인증에 사용할 App ID를 계정 관리자 또는 기술 지원팀과 공유하세요.

Account Activity API는 단일 연결을 통해 구독 중인 모든 계정의 실시간 계정 활동을 수신할 수 있도록 사용자 구독을 생성하고 관리하는 일련의 엔드포인트로 구성됩니다. Account Activity API에는 두 가지 인증 방법이 제공됩니다(OAuth 1.0a 및 OAuth 2.0 Bearer Token). 사용할 인증 방법은 사용하는 엔드포인트에 따라 달라집니다.


설명	엔드포인트	OAuth 1.0a (사용자 컨텍스트)	OAuth 2.0 베어러 토큰(애플리케이션 전용)
지정된 애플리케이션 컨텍스트에 대해 새 webhook URL 등록	POST account_activity/webhooks	✓
지정된 애플리케이션의 모든 URL과 해당 상태 반환	GET account_activity/webhooks		✓
특정 webhook의 URL에 대해 CRC(Challenge Response Check) 트리거	PUT account_activity/webhooks/:webhook_id	✓
애플리케이션을 사용자의 계정 이벤트에 구독	POST account_activity/webhooks/:webhook_id/subscriptions/all	✓ *
현재 활성 구독 수 반환	GET account_activity/subscriptions/count		✓
webhook 구성이 사용자의 이벤트에 구독되어 있는지 확인	GET account_activity/webhooks/:webhook_id/subscriptions/all	✓ *
현재 활성 구독 목록 반환	GET account_activity/webhooks/:webhook_id/subscriptions/all/list		✓
webhook 삭제	DELETE account_activity/webhooks/:webhook_id	✓
[사용 중단됨] 제공된 사용자 컨텍스트와 애플리케이션에 대한 구독 비활성화	DELETE account_activity/webhooks/:webhook_id/subscriptions/all	✓ *
애플리케이션 전용 OAuth를 사용하여 구독 비활성화	DELETE /account_activity/webhooks/:webhook_id/subscriptions/:user_id/all.json		✓
활동을 webhook으로 재전달	POST /1.1/account_activity/replay/webhooks/:webhook_id/subscriptions/all.json		✓

*_ 인증에는 구독 사용자의 액세스 토큰이 필요합니다. _ OAuth 1.0a 사용자 컨텍스트 인증이 필요한 엔드포인트의 경우, 요청을 인증하려면 다음 자격 증명을 제공해야 합니다:

Consumer Keys (API Key 및 Secret)
Access Tokens (Access Token 및 Secret)

다음 세 엔드포인트의 경우 애플리케이션 컨텍스트에서 쓰기 작업을 수행합니다(X 사용자는 관여하지 않음). 따라서 제공해야 하는 액세스 토큰은 귀하의 Developer 앱에 속한 것입니다. 이는 개발자 포털에서 앱의 “Keys and tokens” 탭에서 직접 생성할 수 있습니다.

POST account_activity/webhooks: 지정된 애플리케이션 컨텍스트에 대해 새 webhook URL을 등록합니다
PUT account_activity/webhooks/:webhook_id: 특정 webhook의 URL에 대해 CRC(Challenge Response Check)를 실행합니다
DELETE account_activity/webhooks/:webhook_id: webhook을 삭제합니다

반면, 다음 세 개 엔드포인트는 애플리케이션이 X 사용자를 대신해 보호된 데이터(예: 다이렉트 메시지)에 접근하도록 요청하는 경우입니다. 따라서 해당 구독 사용자에 속한 액세스 토큰을 제공해야 합니다. 필요한 액세스 토큰은 3-legged OAuth 플로우를 통해 얻을 수 있습니다(OAuth 1.0a: 사용자의 액세스 토큰을 얻는 방법 참조). 이러한 엔드포인트는 위 표에서 별표(*)로 표시되어 있습니다.

POST account_activity/webhooks/:webhook_id/subscriptions/all: 애플리케이션을 사용자의 계정 이벤트에 구독합니다
GET account_activity/webhooks/:webhook_id/subscriptions/all: webhook 구성이 사용자의 이벤트에 구독되어 있는지 확인합니다
DELETE account_activity/webhooks/:webhook_id/subscriptions/all: 제공된 사용자 컨텍스트와 애플리케이션에 대한 구독을 비활성화합니다 [사용 중단됨]

유의하세요: Developer 앱이 “Read, Write, and Direct Messages” 권한으로 활성화되어 있는지 확인하세요. 개발자 계정의 Projects & Apps 섹션에서 선택한 Developer 앱의 “App permissions”에서 이 설정을 변경할 수 있습니다. 권한을 변경한 후에는 앱 자격 증명을 다시 생성해야 합니다.

Account Activity API에서 사용할 수 있는 모든 엔드포인트 목록(설명과 인증 구현 예가 포함된 cURL 예제 포함)은 API 참조 문서에서 확인할 수 있습니다. 추가 정보는 Enterprise Account Activity API를 시작하는 데 도움이 되는 XDev의 샘플 웹 앱 및 도우미 스크립트를 참고하세요.

재시도

Enterprise Account Activity API의 Enterprise 등급에는 웹훅 이벤트에 대한 재시도 메커니즘이 포함되어 있습니다. ‘성공’ 200 HTTP 응답 코드를 받지 못하면 X 서버가 재시도 메커니즘을 작동해 5분 동안 최대 세 번 웹훅 이벤트를 다시 전송합니다. 이 웹훅 이벤트 재시도 서비스는 네트워크 문제 발생 시는 물론, 클라이언트측 서비스 중단이나 배포 중에도 신뢰성을 높이고 이벤트 복구에 기여합니다.

재시도란 무엇인가요?

Account Activity API는 클라이언트의 웹 앱이 계정 활동 웹훅 이벤트에 대해 ‘성공’ 200 응답을 반환하지 않을 때 재시도 기능을 제공합니다. 클라이언트 측에서 이벤트를 성공적으로 수신했음을 확인하지 않으면 X는 해당 이벤트가 수신되지 않은 것으로 간주합니다. 200이 아닌 응답을 받았거나, 3초 내에 응답이 없거나, 아예 응답이 수신되지 않으면 요청을 다시 시도하고 그 요청을 3초간 열어 둡니다. 즉, 두 번의 시도 동안 총 대략 5초 내에 응답해야 하며, 그래야 우리가 귀하의 웹훅 URL로 전송하려는 활동을 수신할 수 있습니다. 서버가 응답하지 않거나 일시적인 오류를 반환하는 경우에는 5분 동안 재시도를 계속합니다. 검증을 확인하기 위해 총 세 번의 재시도가 수행됩니다. 이는 중복성과 안전망을 제공하여 모든 웹훅 이벤트를 수신할 수 있도록 합니다. 재시도가 설정된 구독은 해당 웹훅에 구독된 모든 사용자에 대해 발생하는 모든 활동에 대해 재시도된 이벤트를 받게 됩니다. 이 여덟 번의 시도 내에 검증을 완료하지 못하면 해당 활동은 더 이상 Account Activity API를 통해 제공되지 않습니다.

재시도 타임라인

Account Activity API는 200 응답을 받을 때까지 약 5분 동안 최대 세 차례 재시도합니다. 자세한 내용은 아래 표를 참고하세요. 약 5분이 지나면 해당 활동은 Account Activity API로 다시 전송할 수 없습니다. 누락된 데이터를 수집하려면 다른 X 엔드포인트를 사용해야 합니다. 예를 들어, search APIs를 사용해 관련 게시물, 리트윗, 인용 트윗, 멘션 및 답글을 조회할 수 있습니다. 누락된 다이렉트 메시지는 이 엔드포인트로 조회할 수 있습니다.

재시도 타임라인


활동이 생성되고 Account Activity API가 webhook URL로 POST를 시도하나 3초 내에 타임아웃됩니다.
직전 타임아웃이 끝난 뒤 3초를 기다린 다음, Account Activity API가 webhook URL로 POST를 시도하나 3초 내에 타임아웃됩니다.
직전 타임아웃이 끝난 뒤 27초를 기다린 다음, Account Activity API가 webhook URL로 POST를 시도하나 3초 내에 타임아웃됩니다.
직전 타임아웃이 끝난 뒤 242초를 기다린 다음, Account Activity API가 webhook URL로 POST를 시도하나 3초 내에 타임아웃됩니다.
이후에는 Account Activity API가 더 이상 POST를 시도하지 않습니다. 클라이언트는 데이터를 복구하려면 다른 X 엔드포인트를 사용해야 합니다.

Account Activity 데이터 객체 구조

Object	Details
for_user_id	이벤트와 관련된 구독 사용자(구독 항목)를 식별합니다.
is_blocked_by	(조건부) 다른 사용자가 구독된 사용자를 언급할 때만 표시됩니다. 게시물 언급 이벤트에서만 true인 경우 포함됩니다.
source	활동을 수행하는 사용자입니다. 예: 팔로우, 차단, 음소거를 수행하는 사용자가 source 사용자입니다.
target	활동의 대상 사용자입니다. 예: 팔로우되거나 차단되거나 음소거되는 사용자가 target 사용자입니다.

사용 가능한 활동

Message Type	Details
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	컴플라이언스 유지를 용이하게 하기 위한 삭제된 게시물 알림.

페이로드 예시 위 표에 설명된 각 Account Activity 이벤트의 페이로드 예시는 아래를 참고하세요.

tweet_create_events (게시물, 리포스트, 답글, 인용 게시물)

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

tweet_create_events (@맨션)

{
	"for_user_id": "2244994945",
	"user_has_blocked": "false",
	"tweet_create_events": [
	  {
		<트윗 객체>
	  }
	]
}

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": {
			<트윗 객체>
		},
		"user": {
			<사용자 객체>
		}
	}]
}

follow_events

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

언팔로우_이벤트

{
	"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": "null",
			"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,
			"profile_image_url": "null",
			"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 의견은 본인 의견임",
			"url": "https://t.co/SnxaA15ZuY",
			"protected": false,
			"verified": false,
			"followers_count": 23,
			"friends_count": 47,
			"statuses_count": 509,
			"profile_image_url": "null",
			"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": "null",
			"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": "낮에는 @X에서 데이터, 저녁에는 디자인",
			"protected": false,
			"verified": false,
			"followers_count": 299,
			"friends_count": 336,
			"statuses_count": 752,
			"profile_image_url": "null",
			"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 의견은 제 개인 의견입니다",
			"url": "https://t.co/SnxaA15ZuY",
			"protected": false,
			"verified": false,
			"followers_count": 23,
			"friends_count": 48,
			"statuses_count": 510,
			"profile_image_url": "null",
			"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"
    }
   ]
}

Account Activity Replay API

Enterprise Account Activity Replay API는 최대 5일 전까지의 이벤트를 복구할 수 있는 데이터 복구 도구입니다. 이는 retry window보다 긴 연결 해제나, 시스템을 정상 상태로 복원하는 데 며칠이 필요한 재해 복구 시나리오 등으로 인해 webhook 서버가 이벤트를 놓친 경우 데이터 복구에 사용해야 합니다. Account Activity Replay API는 일정 기간 동안 activities 수집에 실패한 모든 상황을 위해 개발되었습니다. 원래 실시간으로 activities를 전달하던 것과 동일한 webhook으로 activities를 전달합니다. 이 제품은 복구 도구이며 백필 도구가 아니므로, 과거에 해당 이벤트의 전달을 시도한 적이 있는 경우에만 이벤트가 재생됩니다. Account Activity Replay API는 구독이 생성되기 이전 기간의 이벤트는 전달할 수 없습니다.

Account Activity Replay API 사용

계정에 Replay 기능이 설정되어 있다면 Account Activity API에 요청하는 방식과 유사하게 요청할 수 있습니다. 요청에는 어떤 webhook의 활동을 재생할지 지정하기 위해 반드시 webhook id 매개변수를 포함해야 합니다. 다시 말해 Replay 요청은 webhook id와 application id를 기준으로 시작 날짜/시간부터 종료 날짜/시간까지의 이벤트를 Account Activity Replay API가 조회하도록 지시합니다. UTC 시간 기준이어야 합니다. 이러한 활동은 해당 id와 연결된 등록된 webhook을 통해 초당 최대 2,500건의 이벤트 속도로 전달됩니다. 또한 하나의 webhook당 동시에 실행할 수 있는 Replay 작업은 하나뿐이며, 해당 webhook에 지정한 날짜/시간 동안 활성 상태였던 모든 구독은 재생된다는 점에 유의하세요. 이벤트는 지정한 기간의 첫 번째(가장 오래된) 1분부터 시작해 가능한 한 시간 순서대로 마지막 1분이 전달될 때까지 제공됩니다. 그 시점에 Replay는 해당 webhook으로 작업 완료 이벤트를 전송합니다. 활동을 시간 순서대로 전달하기 때문에 시작 시간 부근에 일치하는 결과가 거의 없거나 전혀 없는 경우, 첫 결과가 전달되기까지 시간이 걸릴 수 있습니다.

제한 사항

Replay는 최대 5일 전까지의 활동을 손쉽게 복구하기 위한 도구이지만, 구독이 생성된 시점 이전의 이벤트는 제공하지 않습니다. 예를 들어 3일 전에 새 구독을 추가하고, 오늘을 기준으로 지난 5일을 대상으로 Replay 작업을 실행했다면, 해당 새 구독이 활성화되어 있던 3일치 데이터만 받게 됩니다.

데이터 가용성 및 유형

Account Activity Replay API의 활동 데이터는 요청을 시작한 시점부터 5일 동안 제공되며, 특정 활동이 생성된 후 약 10분 뒤에 새 데이터가 이용 가능해집니다. 요청에서 from_date 및 to_date 매개변수를 사용해 이 5일 범위 내의 시간 구간을 지정할 수 있습니다. Replay에 대한 액세스 권한을 받기 전에 원래 전달된 이벤트는 재생할 수 없습니다. 예를 들어, 2019년 6월 1일 UTC 오후 3시 30분에 계정에 Account Activity Replay API 액세스 권한이 부여되었다면, 그 날짜와 시간 이전의 이벤트는 Replay로 가져올 수 없습니다. Account Activity Replay API reference로 계속

마이그레이션 소개

저희는 2018년에 Site Streams, User Streams, 그리고 Account Activity API - DM Only 제품의 표준 베타 버전을 사용 중단했습니다. 해당 제품을 사용하셨다면 Account Activity API의 프리미엄 또는 엔터프라이즈 버전으로 마이그레이션해 주시기 바랍니다. 레거시 Direct Message 엔드포인트도 사용 중단했습니다. 해당 엔드포인트를 사용하셨다면 새로운 DM 엔드포인트 또는 Account Activity API의 프리미엄/엔터프라이즈 버전으로 마이그레이션해 주시기 바랍니다. 자세한 내용은 이 공지를 확인하세요. 다음 엔드포인트가 이번 변경의 영향을 받습니다:

User Streams
Site Streams
GET direct_messages
GET direct_messages/sent
GET direct_messages/show
POST direct_messages/new
POST direct_messages/destroy

Direct Message의 경우 추가 기능을 포함해 유사한 접근을 제공하는 새로운 엔드포인트와 서비스가 마련되어 있습니다:

Account Activity API enterprise 및 premium
GET direct_messages/events/list
GET direct_messages/events/show
POST direct_messages/events/new
POST direct_messages/events/destroy

이 새로운 엔드포인트와 서비스로 원활히 전환하실 수 있도록 두 가지 마이그레이션 가이드를 제공합니다:

User Streams 및 Site Streams에서 새로운 웹훅 기반 서비스로 이동하시는 분들을 위한 Account Activity API 마이그레이션 가이드
Direct Message REST 엔드포인트 간 전환을 위한 Direct Message 마이그레이션 가이드

또한 Account Activity API와 시작 방법을 다루는 영상 시리즈도 제공합니다. 마지막으로, 이해를 돕고 빠르게 시작하실 수 있도록 코드 샘플도 제공합니다:

Account Activity Dashboard는 Account Activity API를 시작하는 데 도움이 되는 보조 스크립트를 포함한 샘플 Node.js 웹 앱입니다.
SnowBot은 Account Activity API와 REST Direct Message 엔드포인트를 사용하는 샘플 챗봇입니다. Ruby로 작성되었고 Sinatra 웹 앱 프레임워크를 사용하며 Heroku에 배포되어 있습니다.

마이그레이션 가이드: User Streams/Site Streams에서 Account Activity API로 전환

2018년 8월 23일부로 Site Streams와 User Streams가 폐기되었습니다. 반드시 Account Activity API로 전환해 주세요. 자세한 내용은 이 공지를 확인하세요. 이 가이드는 레거시 User Streams 및 Site Streams API에서 대체 서비스인 Account Activity API로 전환하는 데 도움이 되도록 작성되었습니다. 아래에서 변경 사항 요약, 신규 기능 목록, 전환 시 유의해야 할 주요 차이점과 고려 사항을 확인할 수 있습니다. 기본 DM 엔드포인트에서 전환하는 방법은 Direct Message 마이그레이션 가이드를 참고하세요.

변경 사항 요약

Account Activity API는 User Streams 및 Site Streams와 같은 스트리밍 연결 대신 웹훅을 통해 인증되고 구독된 계정의 이벤트를 전달합니다.

사용 중단된 API

GET user GET site (컨트롤 스트림 포함: GET site/c/:stream_id, GET site/c/:stream_id/info.json, GET site/c/:stream_id/friends/ids.json, POST site/c/:stream_id/add_user.json, POST /site/c/:stream_id/remove_user.json)

대체용 API

Enterprise Account Activity API - 모든 활동

차이점 및 마이그레이션 고려사항

API 형식: 새로운 Account Activity API는 User Streams 및 Site Streams와는 다르게 작동합니다. 웹후크로 데이터를 수신하도록 웹 앱을 수정해야 합니다. 웹후크에 대한 자세한 내용은 여기에서 확인하세요. 사용 가능한 데이터: 또 다른 핵심 차이점은 전달되는 데이터입니다. X는 더 이상 사용자가 X에서 팔로우하는 사람들(즉, 홈 타임라인)로부터 발생하는 이벤트를 보내지 않습니다. 이는 의도적인 변경이며, 앞으로도 바꿀 계획이 없습니다. 신뢰성: 스트리밍과 달리 웹후크는 전달 확인을 제공하고, 웹후크 URL에 도달하지 못한 POST된 활동을 재시도할 수 있는 옵션을 제공합니다. 이를 통해 짧은 연결 끊김이나 다운타임이 있어도 앱이 모든 관련 활동을 수신하고 있다는 신뢰도를 높일 수 있습니다.

새로운 기능

Account Activity API는 많은 새로운 기능을 제공합니다. 가장 눈에 띄는 변화는 데이터가 스트리밍 방식이 아닌 웹훅으로 전달된다는 점입니다. 웹훅은 스트리밍에 비해 여러 이점이 있으며, 가장 두드러진 것은 속도와 신뢰성입니다. API는 데이터가 생성되는 즉시 JSON 이벤트 형태로 전달하므로 더 이상 활성 연결을 유지하거나 엔드포인트를 폴링할 필요가 없습니다. 이는 중복 구성의 필요성을 줄이고 전반적인 효율성을 높입니다. 웹훅에 대한 자세한 내용은 기술 문서에서 확인할 수 있습니다.

사용자 구독 관리

Account Activity API는 하나의 등록된 웹훅에 대해 여러 구독을 허용합니다. 이를 통해 Site Streams 아키텍처처럼 웹훅을 사용해 여러 사용자 구독 활동을 동일한 엔드포인트로 전달할 수 있습니다. 즉, 구독 한도와 관련된 구독 관리를 웹훅 연결과는 별도로 추적할 수 있습니다. 또한 단일 웹훅에 대해 소수의 구독부터 수천 개의 구독까지 확장할 수 있습니다.

마이그레이션 방법

Site Streams API에서 Account Activity API로 쉽게 마이그레이션하려면 아래 단계를 따르세요

1단계: 패키지 결정 현재 User Streams 또는 Site Streams를 어떻게 운영 중인지에 따라 Account Activity API의 enterprise 또는 premium 버전으로 전환하는 것을 고려하세요. 현재 지원하는 애플리케이션 수와 승인된 사용자 수를 검토하고, 필요한 처리량과 신뢰성에 맞게 규모를 조정하십시오. 가장 적합한 패키지를 결정할 때 고려할 사항은 다음과 같습니다:

필요한 웹훅 수
애플리케이션에서 관리 중이거나 예정된 구독/승인된 사용자 수
현재 X 클라이언트 애플리케이션 수
X에서 선호하는 지원 수준(포럼 지원 또는 관리형 엔터프라이즈 1:1 지원)
각 패키지의 가격

2단계: 개발자 포털에서 X 앱 설정 확인 User Streams 또는 Site Streams에 현재 사용 중인 X 앱은 개발자 포털에서 소유 사용자에게 표시됩니다. 이 X 앱은 해당 애플리케이션의 승인된 사용자를 유지하기 위해 Account Activity API에도 사용할 수 있습니다. 새 앱을 생성하고, 필요 시 사용자를 이 새 앱에 다시 승인받을 수도 있습니다. 비즈니스를 대신해 새 앱을 만드는 경우, 기업용 X @handle 계정으로 앱을 생성하는 것을 권장합니다.

X 앱 페이지의 permissions 탭에서 “Read, Write and Access direct messages”를 활성화하세요. *이 설정 변경은 소급 적용되지 않으며, 이미 승인된 사용자는 승인 당시의 설정을 유지합니다. 사용자가 아직 읽기, 쓰기 및 다이렉트 메시지 접근을 허용하지 않았다면, 해당 사용자가 애플리케이션을 다시 승인해야 합니다.
X Sign-in 및 X API에서 사용자 컨텍스트가 작동하는 방식에 익숙하지 않다면 Obtaining Access Tokens를 확인하세요.
“Keys and Tokens” 탭 하단에서 X 앱 소유자용 액세스 토큰을 생성하세요. 같은 탭에서 Consumer Key, Consumer Secret, Access Token, Access Token Secret을 기록해 두세요. API 사용 시 필요합니다.
application-only API 메서드용으로 Consumer Key와 Consumer Secret을 사용해 베어러 토큰을 생성하세요.

3단계: 웹훅 설정 및 구성

이벤트를 수신할 웹훅으로 사용할 엔드포인트가 포함된 웹 앱을 생성하세요(예: https://your_domain.com/webhook/twitter 또는 https://webhooks.your_domain.com).
웹훅을 생성할 때 Consumer Key, Consumer Secret, Access Token, Access Token Secret을 사용하세요. 엔드포인트는 crc_token과 앱 Consumer Secret으로부터 생성된 base64 인코딩 HMAC SHA-256 해시인 response_token을 포함하는 JSON 응답을 반환해야 합니다.
Challenge Response Check(CRC) 요구 사항에 특히 유의하여 Securing Webhooks 문서를 검토하세요.
웹훅이 들어오는 이벤트에 대한 POST 요청과 CRC에 대한 GET 요청을 지원하는지 확인하세요.
웹훅이 낮은 지연 시간으로 동작하는지 확인하세요(POST 요청에 대한 응답이 3초 미만).

4단계: 웹훅 설정 검증

Webhook API는 다음 두 가지 방식으로 웹훅을 보호합니다:

- 웹훅 소유자가 웹 앱 소유자인지 검증하기 위한 챌린지 응답 검사 요구 - 소스 검증을 위해 각 POST 요청에 포함되는 서명 헤더

웹 앱과 웹훅 URL의 소유자가 모두 본인임을 확인하기 위해 X는 CRC(Challenge Response Check)를 수행합니다. 이는 순환 중복 검사(cyclic redundancy check)와 혼동하지 마세요.
crc_token이라는 매개변수를 포함한 GET 요청이 웹훅 URL로 전송됩니다. 엔드포인트는 crc_token과 앱 Consumer Secret으로부터 생성된 base64 인코딩 HMAC SHA-256 해시인 response_token을 포함하는 JSON 응답을 반환해야 합니다.
crc_token은 수신되는 각 CRC 요청마다 변경됩니다. 계산 시 crc_token을 메시지로 사용하고, Consumer Secret을 키로 사용해야 합니다.
응답이 유효하지 않으면 등록된 웹훅으로의 이벤트 전송이 중단됩니다.

5단계: 각 User Stream 또는 Site Streams 승인 사용자에 대한 구독 생성 User Streams에서 Account Activity API로 전환:

User Streams에서 현재 사용자 구독 목록을 생성합니다
다음 요청으로 새로운 Account Activity API 구독을 설정합니다: POST account_activity/all/:env_name/subscriptions
다음 요청으로 Account Activity API 구독을 확인합니다: _GET account_activity/all/:env_name/subscriptions/list _

Site Streams에서 Account Activity API로 전환하기: (컨트롤 스트림 사용)

다음 요청으로 Site Streams의 현재 구독 목록을 생성합니다: GET /1.1/site/c/:stream_id/info.json
다음 요청으로 새로운 Account Activity API 구독을 설정합니다: POST account_activity/all/:env_name/subscriptions
다음 요청으로 Account Activity API 구독을 확인합니다: _GET account_activity/all/:env_name/subscriptions/list _

Webhook 등록 및 구독 생성(Site Streams 또는 User Streams에서 마이그레이션하지 않는 경우)

POST webhooks를 사용해 앱에 webhook URL을 등록하고 webhook_id를 받습니다.
반환된 webhook_id로 POST webhooks/:webhook_id/subscriptions/all을 호출해 사용자 구독을 추가합니다.

Account Activity 대시보드(샘플 Account Activity API 애플리케이션)

Account Activity API를 더 빠르게 테스트할 수 있도록 샘플 앱을 준비했습니다:

Account Activity 대시보드 샘플 애플리케이션을 여기에서 다운로드하세요(Node.js 사용)
README의 안내에 따라 앱을 설치하고 실행하세요
애플리케이션을 실행한 후 UI에서 웹훅을 손쉽게 설정하고 새 구독을 생성할 수 있습니다

사용 가능한 활동

메시지 유형	세부 정보
tweet_create_events	구독 사용자에 의해 또는 구독 사용자 대상으로 다음 작업이 발생할 때 게시물 상태 페이로드를 전송: 게시물, 리트윗, 답글, @멘션, 인용 게시물
favorite_events	사용자와 대상이 포함된 즐겨찾기(좋아요) 이벤트 상태.
follow_events	사용자와 대상이 포함된 팔로우 이벤트.
block_events	사용자와 대상이 포함된 차단 이벤트.
mute_events	사용자와 대상이 포함된 음소거 이벤트.
direct_message_events	사용자와 대상이 포함된 다이렉트 메시지 이벤트 상태.
direct_message_indicate_typing_events	사용자와 대상이 포함된 다이렉트 메시지 입력 중 표시 이벤트.
direct_message_mark_read_events	사용자와 대상이 포함된 다이렉트 메시지 읽음 표시 이벤트.

사용 중단된 스트리밍 메시지 유형


빈 줄	빈 줄은 더 이상 Account Activity API에서 전달되지 않습니다. 과거에는 User Streams와 Site Streams에서 keep-alive 메시지로 사용되었습니다.
제한 알림	제한 알림은 더 이상 특정 웹훅으로 전송되지 않습니다. 대신 사용자는 API를 호출해 사용 가능한 핸들의 현재 사용량을 조회할 수 있습니다. 이는 향후 개발자 포털에 포함될 예정입니다.
연결 끊김 메시지	웹훅은 활성 연결에 의존하지 않으므로 연결 끊김 알림이 더 이상 필요하지 않습니다.
정체 경고	웹훅은 대량의 수신 메시지를 처리할 수 있는 활성 연결에 의존하지 않으므로 정체 경고가 더 이상 필요하지 않습니다.
친구 목록	친구 목록은 더 이상 사전 제공되지 않습니다. 이제 이 정보를 조회할 수 있는 REST 엔드포인트가 제공됩니다.

사용 중단된 이벤트 유형


설명	이벤트 이름	소스	대상	대상 객체
사용자가 게시물을 삭제함	delete	현재 사용자	현재 사용자	게시물
팔로우한 사용자가 게시물을 삭제함	delete	팔로우한 사용자	팔로우한 사용자	게시물
사용자가 게시물의 즐겨찾기를 해제함	unfavorite	현재 사용자	게시물 작성자	게시물
사용자의 게시물이 즐겨찾기 해제됨	unfavorite	즐겨찾기 해제한 사용자	현재 사용자	게시물
사용자가 누군가를 언팔로우함	unfollow	현재 사용자	팔로우한 사용자	Null
사용자가 목록을 생성함	list_created	현재 사용자	현재 사용자	목록
사용자가 목록을 삭제함	list_destroyed	현재 사용자	현재 사용자	목록
사용자가 목록을 수정함	list_updated	현재 사용자	현재 사용자	목록
사용자가 누군가를 목록에 추가함	list_member_added	현재 사용자	추가된 사용자	목록
사용자가 목록에 추가됨	list_member_added	추가한 사용자	현재 사용자	목록
사용자가 누군가를 목록에서 제거함	list_member_removed	현재 사용자	제거된 사용자	목록
사용자가 목록에서 제거됨	list_member_removed	제거한 사용자	현재 사용자	목록
사용자가 목록을 구독함	list_user_subscribed	현재 사용자	목록 소유자	목록
사용자의 목록이 구독됨	list_user_subscribed	구독한 사용자	현재 사용자	목록
사용자가 목록 구독을 취소함	list_user_unsubscribed	현재 사용자	목록 소유자	목록
사용자의 목록 구독이 취소됨	list_user_unsubscribed	구독 취소한 사용자	현재 사용자	목록
사용자가 프로필을 업데이트함	user_update	현재 사용자	현재 사용자	Null
사용자가 보호 상태를 업데이트함	user_update	현재 사용자	현재 사용자	Null

다이렉트 메시지 마이그레이션 가이드

2018년 9월 17일부로 기존 다이렉트 메시지 엔드포인트를 사용 중단했습니다. 해당 엔드포인트를 사용 중이셨다면 새로운 다이렉트 메시지 엔드포인트 또는 Account Activity API로 반드시 마이그레이션해 주세요. 자세한 내용은 이 공지를 확인하세요. 이 가이드는 기존 다이렉트 메시지 REST API에서 베타를 종료한 향상된 대체 API로 마이그레이션하는 데 도움이 되도록 작성되었습니다. 아래에서 변경 사항 요약, 신규 기능 목록, 전환에 유용한 주요 차이점과 고려 사항을 확인할 수 있습니다. 새로운 다이렉트 메시지 엔드포인트는 현재 모든 개발자에게 제공됩니다. User Streams 또는 Site Streams에서 마이그레이션하는 방법은 Account Activity API 마이그레이션 가이드를 참조하세요.

변경 사항 요약
신규 기능
다이렉트 메시지 보내기
다이렉트 메시지 받기
다이렉트 메시지 삭제

변경 사항 요약

다음 DM 엔드포인트를 아직 사용 중인 경우, 더 최신 엔드포인트로 이전해야 합니다.

사용 중단된 엔드포인트	권장 대체 엔드포인트
POST direct_messages/new	POST direct_messages/events/new
GET direct_messages/show	GET direct_messages/events/show
GET direct_messages	GET direct_messages/events/list
GET direct_messages/sent	GET direct_messages/events/list
POST direct_messages/destroy	DELETE direct_messages/events/destroy

새로운 기능

새 Direct Message API 엔드포인트는 여러 신규 기능을 지원하며, 기존 Direct Message에 대한 접근성을 개선합니다. 새로운 기능은 다음과 같습니다:

미디어 첨부(이미지, GIF, 비디오) 지원
사전 정의된 옵션 목록으로 구조화된 응답을 요청할 수 있는 기능
과거 Direct Message에 최대 30일간 접근 가능

새로운 Direct Message 기능의 전체 목록과 추가 신규 API 엔드포인트는 기술 문서를 참고하세요.

차이점 및 마이그레이션 고려 사항

새 API 엔드포인트는 이전 엔드포인트와 동작 방식이 크게 다릅니다. 엔드포인트 URL만 바꾸면 애플리케이션에서 오류가 발생합니다. 마이그레이션에 맞춰 애플리케이션을 업데이트할 때는 아래 사항을 유의하세요.

새로운 다이렉트 메시지 객체

가장 먼저 눈에 띄는 점은 다이렉트 메시지의 새로운 객체 구조입니다. 이 새로운 Message Create 객체 구조는 Quick Replies와 Attachments 같은 신규 기능을 지원하기 위해 도입되었습니다. 이 객체에는 더 작고 간소화된 사용자 객체도 포함됩니다. 애플리케이션은 이 새로운 객체 구조를 반영하도록, 파싱 로직은 물론 필요 시 데이터 모델이나 스토리지도 업데이트해야 합니다. 각 속성에 대한 설명은 Message Create Object 전체 문서를 참조하세요. 예시 Message Create 객체

{
      "type": "message_create",
      "id": "1234858592",
      "created_timestamp": "1392078023603",
      "initiated_via": {
        "tweet_id": "123456",
        "welcome_message_id": "456789"
      },
      "message_create": {
        "target": {
          "recipient_id": "1234858592"
        },
        "sender_id": "3805104374",
        "source_app_id": "268278",
        "message_data": {
          "text": "Blue Bird",
          "entities": {
            "hashtags": [],
            "symbols": [],
            "urls": [],
            "user_mentions": [],
          },
          "quick_reply_response": {
            "type": "options",
            "metadata": "external_id_2"
          },
          "attachment": {
            "type": "media",
            "media": {
             ...
            }
          }
        }
      }

요약

완전히 새로워진 다이렉트 메시지 객체 구조
간소화된 사용자 객체
새로 추가된 정보(퀵 리플라이 응답, 첨부 파일 등)

다이렉트 메시지 보내기

POST direct_messages/events/new는 다이렉트 메시지를 보내기 위한 대체 엔드포인트입니다. 이 엔드포인트의 가장 큰 변화는, 개별 POST 파라미터 대신 모든 정보를 POST 요청 본문에서 JSON으로 전송한다는 점입니다. Twurl 요청 예시

twurl -A 'Content-type: application/json' -X POST /1.1/direct_messages/events/new.json -d '{"event": {"type": "message_create", "message_create": {"target": {"recipient_id": "4534871"}, "message_data": {"text": "Hello World!"}}}}'

위 요청에서 Content-Type이 application/x-www-form-urlencoded가 아니라 application/json으로 설정되어 있음을 확인하세요. 또한 OAuth 1.0a 서명을 생성할 때 JSON 본문은 서명 생성에 포함되지 않는다는 점에 유의하세요. 대부분의 OAuth 라이브러리는 이미 이를 반영하고 있습니다. twurl을 사용하는 경우 최소 0.9.3 버전을 사용 중인지 확인하세요.

요약

메시지는 JSON POST 본문에서 정의됩니다.
Content-Type 헤더는 application/json으로 설정해야 합니다.
JSON 본문은 OAuth 서명 생성에 포함되지 않습니다.

다이렉트 메시지 가져오기

과거 다이렉트 메시지는 이제 단일 API 엔드포인트로 조회합니다: GET direct_messages/events/list. 이 새로운 엔드포인트의 핵심 차이는 전송 및 수신 메시지를 모두 최신순(내림차순)으로 반환한다는 점입니다. 이는 대화 스레드를 재구성하는 데 유용할 수 있습니다. 다만 전송 또는 수신 메시지만 필요하다면 응답의 sender_id 속성을 참고해 후처리해야 합니다. 페이지네이션은 이제 다이렉트 메시지의 ID가 아니라 커서 값에 기반합니다. 각 응답에는 cursor 속성이 함께 반환됩니다. GET direct_messages/events/list는 지난 30일 동안의 과거 메시지를, 해당 기간의 메시지 수와 무관하게 최대 30일치까지 반환합니다. 커서가 반환되지 않으면 더 이상 반환할 메시지가 없다는 의미입니다. GET direct_messages/events/show를 사용해 개별 다이렉트 메시지에 접근하는 방법은 동일하지만, 반환되는 다이렉트 메시지 객체의 구조는 앞서 설명한 대로 변경되었습니다. 마지막으로, 다이렉트 메시지의 실시간 액세스는 이제 Account Activity API의 웹후크(webhook)를 통해 제공합니다. User Streams 또는 Site Streams에서 마이그레이션하는 방법은 Account Activity API 마이그레이션 가이드를 참조하세요.

요약

보낸 메시지와 받은 메시지가 이제 동일한 엔드포인트에서 반환됩니다.
최대 30일치 메시지를 반환합니다.
커서 기반 페이지네이션.
웹훅을 통한 다이렉트 메시지 실시간 접근.

다이렉트 메시지 삭제

다이렉트 메시지는 이제 DELETE direct_messages/events/destroy로 삭제할 수 있습니다. 인터페이스는 대부분 동일하며, 삭제할 메시지의 ID가 필요합니다. 주요 차이점은 이제 이 엔드포인트가 POST 요청이 아닌 DELETE 요청을 요구한다는 점입니다. 삭제된 다이렉트 메시지가 공식 X 클라이언트에 표시되는 방식은 변함이 없습니다. 다이렉트 메시지는 제공된 사용자 컨텍스트의 인터페이스에서만 제거됩니다. 대화의 다른 참여자는 여전히 해당 다이렉트 메시지에 액세스할 수 있습니다.

요약

다이렉트 메시지를 삭제하려면 ID가 필요합니다.
새 엔드포인트는 DELETE 요청이 필요합니다.
삭제된 다이렉트 메시지가 공식 X 클라이언트에 반영되는 방식은 변함이 없습니다.

**새로운 다이렉트 메시지 엔드포인트로 마이그레이션하는 데 대해 궁금한 점이 있나요? **devcommunity.com의 개발자 커뮤니티 포럼에 질문을 올려주세요.

자주 묻는 질문

일반

Account Activity API를 사용하면 어떤 이점이 있나요? Account Activity API는 webhook을 사용하므로 스트리밍 API와 달리 정보를 전달받기 위해 상시 연결을 유지할 필요가 없습니다. 또한 webhook은 REST API와도 달라서 원하는 데이터를 얻기 위해 15분마다 수백 번 폴링할 필요가 없습니다. 이는 이벤트가 발생하는 즉시 데이터를 전달하여 사용자와 앱 간 효율성을 높여 줍니다. Account Activity API의 장점은 다음과 같습니다:

속도: X의 속도로 데이터를 전달합니다.
간편성: 단일 webhook 연결을 통해 한 계정의 모든 이벤트를 전달합니다. API로 전달되는 활동에는 게시물, @멘션, 답글, 리트윗, 인용 리트윗, 인용 리트윗의 리트윗, 즐겨찾기, 보낸 다이렉트 메시지, 받은 다이렉트 메시지, 팔로우, 차단, 뮤트가 포함됩니다.
확장성: 이벤트 상한이나 요청 한도에 구애받지 않고 관리하는 계정의 모든 활동을 수신합니다.

Account Activity API는 프리미엄 샌드박스, 유료 프리미엄, 엔터프라이즈로 제공되며, 책임 관련 기능 또는 추가 기능을 위해 더 많은 계정이 필요할 경우 요구 사항에 맞춰 확장할 수 있습니다. 시작하려면 GitHub에서 샘플 코드 스니펫을 다운로드하세요. 어떤 제품 티어가 가장 적합한지 어떻게 알 수 있나요? 프리미엄 옵션과 엔터프라이즈 옵션의 차이를 알아보려면 Account Activity API 개요 페이지를 확인하세요. 프리미엄 환경과 엔터프라이즈 webhook의 차이는 무엇인가요? 차이가 없습니다. 각 프리미엄 환경에는 고유한 webhook_id가 있습니다. Account Activity API에 개발, 스테이징, 운영 환경을 구성할 수 있나요? 가능합니다! Account Activity API의 유료 티어(유료 프리미엄 및 엔터프라이즈)에서는 여러 webhook URL을 등록하고 API 메서드를 통해 환경별로 구독을 개별 관리할 수 있습니다. 또한 현재 승인된 사용자의 권한 유지를 위해 여러 클라이언트 앱을 허용 목록에 추가할 수 있습니다. Account Activity API 설정을 단계별로 안내하는 가이드가 있나요? 물론입니다!

처음 시작하신다면 webhook 시작하기 가이드를 권장합니다.
X Dev에서 제공하는 스크립트를 따라 진행하세요:
- Account Activity API 대시보드: webhook 이벤트를 표시하는 Node 웹 앱입니다.
- SnowBot 챗봇: Account Activity 및 Direct Message API를 기반으로 구축된 Ruby 웹 앱입니다. 이 코드베이스에는 Account Activity API webhook 설정을 돕는 스크립트가 포함되어 있습니다.

시스템이 일정 기간 다운되면 데이터를 복구할 수 있는 방법이 있나요? Account Activity API의 유료 티어(유료 프리미엄 및 엔터프라이즈)에서는 당사 시스템이 4시간 동안 여러 차례 활동 전송을 재시도합니다. 해당 4시간 내에 시스템이 응답하지 않으면 활동은 손실되며, 7일 이내의 데이터를 복구하려면 다른 REST 엔드포인트를 사용해야 합니다. 서로 다른 webhook이나 환경을 Account Activity Replay API와 같은 이중화 도구로 활용해 시스템 일부가 다운되더라도 활동을 놓치지 않도록 하는 것을 권장합니다. Account Activity API에는 어떤 인증을 사용해야 하나요? Account Activity API에 필요한 인가 방식은 API 레퍼런스 페이지의 각 메서드에 설명되어 있습니다. X 인증이 처음이라면 이 섹션을 먼저 읽어보시길 권장합니다. challenge-response check(CRC)란 무엇인가요? Account Activity API의 챌린지 응답 검사(CRC)는 Account Activity API의 활동이 올바른 개발자에게 전송되고 있음을 보장하기 위한 보안 기능입니다. 또한 개발자가 수신하는 데이터가 X에서 온 것임을 확인하는 데에도 사용할 수 있습니다. X는 웹훅 URL이 마지막으로 검증된 시점을 기준으로 24시간마다 한 번씩 자동으로 CRC를 해당 웹훅 URL로 전송합니다. 시스템은 검증 상태를 유지하려면 3초 이내에 유효한 응답을 반환해야 합니다. 자세한 내용은 Securing webhooks 페이지를 방문하세요. 내 웹훅 URL이 즉시 무효화될 수 있는 경우가 있나요? 다음 중 하나가 발생하면 웹훅을 즉시 무효로 표시합니다:

서버가 CRC에 잘못된 토큰으로 응답하는 경우. 이 경우 당사 시스템은 활동을 보내기 위해 재시도를 수행하지 않습니다.
웹훅 URL에 잘못된 인증서가 구성된 경우. 이 경우에도 당사 시스템은 활동을 보내기 위해 재시도를 수행하지 않습니다.
서버가 2XX, 4XX, 5XX가 아닌 응답 코드를 반환하는 경우.
gzip 사용을 지정했지만 실제로는 전송하지 않는 경우.
gzip 사용을 지정하지 않았지만 실제 응답에서 gzip을 사용하는 경우.

서로 상호작용하는 사용자에 구독되어 있으면 중복 활동을 받게 되나요? 네. 웹 앱이 사용자 A와 사용자 B에 대해 활성 구독을 보유하고 있고, 사용자 A가 게시물에서 사용자 B를 멘션하면 등록된 웹훅으로 두 개의 POST 활동이 전송됩니다. 각 활동에는 해당 활동이 어떤 구독에 속하는지 표시하기 위한 “for_user_id” 표시자가 포함됩니다. 웹훅에 대한 구독을 생성할 때, 다음 엔드포인트의 /all/ 부분을 다른 계정 활동 데이터 객체로 대체하여 API가 전달하는 활동을 제한할 수 있나요?POST https://api.x.com/1.1/account_activity/all/:env_name/subscriptions.json 아니요, 불가능합니다. 현재로서는 /all/ 제품만 제공됩니다. 사용자로부터 Direct Messages 권한을 요청하지 않고 Account Activity API를 사용할 수 있는 방법이 있나요? 현재로서는 이 API에서 Direct Messages 활동을 ‘필터링’할 방법이 없기 때문에 Direct Messages 권한이 필요합니다. Account Activity API의 무료 버전이 있나요? 네, 샌드박스 버전을 무료 티어로 제공합니다. 샌드박스 옵션은 단일 웹훅과 최대 15개의 구독으로 제한됩니다. 샌드박스 옵션에 대한 자세한 내용은 our documentation에서 확인하실 수 있습니다. 구독된 사용자를 멘션하는 게시물의 리트윗을 가져오기 위해 Account Activity API를 사용할 수 있나요? 유감스럽게도 이는 이 API가 전달하는 활동에 포함되어 있지 않습니다. 이 경우 Streaming API 사용을 권장합니다. tweet_create_event가 나타내는 가능한 활동 유형은 무엇인가요? tweet_create_event 페이로드는 다음과 같은 경우에 전송됩니다: 구독된 사용자가 다음 작업 중 하나를 수행한 경우:

게시물 작성
리트윗
게시물에 답글

다른 사용자가 다음을 수행한 경우:

구독된 사용자를 @멘션*
구독된 사용자가 만든 트윗을 인용

*참고: Account Activity API는 구독된 사용자가 X에서 알림을 받고 해당 이벤트를 공개적으로 볼 수 있는 경우에만 이벤트를 전달합니다. 즉, 멘션된 계정(@userA)이 보호된 계정(@userB)을 팔로우하는 경우 UserA는 UserB가 자신을 멘션했다는 알림을 받습니다. UserA가 UserB를 팔로우하지 않았고(UserB의 승인을 받지 못한 경우) 알림을 받지 못한다면, @userA가 구독을 보유하고 있더라도 AAA를 통해 tweet_create_event는 전송되지 않습니다. 차단된 사용자가 내 구독 사용자를 멘션하면 이를 어떻게 식별할 수 있나요? JSON 응답의 최상위에 “user_has_blocked”라는 불리언 필드가 있으며, 값은 “true” 또는 “false”로 설정됩니다. 이 필드는 게시물 멘션에서만 노출됩니다. Enterprise 내 앱을 allowlist에 추가하거나 이미 allowlist에 있는지 확인하려면 어떻게 하나요? Enterprise API를 통해 액세스할 수 있도록 허용 목록에 추가한 X apps를 관리하려면 앱 ID와 함께 계정 담당자에게 문의하세요. 앱 ID는 developer portal에서 “Apps” 페이지로 이동하여 확인할 수 있습니다. 웹훅 3개에 대한 액세스 권한이 있다면, 엔터프라이즈 용도로 등록한 각 앱에 웹훅 3개씩 사용할 수 있나요? 웹훅 제한은 앱 단위가 아닌 계정 단위로 설정됩니다. 웹훅 3개에 대한 액세스 권한이 있고 엔터프라이즈 용도로 등록된 앱이 2개라면, 한 앱에 2개, 다른 앱에 1개를 사용할 수 있지만 각 앱에 3개씩 사용할 수는 없습니다. Account Activity Replay API로 재전달할 이벤트 유형을 지정할 수 있나요? 재전송할 이벤트 유형은 지정할 수 없습니다. 지정한 날짜 및 시간 범위에 전달된 모든 이벤트가 재생됩니다. 내 애플리케이션이 Account Activity Replay API 이벤트 수집에 실패한 경우 재시도가 있나요? 아니요, 재시도는 없습니다. 애플리케이션이 Account Activity Replay API가 전송한 이벤트 수집에 실패한 경우, 동일한 기간에 대해 다른 Replay 작업을 제출하여 누락된 Replay 이벤트의 재전달을 시도할 수 있습니다. 부분 성공 완료 이벤트를 수신하면 무엇을 해야 하나요? 수신된 이벤트의 타임스탬프를 기록한 뒤, 누락된 이벤트에 대해 또 다른 Replay 작업을 요청할 것을 권장합니다. 동시에 실행할 수 있는 Account Activity Replay API 작업은 몇 개인가요? 웹훅당 동시에 하나의 Account Activity Replay API 작업만 실행할 수 있습니다. 웹훅으로 전달될 때 Account Activity Replay API 이벤트를 실시간 프로덕션 이벤트와 어떻게 구분할 수 있나요? Account Activity Replay API는 항상 과거의 이벤트를 전달하므로, 이벤트의 타임스탬프를 기준으로 실시간 프로덕션 이벤트와 구분할 수 있습니다. 애플리케이션에서 누락하거나 드롭한 활동을 재전달하기 위해 Account Activity Replay API를 얼마나 빨리 사용할 수 있나요? 활동은 생성된 후 약 10분이 지나면 재전달 가능해집니다.

오류 해결 가이드

코드 32

이 오류는 일반적으로 요청, 헤더, 인가 또는 지정한 URL 중 하나의 형식이 잘못되었음을 의미합니다. 이는 Account Activity API 오류가 아니라 인가 오류이며, X가 올바르게 설정된 OAuth 또는 URL을 받지 못하고 있다는 뜻입니다.

Enterprise - 사용 중인 컨슈머 키와 액세스 토큰이 Enterprise 제품 사용을 위해 등록된 X 앱에 속해 있는지 확인하세요. 컨슈머 키와 액세스 토큰이 없거나 X 앱을 허용 목록에 추가해야 한다면 담당 어카운트 매니저에게 문의하세요.
사용자 컨텍스트로 인증하는 경우 oauth nonce, oauth_signature, oauth_timestamp를 올바르게 포함하여 요청을 인가했는지 확인하세요.
액세스 토큰에 올바른 권한 수준이 설정되어 있는지 확인하세요.
- 앱 대시보드의 ‘Keys and tokens’ 탭에서 액세스 토큰에 ‘Read, write, and direct messages’ 권한 수준이 부여되어 있는지 확인하세요.
- 토큰의 권한 수준이 이보다 낮다면 ‘Permissions’ 탭으로 이동해 권한을 ‘Read, write, and direct messages’로 조정한 뒤, ‘Keys and tokens’ 탭에서 액세스 토큰과 시크릿을 다시 생성하세요.
URL이 올바르게 구성되어 있는지 확인하세요.
- :env_name은 대소문자를 구분합니다.

코드 200 - Forbidden

Premium - API에 요청하기 전에 승인된 개발자 계정이 있는지 확인하세요. 또한 요청에서 올바른 :env_name을 사용해야 하며, 이는 dev environments 페이지에서 설정할 수 있습니다.
Enterprise - 담당 어카운트 매니저가 Account Activity API 접근 권한을 부여했는지 확인하세요.
URI를 올바르게 구성했는지 확인하세요. 요청에 잘못된 URI를 입력하면 이 오류가 발생할 수 있습니다.

코드 214 - Webhook URL이 요구 사항을 충족하지 않습니다.

HTTPS를 사용하고 있는지 확인하세요.
Webhook URL이 잘못된 형식일 수 있습니다.
웹훅 시작하기 페이지의 웹훅 소비자 앱 개발 섹션에서 웹훅 URL 설정 방법을 자세히 알아보세요.

코드 214 - CRC GET 요청의 지연 시간이 높습니다. 웹훅은 3초 이내에 응답해야 합니다.

이는 서버 응답이 느리다는 뜻입니다. CRC에 3초 내로 응답하는지 확인하세요.

코드 214 - CRC GET 요청 중 200이 아닌 응답 코드(예: 404, 500 등)

서버가 중단되었을 수 있습니다. 서버가 정상적으로 동작 중인지 확인하세요.

코드 214 - 이미 너무 많은 리소스가 생성되었습니다.

Enterprise - 이미 사용 가능한 webhook을 모두 소진했습니다. 등록된 각 앱에 대해 GET webhooks 엔드포인트를 사용하여 webhook이 어디에 배포되어 있는지 확인하세요.

코드 261 - 애플리케이션이 쓰기 작업을 수행할 수 없습니다.

API와 함께 사용 중인 앱의 액세스 토큰 및 액세스 토큰 시크릿에 적절한 권한 수준이 설정되어 있지 않습니다. X apps 대시보드의 ‘Keys and tokens’ 탭으로 이동해 액세스 토큰과 액세스 토큰 시크릿에 부여된 권한 수준을 확인하세요. 값이 ‘Read, write and Direct Messages’가 아니라면 ‘Permission’ 탭에서 설정을 변경한 뒤, 새 설정을 적용하기 위해 액세스 토큰과 액세스 토큰 시크릿을 재발급하세요.
또는 앱 전용 인증으로 웹훅을 등록하려 하고 있을 수 있으며, 이는 지원되지 않습니다. Enterprise Account Activity API의 웹훅 등록 API 레퍼런스에 명시된 대로 사용자 컨텍스트로 인증하세요.

Account Activity API 참고 색인


용도	엔터프라이즈
웹훅 URL 등록 / webhook_id 생성	POST webhooks
모든 웹훅 URL과 해당 상태 반환	GET webhooks
챌린지 응답 검사 수동 트리거	PUT webhooks/:webhook_id
애플리케이션을 계정 이벤트에 구독시키기	POST webhooks/:webhook_id/subscriptions/all
현재 활성 구독 수 반환	GET subscriptions/count
특정 웹훅이 해당 계정에 구독되어 있는지 확인	GET webhooks/:webhook_id/subscriptions/all
현재 활성 구독 목록 반환	GET webhooks/:webhook_id/subscriptions/all/list
웹훅 삭제	DELETE webhooks/:webhook_id
3-legged OAuth를 사용하여 구독 비활성화(사용 중단됨)	DELETE webhooks/:webhook_id/subscriptions/all
애플리케이션 전용 OAuth를 사용하여 구독 비활성화	DELETE webhooks/:webhook_id/subscriptions/:user_id/all.json
웹훅으로 활동 재전송	POST replay/webhooks/:webhook_id/subscriptions/all

엔터프라이즈 계정 활동 API

POST account_activity/webhooks

지정된 애플리케이션 컨텍스트에 대해 새 webhook URL을 등록합니다. 저장 전에 CRC 요청으로 URL을 검증합니다. 검증이 실패하면 요청자에게 상세한 오류 메시지를 반환합니다. 허용되는 webhook 수는 요금제에 따라 결정됩니다.

리소스 URL

https://api.x.com/1.1/account_activity/webhooks.json

리소스 정보


응답 형식	JSON
인증 필요	예(사용자 컨텍스트 - 모든 컨슈머 키 및 액세스 토큰)
요청 제한	예
15분당 요청 수(사용자 인증)	15
트윗 편집 지원	모든 트윗 객체에는 해당 트윗의 편집 이력을 설명하는 트윗 편집 메타데이터가 포함됩니다. 자세한 내용은 “트윗 편집” 기본 사항 페이지를 참조하세요.

매개변수


url (필수)	콜백 엔드포인트용으로 인코딩된 URL입니다.

예시 요청

$ curl —request POST —url ‘https://api.x.com/1.1/account_activity/webhooks.json?url=https%3A%2F%2Fyour_domain.com%2Fwebhooks%2Ftwitter%2F0' —header ‘authorization: OAuth oauth_consumer_key=“CONSUMER_KEY”, oauth_nonce=“GENERATED”, oauth_signature=“GENERATED”, oauth_signature_method=“HMAC-SHA1”, oauth_timestamp=“GENERATED”, oauth_token=“ACCESS_TOKEN”, oauth_version=“1.0“‘

HTTP 응답

HTTP 코드	메시지
200	Webhook URL이 제공된 애플리케이션에 등록되었습니다
403	요청에 오류가 있습니다. 아래의 오류 메시지 섹션을 확인하세요.

성공 예시 응답

_HTTP 200_

    {
      "id": "1234567890",
      "url": "https://your_domain.com/webhook/twitter/0",
      "valid": true,
      "created_at": "2016-06-02T23:54:02Z"
    }

오류 메시지

코드	메시지
214	Webhook URL이 요건을 충족하지 않습니다.
214	이미 생성된 리소스가 너무 많습니다.
214	Webhook URL이 요건을 충족하지 않습니다. CRC 토큰이 잘못되었거나 JSON 응답 형식이 올바르지 않습니다.
214	CRC GET 요청의 지연 시간이 큽니다. Webhook은 3초 이내에 응답해야 합니다.
214	CRC GET 요청 중 200이 아닌 응답 코드(예: 404, 500 등)가 반환되었습니다.

HTTP 403

    {
      "errors": [
        {
          "code": 214,
          "message": "생성된 리소스가 너무 많습니다."
        }
      ]
    }

GET account_activity/webhooks

지정된 애플리케이션의 모든 URL과 해당 상태를 반환합니다. 일일 유효성 검사에 실패한 URL은 무효로 표시됩니다. URL을 다시 활성화하려면 업데이트 엔드포인트를 호출하세요.

리소스 URL

https://api.x.com/1.1/account_activity/webhooks.json

리소스 정보


응답 형식	JSON
인증 필요	예(애플리케이션 전용 - 베어러 토큰)
속도 제한	예
요청 수/15분 간격(애플리케이션 인증)	15

예시 요청

    $ curl --request GET
     --url https://api.x.com/1.1/account_activity/webhooks.json
     --header 'authorization: Bearer TOKEN'

응답 예시

HTTP 200 OK

    [
      {
        "id": "1234567890",
        "url": "https://your_domain.com/webhook/twitter/0",
        "valid": true,
        "created_at": "2016-06-02T23:54:02Z"
      }
      {
        "id": "2468013579",
        "url": "https://your_domain2.com/webhook/twitter/0",
        "valid": true,
        "created_at": "2016-06-04T22:31:29Z"
      }
    ]

오류 메시지

코드	메시지
99	이 리소스에 접근할 권한이 없습니다.

PUT account_activity/webhooks/:webhook_id

지정된 webhook의 URL에 대해 CRC(Challenge Response Check)를 실행합니다. 검사가 성공하면 204를 반환하고 상태를 valid로 설정하여 webhook을 다시 활성화합니다.

리소스 URL

https://api.x.com/1.1/account_activity/webhooks/:webhook_id.json

리소스 정보


응답 형식	JSON
인증 필요	예(사용자 컨텍스트 - 모든 컨슈머 키 및 액세스 토큰)
요청 제한	예
15분당 요청 수(사용자 인증)	15

매개변수


webhook_id (필수)	Webhook ID. 리소스 경로에 정의됩니다.

요청 예시

    $ curl --request PUT
     --url https://api.x.com/1.1/account_activity/webhooks/:WEBHOOK_ID.json
     --header 'authorization: OAuth oauth_consumer_key="CONSUMER_KEY", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="ACCESS_TOKEN", oauth_version="1.0"'

응답

HTTP 204 OK

{ }

오류 메시지

코드	메시지
34	Webhook이 존재하지 않거나 다른 X 애플리케이션에 연결되어 있습니다.
214	Webhook URL이 요구 사항을 충족하지 않습니다.
214	Webhook URL이 요구 사항을 충족하지 않습니다. CRC 토큰 또는 JSON 응답 형식이 올바르지 않습니다.
214	CRC GET 요청의 지연 시간이 높습니다. Webhook은 3초 이내에 응답해야 합니다.
214	CRC GET 요청 중 200이 아닌 응답 코드(예: 404, 500 등)가 반환되었습니다.

POST account_activity/webhooks/:webhook_id/subscriptions/all

지정된 사용자 컨텍스트에 대해, 모든 메시지 유형의 모든 이벤트를 지정된 애플리케이션이 구독하도록 합니다. 활성화되면 요청 사용자에 관한 모든 이벤트가 POST 요청을 통해 애플리케이션의 webhook으로 전송됩니다. 구독은 현재 계정 구성에 따라 제한됩니다. 더 많은 구독이 필요하면 계정 관리자에게 문의하세요.

리소스 URL

https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/all.json

리소스 정보


응답 형식	JSON
인증 필요	예 (3-legged OAuth - 화이트리스트된 컨슈머 키 및 구독 사용자 액세스 토큰)
속도 제한	예
요청 수/15분 창(사용자 인증)	500

매개변수


webhook_id (필수)	Webhook ID. 리소스 경로에서 정의됩니다.

예제 요청

    $ curl --request POST
     --url https://api.x.com/1.1/account_activity/webhooks/:WEBHOOK_ID/subscriptions/all.json
     --header 'authorization: OAuth oauth_consumer_key="WHITELISTED_CONSUMER_KEY", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="SUBSCRIBING_USER'S_ACCESS_TOKEN", oauth_version="1.0"'

예시 응답 - 성공

HTTP 204 NO CONTENT

{}

오류 메시지

코드	메시지
34	웹후크가 존재하지 않거나 다른 X 애플리케이션에 연결되어 있습니다.
348	클라이언트 애플리케이션은 이 사용자의 웹후크 구독에 접근할 수 없습니다.

GET account_activity/subscriptions/count

현재 계정에서 활성화된 구독 수를 반환합니다. /count 엔드포인트는 애플리케이션 전용 OAuth가 필요하므로 사용자 컨텍스트 대신 베어러 토큰으로 요청해야 합니다.

리소스 URL

https://api.x.com/1.1/account_activity/subscriptions/count.json

리소스 정보


응답 형식	HTTP 응답 코드
인증 필요	예(애플리케이션 전용 - 베어러 토큰)
속도 제한	예
15분당 요청 수(애플리케이션 인증)	15

HTTP 응답 코드


코드	메시지
200	성공. 요청한 webhook의 구독 수가 반환됩니다.
401	애플리케이션에 지정된 webhook의 구독을 조회할 권한이 없습니다.

예제 요청

    $ curl --request GET
     --url https://api.x.com/1.1/account_activity/subscriptions/count.json
     --header 'authorization: Bearer TOKEN'

예시 응답 - 성공

HTTP 200

    {
      "account_name":"my-account",
      "subscriptions_count_all":"1",
      "subscriptions_count_direct_messages":"0",
      "provisioned_count":"50"
    }

오류 메시지

코드	메시지
32	인증할 수 없습니다.

HTTP 401

    {
      "errors": [
        {
           "code": 32,
          "message": "사용자를 인증할 수 없습니다."
        }
      ]
    }

GET account_activity/webhooks/:webhook_id/subscriptions/all

웹훅 설정이 지정한 사용자의 이벤트에 대해 구독되어 있는지 확인하는 방법을 제공합니다. 지정한 사용자 컨텍스트가 해당 애플리케이션에 대해 활성 구독 상태라면 204 OK를 반환합니다. 응답 코드가 204가 아니면 해당 사용자에게 활성 구독이 없습니다. 자세한 내용은 아래의 HTTP 응답 코드 및 오류 메시지를 참조하세요.

리소스 URL

https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/all.json

리소스 정보


응답 형식	JSON
인증 필요	예(3-legged OAuth — 화이트리스트에 등록된 consumer key 및 구독 중인 사용자의 액세스 토큰)
요청 제한	예
요청 수/15분(사용자 인증)	500

매개변수


webhook_id (필수)	웹훅 ID. 리소스 경로에서 정의됩니다.

예제 요청

$ curl —request GET —url https://api.x.com/1.1/account_activity/webhooks/:WEBHOOK_ID/subscriptions/all.json —header ‘authorization: OAuth oauth_consumer_key=“WHITELISTED_CONSUMER_KEY”, oauth_nonce=“GENERATED”, oauth_signature=“GENERATED”, oauth_signature_method=“HMAC-SHA1”, oauth_timestamp=“GENERATED”, oauth_token=“SUBSCRIBING_USER’S_ACCESS_TOKEN”, oauth_version=“1.0“‘

예시 응답 - 성공

HTTP 204 콘텐츠 없음

{ }

GET account_activity/webhooks/:webhook_id/subscriptions/all/list

지정된 webhook의 현재 All Activity 유형 구독 목록을 반환합니다. /list 엔드포인트는 애플리케이션 전용 OAuth가 필요하므로 요청은 사용자 컨텍스트 대신 베어러 토큰으로 수행해야 합니다.

리소스 URL

https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/all/list.json

리소스 정보


응답 형식	HTTP 응답 코드
인증 필요	예(애플리케이션 전용 - 베어러 토큰)
할당량 제한	예
15분당 요청 수(애플리케이션 인증)	50

매개변수


webhook_id (필수)	웹후크 ID. 리소스 경로에서 정의됩니다.

HTTP 응답 코드

코드	메시지
200	성공. 요청한 webhook의 구독 목록이 반환됩니다.
401	지정된 webhook의 구독을 조회할 권한이 애플리케이션에 없습니다.

예시 요청

$ curl —request GET —url https://api.x.com/1.1/account_activity/webhooks/:WEBHOOK_ID/subscriptions/all/list.json —header ‘authorization: Bearer TOKEN’

예시 응답 - 성공

HTTP 200

    {
      "webhook_id": "1234567890",
      "webhook_url": "https://your_domain.com/webhook/twitter/0",
      "application_id": "11231812",
      "subscriptions": [{
        "user_id": "20212306"
      }]
    }

오류 메시지

코드	메시지
32	인증에 실패했습니다.

HTTP 401

    {
      "errors": [
        {
           "code": 32,
          "message": "인증할 수 없습니다."
        }
      ]
    }

DELETE account_activity/webhooks/:webhook_id

제공된 애플리케이션의 구성에서 웹후크를 제거합니다. 웹후크 ID는 GET /1.1/account_activity/webhooks 호출로 확인할 수 있습니다.

리소스 URL

https://api.x.com/1.1/account_activity/webhooks/:webhook_id.json

리소스 정보


응답 형식	JSON
인증 필요	예(사용자 컨텍스트 — 모든 소비자 키 및 액세스 토큰)
속도 제한	예
요청/15분 윈도우(사용자 인증)	15

매개변수


webhook_id (필수)	Webhook ID. 리소스 경로에서 정의됩니다.

요청 예시

    $ curl --request DELETE
     --url https://api.x.com/1.1/account_activity/webhooks/:WEBHOOK_ID.json
     --header 'authorization: OAuth oauth_consumer_key="CONSUMER_KEY", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="ACCESS_TOKEN", oauth_version="1.0"'

응답

HTTP 204 OK

{ }

DELETE account_activity/webhooks/:webhook_id/subscriptions/all (사용 중단됨)

제공된 사용자 컨텍스트와 애플리케이션의 구독을 비활성화합니다. 비활성화되면 요청한 사용자에 대한 모든 이벤트가 더 이상 webhook URL로 전송되지 않습니다.

리소스 URL

https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/all.json

리소스 정보


응답 형식	JSON
인증 필요	예 (3-legged OAuth - 화이트리스트에 등록된 컨슈머 키 및 구독된 사용자의 액세스 토큰)
속도 제한	예
요청 수/15분(사용자 인증)	500

매개변수


webhook_id (필수)	Webhook ID. 리소스 경로에 정의됩니다.

예제 요청

    $ curl --request DELETE
     --url https://api.x.com/1.1/account_activity/webhooks/:WEBHOOK_ID/subscriptions/all.json
     --header 'authorization: OAuth oauth_consumer_key="WHITELISTED_CONSUMER_KEY", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="SUBSCRIBED_USER'S_ACCESS_TOKEN", oauth_version="1.0"'

예시 요청

{ }

DELETE /account_activity/webhooks/:webhook_id/subscriptions/:user_id/all.json

지정된 webhook과 사용자 id의 구독을 비활성화합니다. 비활성화되면 요청한 사용자에 대한 모든 이벤트가 더 이상 webhook URL로 전송되지 않습니다. 참고: 이 엔드포인트는 애플리케이션 전용 OAuth가 필요하므로, 요청은 사용자 컨텍스트 대신 베어러 토큰을 사용해 수행해야 합니다.

리소스 URL

https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/:user_id/all.json

리소스 정보


응답 형식	JSON
인증 필요	예(애플리케이션 전용 - 베어러 토큰)
속도 제한	예
요청/15분 창	500

예시 요청

    $ curl --request DELETE
     --url https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/:user_id/all.json
     --header 'authorization: Bearer TOKEN'

응답

HTTP 204 내용 없음

오류 메시지

코드	메시지
404	죄송합니다. 해당 페이지가 존재하지 않습니다. - 지정한 사용자 id가 실제로 구독되어 있지 않을 때 자주 발생합니다.

Replay API

POST /1.1/account_activity/replay/webhooks/:webhook_id/subscriptions/all.json ¶ 요청에 지정한 날짜 및 시간 창 동안 존재했던 모든 구독에서 최대 최근 5일간의 활동을 가져오도록 요청을 제출합니다. 웹훅에 활성 사용자 구독이 있는 경우 해당 이벤트도 동시에 수신합니다. 참고: 리플레이 이벤트를 전달하기 전에 CRC를 수행합니다.


Request Method	HTTP POST
URL	/1.1/account_activity/replay/webhooks/:webhook_id/subscriptions/all.json?from_date=yyyymmddhhmm&to_date=yyyymmddhhmm
Response Format	JSON
Requires Authentication	예 (application only - 베어러 토큰)
Rate Limit	15분당 요청 5건. 현재 요청 가능한 리플레이 작업 수에는 상한이 없습니다.
from_date	이벤트 제공의 기준이 되는 가장 오래된(시작) UTC 타임스탬프로, ‘yyyymmddhhmm’ 형식이어야 합니다. 타임스탬프는 분 단위 정밀도를 가지며 포함 범위입니다(예: 12:00은 00분을 포함). 유효한 시간은 최근 5일 이내의 UTC여야 하며, 현재 시점으로부터 최소 31분 이전이어야 합니다. from_date와 to_date는 약 2시간 이내 범위로 설정하는 것을 권장합니다.
to_date	이벤트 제공의 기준이 되는 가장 최신(종료) UTC 타임스탬프로, ‘yyyymmddhhmm’ 형식이어야 합니다. 타임스탬프는 분 단위 정밀도를 가지며 제외 범위입니다(예: 12:30은 해당 시각의 30분을 포함하지 않음). 유효한 시간은 최근 5일 이내의 UTC여야 하며, 현재 시점으로부터 최소 10분 이전이어야 합니다.

응답

다음 응답이 API에서 반환될 수 있습니다. 대부분의 오류 코드는 본문에 추가 세부 정보가 포함된 문자열과 함께 반환됩니다. 200이 아닌 응답의 경우 오류를 해결한 뒤 다시 시도하세요.

상태	텍스트	오류 코드	설명	메시지
202	Accepted	N/A	요청이 성공했으며 활동이 전송됩니다.	N/A
400	Bad Request	214	Webhook이 유효하지 않은 것으로 표시되었습니다.	Webhook이 유효하지 않은 것으로 표시되었으며 CRC 검사가 필요합니다.
400	Bad Request	357	쿼리 매개변수가 누락되었습니다.	: queryParam은(는) 필수입니다.
400	Bad Request	358	경로 또는 쿼리 매개변수 형식이 올바르지 않습니다.	매개변수를 구문 분석할 수 없습니다.
400	Bad Request	360	경로 매개변수가 음수입니다.	webhook_id: [] 값이 0보다 크거나 같지 않습니다.
400	Bad Request	368	from_date 또는 to_date가 과거 시점이 아닙니다.	: [<field_value>] 값이 과거 시점이 아닙니다.
400	Bad Request	356	from_date는 to_date보다 이전이어야 합니다.	from_date는 to_date보다 이전이어야 합니다.
400	Bad Request	356	from_date는 최근 5일 이내여야 합니다.	from_date는 최근 5일 이내여야 합니다.
401	Unauthorized	32	제공된 3-legged 인증으로 인해 HTTP 인증에 실패했습니다.	잘못된 인증 방식입니다. 애플리케이션 전용 인증을 사용하세요.
401	Unauthorized	61	클라이언트는 이 메서드를 요청할 권한이 없습니다.	클라이언트는 이 메서드를 요청할 권한이 없습니다.
403	Forbidden	200	클라이언트에 Replay가 활성화된 엔터프라이즈 계정이 없습니다.	Account Activity API 엔터프라이즈 계정과 Replay가 필요합니다. 엔터프라이즈 계정이 있으며 Replay가 활성화되어 있는지 확인하세요.
404	Not Found	34	존재하지 않는 webhook_id; webhook_id-application_id 불일치.	Webhook이 존재하지 않거나 다른 X 애플리케이션과 연결되어 있습니다.
409	Conflict	355	진행 중인 요청이 있어 다른 요청을 하기 전에 처리가 완료되어야 합니다.	이 webhook에 대한 재생 작업이 이미 진행 중입니다.
429	Too Many Requests	88	속도 제한(일정 기간당 요청 수 한도 도달)	요청이 너무 많습니다. API 요청 속도를 낮추세요.
500	Internal Server Error	0	내부 서버 오류.	내부 서버 오류.
503	Service Unavailable	67	X의 하나 이상의 종속 서비스가 사용 불가입니다.	X 서버 오류입니다. 지수 백오프 패턴으로 재시도하세요.

”작업이 성공적으로 완료되었습니다” 메시지

작업이 성공적으로 완료되면 Account Activity Replay API가 다음과 같은 작업 완료 이벤트를 전달합니다. 이 이벤트를 수신하면 해당 작업이 종료된 것이며, 이어서 다른 작업을 제출할 수 있습니다.

{
  "replay\_job\_status": {
    "webhook_id": "1234577122340233217",
    "job_state": "Complete",
    "job\_state\_description": "작업이 성공적으로 완료됨"
    "job_id": "1095098195724558337"
  }
}

”작업 완료 실패” 메시지

작업이 정상적으로 완료되지 않으면 Replay 작업을 다시 시도하라는 다음 메시지를 반환합니다. 이 이벤트를 수신하면 해당 작업의 실행이 종료되었으며, 다른 작업을 제출할 수 있습니다.

{
  "replay\_job\_status": {
    "webhook_id": "123451374207332352",
    "job_state": "Incomplete",
    "job\_state\_description": "모든 이벤트를 전달하지 못했습니다. 재생 작업을 다시 시도하세요",
    "job_id": "1093226942650736640"
  }
}

curl 요청 예시

    curl --request POST  --url 'https://api.x.com/1.1/account_activity/replay/webhooks/:webhook_id/subscriptions/all.json?from_date=yyyymmddhhmm&to_date=yyyymmddhhmm'
    --header 'authorization: Bearer TOKEN'

예시 응답

HTTP 202

{
  "job_id": "1234567890",
  "created_at": "2016-06-02T23:54:02Z"
}

개요

게시물

사용자

다이렉트 메시지

마음에 들어요

목록

스페이스

커뮤니티

커뮤니티 메모

트렌드

미디어

X 활동 내역

사용

스트림 연결하기

준수 사항

엔터프라이즈 v2

좋아요 스트림

GNIP 2.0

​동영상 시리즈

​기능 요약

​웹훅과 구독 사용자 관리

​웹훅 관리:

​구독 사용자 관리:

​참고 문서

​Account Activity API 동영상 가이드

​웹후크 시작하기

​1. X 앱을 생성하세요.

​2. Account Activity API 액세스 얻기

​3. 웹훅 컨슈머 앱 개발

​4. 설정 검증

​웹훅 보안

​챌린지-응답 검사

​CRC 요청은 다음과 같은 경우에 발생합니다:

​응답 요구 사항:

​언어별 HMAC 라이브러리

​Python에서의 응답 토큰 생성 예시:

​예시 JSON 응답:

​기타 예시:

​선택적 시그니처 헤더 검증

​추가 보안 지침

​X 집계 네트워크 블록

​권장 서버 구성

​웹훅과 구독 관리

​웹후크 생성 및 변경

​Webhook 구성 관리 엔드포인트:

​왜 웹훅 URL만 업데이트할 수 없나요?

​사용자 구독 추가 및 제거

​구독 관리 엔드포인트

​재시도

​재시도란 무엇인가요?

​재시도 타임라인

​재시도 타임라인

​Account Activity 데이터 객체 구조

​tweet_create_events (게시물, 리포스트, 답글, 인용 게시물)

​tweet_create_events (@맨션)

​favorite_events

​follow_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

​Account Activity Replay API

​Account Activity Replay API 사용

​제한 사항

​데이터 가용성 및 유형

​마이그레이션 소개

​마이그레이션 가이드: User Streams/Site Streams에서 Account Activity API로 전환

​변경 사항 요약

​사용 중단된 API

​대체용 API

​차이점 및 마이그레이션 고려사항

​새로운 기능

​사용자 구독 관리

​마이그레이션 방법

동영상 시리즈

기능 요약

웹훅과 구독 사용자 관리

웹훅 관리:

구독 사용자 관리:

참고 문서

Account Activity API 동영상 가이드

웹후크 시작하기

1. X 앱을 생성하세요.

2. Account Activity API 액세스 얻기

3. 웹훅 컨슈머 앱 개발

4. 설정 검증

웹훅 보안

챌린지-응답 검사

CRC 요청은 다음과 같은 경우에 발생합니다:

응답 요구 사항:

언어별 HMAC 라이브러리

Python에서의 응답 토큰 생성 예시:

예시 JSON 응답:

기타 예시:

선택적 시그니처 헤더 검증

추가 보안 지침

X 집계 네트워크 블록

권장 서버 구성

웹훅과 구독 관리

웹후크 생성 및 변경

Webhook 구성 관리 엔드포인트:

왜 웹훅 URL만 업데이트할 수 없나요?

사용자 구독 추가 및 제거

구독 관리 엔드포인트

재시도

재시도란 무엇인가요?

재시도 타임라인

재시도 타임라인

Account Activity 데이터 객체 구조

tweet_create_events (게시물, 리포스트, 답글, 인용 게시물)

tweet_create_events (@맨션)

favorite_events

follow_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

Account Activity Replay API

Account Activity Replay API 사용

제한 사항

데이터 가용성 및 유형

마이그레이션 소개

마이그레이션 가이드: User Streams/Site Streams에서 Account Activity API로 전환

변경 사항 요약

사용 중단된 API

대체용 API

차이점 및 마이그레이션 고려사항

새로운 기능

사용자 구독 관리

마이그레이션 방법

Site Streams API에서 Account Activity API로 쉽게 마이그레이션하려면 아래 단계를 따르세요

Account Activity 대시보드(샘플 Account Activity API 애플리케이션)

사용 가능한 활동

사용 중단된 스트리밍 메시지 유형

사용 중단된 이벤트 유형

다이렉트 메시지 마이그레이션 가이드

변경 사항 요약

새로운 기능

차이점 및 마이그레이션 고려 사항

새로운 다이렉트 메시지 객체

요약

다이렉트 메시지 보내기

요약

다이렉트 메시지 가져오기

요약

다이렉트 메시지 삭제

요약

자주 묻는 질문