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

​
인증

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

​
필수 스코프 (OAuth 2.0)

Scope필요한 기능
dm.write메시지 보내기 및 삭제
dm.readdm.write와 함께 필요
tweet.readDM 스코프에 필요
users.readDM 스코프에 필요

​
엔드포인트 개요

MethodEndpointDescription
POST/2/dm_conversations/with/:participant_id/messages일대일 메시지 전송
POST/2/dm_conversations그룹 대화 생성
POST/2/dm_conversations/:dm_conversation_id/messages대화에 메시지 추가
DELETE/2/dm_events/:event_id메시지 삭제

​
메시지 보내기

​
일대일 메시지

특정 사용자에게 메시지를 보냅니다. 기존 대화가 없다면 새 대화를 생성합니다:
cURL
curl -X POST "https://api.x.com/2/dm_conversations/with/9876543210/messages" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello!"}'

​
그룹 대화

새 그룹을 만들고 첫 메시지를 보냅니다:
cURL
curl -X POST "https://api.x.com/2/dm_conversations" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_type": "Group",
    "participant_ids": ["944480690", "906948460078698496"],
    "message": {"text": "Welcome to our group!"}
  }'
conversation_type 필드는 반드시 "Group"으로 설정해야 합니다(대소문자 구분).

​
기존 대화에 추가

참여 중인 대화에 메시지를 보내세요:
cURL
curl -X POST "https://api.x.com/2/dm_conversations/1582103724607971328/messages" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Another message"}'

​
미디어 첨부

메시지당 하나의 미디어(사진, 동영상 또는 GIF)를 첨부할 수 있습니다.
1

미디어 업로드

Media Upload 엔드포인트를 사용해 파일을 업로드하고 media_id를 받습니다.
2

메시지에 포함

{
  "text": "Check out this image!",
  "attachments": [{"media_id": "1583157113245011970"}]
}
  • 인증된 사용자가 해당 미디어를 직접 업로드했어야 합니다.
  • 미디어는 업로드 후 24시간 동안만 사용할 수 있습니다.
  • 메시지당 하나의 첨부만 지원됩니다.

​
포스트 공유

메시지 텍스트에 게시물 URL을 추가하여 해당 게시물을 포함하세요: 
{
  "text": "Have you seen this? https://x.com/XDevelopers/status/1580559079470145536"
}
응답에는 게시물 id가 들어 있는 referenced_tweets 필드가 포함됩니다.

​
메시지 요건

FieldRequiredNotes
text예*첨부 파일이 없을 경우 필수
attachments예*텍스트가 없을 경우 필수
*text 또는 attachments 중 하나 이상은 반드시 제공되어야 합니다.

​
v1.1과의 ID 호환성

대화 및 이벤트 ID는 v1.1과 v2 엔드포인트 간에 공유됩니다. 이를 통해 다음과 같은 하이브리드 워크플로우를 구현할 수 있습니다:
  • v2로 메시지 생성
  • v1.1로 메시지 삭제(아직 v2에서는 지원되지 않음)
  • x.com URL에 포함된 대화 ID 참조

​
오류 처리

Status오류해결 방법
400잘못된 요청요청 본문 형식을 확인하세요
401인증 실패액세스 토큰을 확인하세요
403권한 없음스코프 및 사용자 권한을 확인하세요
429요청 과다대기 후 다시 시도하세요

​
일반적인 문제

수신자가 알지 못하는 사용자로부터 오는 메시지를 차단하도록 DM 설정을 해 두었거나, 귀하를 차단했을 수 있습니다.
같은 인증된 사용자 계정으로 업로드된 미디어인지, 그리고 업로드된 지 24시간이 지나지 않았는지 확인하세요.
모든 참가자 id가 유효한지, 해당 사용자들이 그룹 DM 초대를 허용하는지 확인하세요.

​
다음 단계

빠른 시작

첫 번째 다이렉트 메시지를 보내세요

DM 조회

DM 대화를 조회하세요

미디어 업로드

첨부할 미디어를 업로드하세요

API 참조 문서

전체 엔드포인트 문서