통합 가이드

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

인증

DM 엔드포인트에서 비공개 대화에 액세스하려면 사용자 인증이 필요합니다.

Method	Description
OAuth 2.0 Authorization Code with PKCE	권장
OAuth 1.0a User Context	레거시 지원

App-Only 인증은 지원되지 않습니다. 모든 다이렉트 메시지는 비공개입니다.

필수 스코프 (OAuth 2.0)

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

대화 유형

일대일

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

그룹

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

이벤트 유형

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

예시 이벤트

MessageCreate

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

ParticipantsJoin

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

ParticipantsLeave

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

필드와 expansions

기본 필드

이벤트 유형	기본 필드
MessageCreate	`id`, `event_type`, `text`
ParticipantsJoin/Leave	`id`, `event_type`, `participant_ids`

사용 가능한 필드

Field	Description	Events
`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_keys`	Media 객체
`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"

from xdk import Client

client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

# expansions를 사용하여 DM 이벤트 가져오기
for page in client.dm_events.list(
    dm_event_fields=["created_at", "sender_id", "attachments"],
    expansions=["sender_id", "attachments.media_keys"],
    user_fields=["username", "profile_image_url"],
    media_fields=["url", "type"],
    max_results=100
):
    for event in page.data:
        print(f"Event: {event.event_type} - {event.text}")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

const paginator = client.dmEvents.list({
  dmEventFields: ["created_at", "sender_id", "attachments"],
  expansions: ["sender_id", "attachments.media_keys"],
  userFields: ["username", "profile_image_url"],
  mediaFields: ["url", "type"],
  maxResults: 100,
});

for await (const page of paginator) {
  page.data?.forEach((event) => {
    console.log(`Event: ${event.event_type} - ${event.text}`);
  });
}

페이지네이션

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"

from xdk import Client

client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

# SDK가 페이지네이션을 자동으로 처리합니다
all_events = []

for page in client.dm_events.list(max_results=100):
    if page.data:
        all_events.extend(page.data)

print(f"Found {len(all_events)} DM events")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

async function getAllDMEvents() {
  const allEvents = [];

  // SDK가 페이지네이션을 자동으로 처리합니다
  const paginator = client.dmEvents.list({ maxResults: 100 });

  for await (const page of paginator) {
    if (page.data) {
      allEvents.push(...page.data);
    }
  }

  return allEvents;
}

// 사용 예
const events = await getAllDMEvents();
console.log(`Found ${events.length} DM events`);

최대 30일 전까지의 이벤트를 조회할 수 있습니다.

v1.1과의 ID 호환성

대화 및 이벤트 ID는 v1.1과 v2 엔드포인트에서 동일하게 사용됩니다. 이는 다음을 수행할 수 있다는 의미입니다:

v2를 사용해 이벤트를 가져온 후 v1.1을 사용해 특정 메시지를 삭제할 수 있습니다
API 요청에서 x.com URL의 대화 ID를 참조할 수 있습니다

다음 단계

빠른 시작

첫 번째 DM 조회 요청 보내기

DM 보내기

다이렉트 메시지 보내기

API 참조 문서

전체 엔드포인트 설명서

샘플 코드

실행 가능한 코드 예제

개요

포스트

사용자

다이렉트 메시지

좋아요

리스트

Spaces

커뮤니티

커뮤니티 노트

트렌드

뉴스

미디어

X 활동

사용량

스트림 연결

규정 준수

Enterprise v2

좋아요 스트림

GNIP 2.0

통합 가이드

인증

필수 스코프 (OAuth 2.0)

대화 유형

일대일

그룹

이벤트 유형

예시 이벤트

필드와 expansions

기본 필드

사용 가능한 필드

사용 가능한 expansions

expansions 사용 예시

v1.1과의 ID 호환성

다음 단계

빠른 시작

DM 보내기

API 참조 문서

샘플 코드