통합 가이드

다이렉트 메시지 전송을 위한 핵심 개념 및 모범 사례

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

---

인증

DM 엔드포인트에는 사용자 인증이 필요합니다:

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

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

필수 스코프 (OAuth 2.0)

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

---

엔드포인트 개요

Method	Endpoint	Description
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

shellscript

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

shellscript

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

shellscript

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 필드가 포함됩니다.

---

메시지 요건

Field	Required	Notes
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 참조 문서

전체 엔드포인트 문서