객체

위에서 참조한 형태를 필드별로 설명합니다. 타입은 비공식 표기입니다: string[]은 문자열 배열이고, A | null은 없을 수도 있습니다.

엔벨로프

스트림, GET /v1/events, 웹훅 전달의 모든 이벤트에 존재합니다.

필드	타입	의미
`v`	int	엔벨로프 버전. 현재 `1`
`t`	string	이벤트 타입. 아래 표 참조
`op`	create \| update \| delete	`create`, `update`(같은 id의 보강) 또는 `delete`
`id`	string	안정적인 식별자. 이 값으로 중복 제거
`ts`	int (ms)	X에서 발생한 시각, 에포크 이후 ms. X는 프로필 변경, 팔로우와 언팔로우, 인증된 팔로워 증가, 게시물 삭제가 일어난 시각을 알려 주지 않습니다. 이런 이벤트는 저희가 감지한 시각입니다
`sid`	string	리플레이용 스트림 위치. 스트림과 히스토리에 존재
`target.id`	string	모니터링 대상 계정의 숫자형 X id(`search.match`의 경우 게시물 작성자의 id)
`target.screen_name`	string	모니터링 대상 계정의 핸들
`target.name`	string	계정의 표시 이름
`d`	object	타입별 페이로드

Tweet 페이로드

tweet.create, tweet.reply, tweet.retweet, tweet.quote의 d이며, search.match의 기본 형태입니다.

필드	타입	의미
`tweet_id`	string	게시물 id, 문자열
`kind`	tweet \| reply \| retweet \| quote	게시물의 종류
`text`	string	전체 텍스트(긴 게시물 포함)
`lang`	string \| null	X가 감지한 언어
`author`	User	게시한 계정. 완전한 User 객체이며 `search.match`의 작성자와 같습니다: 핸들, 표시 이름, 소개, 아바타, 배너, 각종 수치, 인증, 위치, 링크, 가입일. 가벼운 첫 프레임에서는 마지막으로 읽은 계정 정보이고, `update`에서는 게시물과 함께 읽은 정보입니다
`reply_to`	Brief+ \| null	답글의 경우: 답글 대상 게시물. Brief에 작성자의 `screen_name`, `tweet_id`, `user_id`가 추가된 형태
`retweet_of`	Brief \| null	리포스트의 경우: 원본 게시물
`quoted`	Brief \| null	인용의 경우: 인용된 게시물
`media`	string[]	미디어 항목당 하나씩의 이미지 URL
`media_items`	Media[]	타입, 비디오 변형, 크기를 포함한 모든 미디어 항목
`urls`	string[]	게시물 내 확장된 링크
`article`	Article \| null	X 아티클을 연결한 게시물일 때: 해당 아티클
`counts`	{reply, rt, like, quote, bookmark}	읽은 시점의 답글, 리포스트, 좋아요, 인용, 북마크 수
`views`	int \| null	조회수. X가 노출하는 경우
`url`	string	게시물의 정식 링크
`full`	bool	가벼운 첫 `create` 프레임에서는 `false`, 이벤트가 게시물 전체를 담으면 `true`
`kind_final`	bool	`kind`가 확정되면 `true`. `false`는 `kind`가 `tweet`인 가벼운 첫 프레임에만 나타납니다. 그 게시물은 아직 인용일 수 있으며, 같은 `id`로 이어지는 `update`가 확정합니다
`kind_was`	tweet \| null (update only)	게시물 종류를 확정하는 `update`에만 있으며, 첫 프레임의 종류가 달랐을 때만 나타납니다. 그 프레임이 가졌던 종류입니다(인용으로 밝혀진 게시물이면 `tweet`)
`edit_of`	Brief \| null	`tweet.edit`에만: 이 버전이 대체한 버전(id와, 기록이 있으면 본문과 작성자)

Brief

다른 이벤트에 포함되는 축약형 게시물: 리포스트의 원본, 인용된 게시물, 답글 대상 게시물, 또는 고정 게시물.

필드	타입	의미
`id`	string	게시물 id
`user`	string	작성자의 핸들
`name`	string	작성자의 표시 이름
`user_id`	string	작성자의 숫자형 id
`text`	string	전체 텍스트
`media`	string[]	이미지 URL
`media_items`	Media[]	타입과 비디오 변형을 포함한 미디어 항목
`created_ms`	int	게시된 시각, 에포크 이후 ms
`url`	string	게시물 링크

Media

사진, 비디오 또는 GIF 하나. 비디오는 찾을 수 있는 최고 비트레이트의 MP4를 담으며, url은 포스터 프레임입니다.

필드	타입	의미
`type`	photo \| video \| animated_gif	미디어 종류
`url`	string	이미지 URL, 또는 비디오의 포스터 프레임
`expanded_url`	string	X의 게시물 미디어 페이지
`video_url`	string (video)	MP4 URL, 사용 가능한 최고 비트레이트
`bitrate`	int (video)	해당 MP4의 비트레이트
`duration_ms`	int (video)	비디오 길이
`width`	int	원본 너비(픽셀)
`height`	int	원본 높이(픽셀)

Article

게시물이 연결한 X 아티클(장문 게시물)입니다. 첫 프레임에는 title과 preview가 담기며, 같은 id의 update가 전문을 전달할 때까지 text는 null입니다.

필드	타입	의미
`id`	string	아티클 ID
`title`	string	제목
`preview`	string	아티클의 첫 몇 줄
`text`	string \| null	전문(단락은 빈 줄로 구분). 첫 프레임에서는 `null`
`cover`	string \| null	커버 이미지 URL
`images`	string[]	아티클 안의 이미지
`url`	string	X에서 아티클로 가는 링크

Delete 페이로드

tweet.delete의 d. 저희가 본 적 있고 지금은 사라진 게시물에 대해서만 전송됩니다. ts는 삭제를 감지한 시각이며, 게시물 자체의 시각은 그 이전의 create 프레임에 있습니다.

필드	타입	의미
`tweet_id`	string	삭제된 게시물의 id
`url`	string	게시물이 있던 위치

프로필 변경 페이로드

모든 profile.* 이벤트의 d. 이 이벤트들의 op는 update입니다.

필드	타입	의미
`field`	string	변경된 프로필 필드. 타입에서 `profile.` 뒤에 오는 것과 같은 단어
`old`	any	이전 값
`new`	any	새 값
`tweet`	Brief (pinned only)	`profile.pinned`의 경우: 새로 고정된 게시물
`old_tweet`	Brief (pinned only)	`profile.pinned`의 경우: 이전에 고정되었던 게시물(보유한 경우)

Follow 페이로드

follow.add, follow.remove, followers.verified.add의 d.

필드	타입	의미
`user`	User	상대 계정, 전체 User 형태

계정 상태 페이로드

account.status의 d. 상태는 active(정상), protected(승인된 팔로워에게만 게시물 공개), suspended(X에 의한 정지), unavailable(비활성화, 삭제 또는 기타 이유로 볼 수 없음) 중 하나입니다. ts는 저희가 변화를 감지한 시각입니다.

필드	타입	의미
`old`	active \| protected \| suspended \| unavailable	이전 상태
`new`	active \| protected \| suspended \| unavailable	현재 상태
`reason`	string \| null	X가 제공하는 문구(있는 경우, 예: `Suspended`)

User

팔로우 이벤트와 search.match에 포함되는 전체 계정 프로필.

필드	타입	의미
`id`	string	숫자형 id
`screen_name`	string	핸들
`name`	string	표시 이름
`bio`	string	소개 텍스트
`avatar`	string	아바타 이미지 URL
`banner`	string \| null	배너 이미지 URL
`followers`	int	팔로워 수
`following`	int	팔로잉 수
`tweets`	int	게시물 수
`location`	string	자유 형식 위치
`url`	string \| null	확장된 프로필 링크
`verified`	bool	인증 배지 보유 여부
`verified_type`	string \| null	`blue`, `business`, `government` 또는 `null`
`protected`	bool	승인된 팔로워만 게시물을 볼 수 있음
`created_at`	string (ISO-8601)	계정 생성 시각
`category`	string \| null	전문 카테고리. 계정이 설정한 경우

Search match 페이로드

search.match의 d: Tweet 페이로드에 매치 관련 필드 세 개가 추가된 형태. 엔벨로프의 target은 게시물 작성자이며, 모니터링 대상이 아닐 수도 있습니다.

필드	타입	의미
`keyword.id`	int	일치한 키워드의 id
`keyword.query`	string	해당 키워드의 쿼리
`keyword.label`	string \| null	해당 키워드의 라벨(설정한 경우)
`author`	User	작성자의 전체 프로필
`author_is_target`	bool	작성자가 이 시스템에서 모니터링 중인 계정이기도 하면 `true`
`…`	TweetPayload	Tweet 페이로드의 모든 필드

Target

이 키가 보는 모니터링 대상 계정 하나.

필드	타입	의미
`id`	string	숫자형 X id. 바뀌지 않으므로 기록의 키로 쓰십시오
`screen_name`	string	현재 핸들. 바뀔 수 있으며 `profile.screen_name`이 알려 줍니다
`name`	string	표시 이름
`previous_screen_names`	string[]	계정이 이전에 쓰던 핸들(최근 순). 모두 `/v1/monitor/targets/{target}`에서 계속 쓸 수 있습니다
`push_ready`	bool	이 계정에 대해 구독한 모든 이벤트 유형이 실시간으로 수집되고 있음. `false`라고 해서 보류되는 것은 없습니다. 계정은 구독한 순간부터 모니터링되고 이벤트는 수집되는 대로 전달되므로, 이 플래그를 기다리지 말고 처리하세요
`last_push_at`	datetime \| null	이 계정의 실시간 이벤트가 마지막으로 도착한 시각
`last_poll_at`	datetime \| null	마지막으로 타임라인을 읽은 시각
`state`	"subscribed"	여기서는 항상 `subscribed`. 대기 중인 조회는 별도의 형태를 가짐
`event_types`	string[]	이 계정에 대해 전달되는 이벤트 타입. 비어 있으면 키가 허용하는 전부
`event_types_all`	bool	`event_types`가 비어 있으면 `true`

대기 중인 Target

요청한 계정을 아직 조회하는 동안 GET /v1/monitor/targets/{target}이 반환하는 것.

필드	타입	의미
`screen_name`	string \| null	핸들로 요청한 경우 그 핸들
`user_id`	string \| null	id로 요청한 경우 그 사용자 id
`state`	"queued"	항상 `queued`
`queued_at`	int (unix s)	요청한 시각
`event_types`	string[]	선택한 이벤트 타입. 확인이 끝나면 적용됩니다
`event_types_all`	bool	`event_types`가 비어 있으면 `true`

Keyword

X 검색에서 감시하는 쿼리 하나.

필드	타입	의미
`id`	int	숫자형 id. 삭제할 때 사용
`query`	string	X 검색 문법의 쿼리
`label`	string \| null	설정한 라벨. 모든 매치에 그대로 포함
`active`	bool	운영자가 일시 중지한 경우 `false`
`hits`	int	지금까지 전달된 매치 수
`last_hit_at`	datetime \| null	마지막 매치
`last_run_at`	datetime \| null	마지막 검색

Account

사용한 키에 대해 GET /v1/account가 반환하는 것.

필드	타입	의미
`name`	string	발급 시 지정된 키 이름
`plan`	string	플랜 프리셋
`key_id`	string	키의 짧은 id. 지원 요청 시 안전하게 인용 가능
`scopes`	string[]	키가 보유한 스코프
`event_types`	string[]	키 전체의 이벤트 타입 허용 목록. 저희가 관리하며 비어 있으면 전부
`event_types_all`	bool	필터가 비어 있으면 `true`
`limits.max_targets`	int	모니터링 계정 상한
`limits.max_conns`	int	동시 WebSocket 상한
`limits.max_keywords`	int	키워드 상한
`limits.requests_per_minute`	int	분당 요청 예산
`usage.targets`	int	현재 모니터링 중인 계정 수
`usage.keywords`	int	현재 감시 중인 키워드 수

Webhook

GET /v1/account/webhook이 반환하는 것.

필드	타입	의미
`url`	string \| null	등록된 엔드포인트
`stats`	{ok, http_`…}`	전달 카운터: `ok`, 그리고 관측된 실패 상태별로 `http_<code>` 하나씩

필드	타입	의미
`count`	int	이 페이지의 항목 수
`has_more`	bool	다음 페이지 존재 여부
`next_cursor`	string \| null	`?cursor=`로 되돌려 보냄. 끝이면 `null`

배치 결과

POST /v1/monitor/targets:batch에 보낸 항목마다 하나씩, 같은 순서로.

필드	타입	의미
`index`	int	요청에서 항목의 위치
`status`	int	단일 항목 엔드포인트가 반환했을 HTTP 상태
`data`	object (on success)	성공 시 단일 항목 응답 본문
`error`	{code, message, details?} (on failure)	실패 시 일반적인 오류 객체

Profile (읽기)

GET /v1/users/{screen_name}, /v1/users/by-id/{user_id}, /v1/users/batch가 계정마다 반환하는 것.

필드	타입	의미
`id`	string	숫자형 id
`name`	string	표시 이름
`screen_name`	string	핸들
`bio`	string	소개 텍스트
`location`	string	자유 형식 위치
`url`	string \| null	프로필 링크
`avatar`	string	아바타 이미지 URL
`banner`	string \| null	배너 이미지 URL
`pinned`	string \| null	고정 게시물의 id
`verified`	bool	인증 배지 보유 여부
`protected`	bool	승인된 팔로워만 게시물을 볼 수 있음
`followers`	int	팔로워 수
`following`	int	팔로잉 수
`tweets`	int	게시물 수

Tweet (읽기)

읽기 엔드포인트가 반환하는 게시물. Tweet 페이로드와 같은 정보를 저희 파서가 만드는 더 평평한 형태로 담습니다.

필드	타입	의미
`id`	int	게시물 id, 숫자형
`created_ms`	int	게시된 시각, 에포크 이후 ms
`user_id`	int	작성자의 숫자형 id
`user`	string	작성자의 핸들
`name`	string	작성자의 표시 이름
`text`	string	전체 텍스트
`lang`	string \| null	X가 감지한 언어
`reply_to`	string \| null	답글 대상 핸들
`reply_to_status_id`	string \| null	답글 대상 게시물의 id
`reply_to_user_id`	string \| null	답글 대상 계정의 id
`conversation_id`	string	스레드 최상위 게시물의 id
`is_rt`	bool	리포스트 여부
`rt_of`	Brief \| null	리포스트의 경우 원본
`is_quote`	bool	다른 게시물 인용 여부
`quoted`	Brief \| null	인용된 게시물
`media`	string[]	이미지 URL
`media_items`	Media[]	타입과 비디오 변형을 포함한 미디어 항목
`urls`	string[]	확장된 링크
`views`	int \| null	조회수
`counts`	{reply, rt, like, quote, bookmark}	답글, 리포스트, 좋아요, 인용, 북마크 수
`article`	Article \| null	게시물이 연결한 X 아티클(있는 경우): 제목, 미리보기, 커버, 이미지. 전문은 `GET /v1/tweets/{tweet_id}/article`
`edit_of`	int \| null	수정된 버전이면 첫 버전의 id, 아니면 `null`
`edit_ids`	int[]	모든 버전의 id(오래된 순). 수정한 적 없는 게시물은 자기 자신만 있습니다
`source`	string \| null	게시에 사용된 클라이언트, X가 주는 그대로(HTML 링크, 예: `Twitter for iPhone`)

User 참조

팔로우 목록 읽기에 사용되는 축약형.

필드	타입	의미
`id`	string	숫자형 id
`screen_name`	string	핸들
`name`	string	표시 이름

객체