메인 콘텐츠로 건너뛰기
이 가이드에서는 Direct Messages 조회용 엔드포인트를 애플리케이션에 통합하는 데 필요한 핵심 개념을 다룹니다.

​
인증

DM 엔드포인트에서 비공개 대화에 액세스하려면 사용자 인증이 필요합니다.
MethodDescription
OAuth 2.0 Authorization Code with PKCE권장
OAuth 1.0a User Context레거시 지원
App-Only 인증은 지원되지 않습니다. 모든 다이렉트 메시지는 비공개입니다.

​
필수 스코프 (OAuth 2.0)

Scope필요한 작업
dm.readDM 이벤트 읽기
tweet.readdm.read와 함께 필요
users.readdm.read와 함께 필요

​
대화 유형

일대일

항상 정확히 두 명의 참가자가 있습니다. 대화 ID 형식: {smaller_user_id}-{larger_user_id}

그룹

두 명 이상의 참가자가 있습니다. 멤버 구성은 시간에 따라 달라질 수 있습니다.

​
이벤트 유형

이벤트설명주요 필드
MessageCreate메시지가 전송됨text, sender_id
ParticipantsJoin사용자가 그룹에 참여함participant_ids, sender_id
ParticipantsLeave사용자가 그룹에서 나감participant_ids

​
예시 이벤트

{
  "id": "1582838499983564806",
  "event_type": "MessageCreate",
  "text": "Hi everyone.",
  "sender_id": "944480690",
  "dm_conversation_id": "1578398451921985538",
  "created_at": "2022-10-19T20:58:00.000Z"
}

{
  "id": "1582835469712138240",
  "event_type": "ParticipantsJoin",
  "participant_ids": ["944480690"],
  "sender_id": "17200003",
  "dm_conversation_id": "1578398451921985538",
  "created_at": "2022-10-19T20:45:58.000Z"
}

{
  "id": "1582838535115067392",
  "event_type": "ParticipantsLeave",
  "participant_ids": ["944480690"],
  "dm_conversation_id": "1578398451921985538",
  "created_at": "2022-10-19T20:58:09.000Z"
}

​
필드와 expansions

​
기본 필드

이벤트 유형기본 필드
MessageCreateid, event_type, text
ParticipantsJoin/Leaveid, event_type, participant_ids

​
사용 가능한 필드

FieldDescriptionEvents
dm_conversation_id대화 ID전체
created_at이벤트 타임스탬프전체
sender_id보낸/초대한 사용자MessageCreate, Join
attachments미디어 첨부 파일MessageCreate
referenced_tweets공유된 포스트MessageCreate

​
사용 가능한 expansions

Expansion반환 항목
sender_id발신자 User 객체
participant_ids참여자 User 객체
attachments.media_keysMedia 객체
referenced_tweets.id게시물 객체

​
expansions 사용 예시

cURL
curl "https://api.x.com/2/dm_events?\
dm_event.fields=created_at,sender_id,attachments&\
expansions=sender_id,attachments.media_keys&\
user.fields=username,profile_image_url&\
media.fields=url,type" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"
DM 이벤트는 최신 이벤트가 먼저 오도록 시간 역순(최신순)으로 반환됩니다:
cURL
# 첫 번째 요청
curl "https://api.x.com/2/dm_events?max_results=100" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

# 페이지네이션 토큰을 사용한 후속 요청
curl "https://api.x.com/2/dm_events?max_results=100&pagination_token=NEXT_TOKEN" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"
최대 30일 전까지의 이벤트를 조회할 수 있습니다.

​
v1.1과의 ID 호환성

대화 및 이벤트 ID는 v1.1과 v2 엔드포인트에서 동일하게 사용됩니다. 이는 다음을 수행할 수 있다는 의미입니다:
  • v2를 사용해 이벤트를 가져온 후 v1.1을 사용해 특정 메시지를 삭제할 수 있습니다
  • API 요청에서 x.com URL의 대화 ID를 참조할 수 있습니다

​
다음 단계

빠른 시작

첫 번째 DM 조회 요청 보내기

DM 보내기

다이렉트 메시지 보내기

API 참조 문서

전체 엔드포인트 설명서

샘플 코드

실행 가능한 코드 예제