메인 콘텐츠로 건너뛰기
v2 Direct Messages 엔드포인트는 대화와 대화 이벤트를 핵심 X API 객체로 도입하고, 일대일 대화와 그룹 대화를 구분합니다. 일대일 대화에는 항상 정확히 두 명의 참가자만 있으며, 그룹 대화에는 두 명 이상이 참여할 수 있고 멤버 구성이 변경될 수 있습니다.    이 페이지에는 시스템에 Manage Direct Messages 엔드포인트를 통합할 때 알아두어야 할 여러 도구와 핵심 개념에 대한 정보가 포함되어 있습니다. 이 페이지는 두 개의 섹션으로 구성되어 있습니다: 핵심 개념

​
다이렉트 메시지 대화

모든 다이렉트 메시지는 다이렉트 메시지 대화에 포함됩니다. 이러한 대화는 1:1 대화 또는 그룹 대화일 수 있습니다. 이번 릴리스에서는 다이렉트 메시지를 생성하고 다이렉트 메시지 대화와 관련된 이벤트를 조회하는 데 필요한 기본 엔드포인트를 제공합니다. 모든 대화에는 고유한 dm_conversation_id가 있으며, 해당 대화를 구성하는 모든 이벤트에는 고유한 dm_event_id가 있습니다.   Manage Direct Message 엔드포인트는 새 메시지를 생성하고 대화에 추가하기 위한 세 가지 POST 메서드를 제공합니다:
  • POST /2/dm_conversations/with/:participant_id/messages - 1:1 다이렉트 메시지를 생성합니다. 이 메서드는 메시지를 기존 1:1 대화에 추가하거나 새 대화를 생성합니다. :participant_id 경로 매개변수는 메시지를 받는 계정의 사용자 ID입니다.  다음은 1:1 다이렉트 메시지를 보내기 위한 JSON 요청 본문 예시입니다:
{
   "text": "안녕하세요, 당신에게 보내는 메시지입니다. 이전에 메시지를 주고받은 적이 없다면 새 대화로 표시되고, 있다면 기존 스레드에 추가됩니다. "
}
  • POST /2/dm_conversations - 새 그룹 대화를 생성하고 해당 대화에 다이렉트 메시지를 추가합니다. 이 요청에는 대화 참가자 목록이 필요합니다. 동일한 참가자 목록으로 여러 대화를 생성할 수 있습니다. 이 요청은 항상 새 대화 ID를 반환합니다. 아래는 새 그룹 대화를 생성하고 다이렉트 메시지를 추가하기 위한 JSON 요청 본문 예시입니다. 이때 “conversation_type” 필드가 필요하며 반드시 “Group”(대/소문자 구분)으로 설정해야 합니다.
{
   "message": {"text": "너희 둘만을 위한 인사입니다. 새로운 그룹 대화예요."},
   "participant_ids": ["944480690","906948460078698496"],
   "conversation_type": "Group"
}
  • POST /2/dm_conversations/:dm_conversation_id/messages - 다이렉트 메시지를 생성하여 기존 대화에 추가합니다. :dm_conversation_id 경로 매개변수는 메시지가 추가될 대화의 ID입니다. 이 메서드는 일대일 및 그룹 대화 모두에 메시지를 추가하는 데 사용할 수 있습니다. 다음은 일대일 및 그룹 대화에 다이렉트 메시지를 보낼 때 사용하는 JSON 요청 본문 예시입니다:
{
   "text": "새 메시지가 도착했습니다."
}
이 POST 메서드는 단일 미디어를 첨부하는 기능을 지원합니다. POST 요청 본문에는 “text”와 “attachments” 필드 중 하나 이상이 포함되어야 합니다. “attachments” 필드가 없으면 “text” 속성이 필요하고, “text” 필드가 없으면 “attachments” 필드가 필요합니다. 자세한 내용은 다음 섹션을 참조하세요. 자세한 내용은 Manage Direct Messages API References를 참조하세요.

​
v1.1 및 v2에서 공유되는 대화 및 이벤트 ID

X Platform의 v1.1과 v2에서는 대화 및 이벤트 ID가 공유됩니다. 따라서 두 버전을 함께 사용할 수 있습니다. 예를 들어, Direct Messages v1.1 엔드포인트에는 단일 이벤트를 반환하거나 이벤트를 삭제하는 메서드가 있습니다. 이러한 메서드는 아직 v2에는 제공되지 않습니다. ID가 v1.1과 v2에서 공통이므로, v2에서 제공된 ID를 바탕으로 v1.1 요청을 보내거나 X 애플리케이션의 대화 URL에 표시되는 대화 ID를 참조할 수 있습니다.  

​
미디어 첨부 및 게시물 참조

Manage Direct Message 엔드포인트는 모두 단일 미디어(사진, 동영상 또는 GIF) 첨부를 지원합니다. 미디어를 첨부하려면 v1.1 Upload media 엔드포인트에서 생성된 미디어 ID가 필요합니다. Direct Message를 게시하는 인증된 사용자는 해당 미디어를 직접 업로드했어야 합니다. 업로드가 완료되면 해당 미디어는 메시지에 포함할 수 있도록 24시간 동안 사용 가능합니다. 미디어 포함 방법을 보여주기 위해 다음은 JSON 요청 본문 예시입니다: 
{
 "text": "사진을 첨부합니다...",
 "attachments": [{"media_id": "1583157113245011970}]
}
결과로 생성된 MessageCreate 이벤트에는 다음 메타데이터가 포함됩니다. 
{
    "attachments": {
        "media_keys": [
            "5_1583157113245011970"
        ]
    }
}
메시지 텍스트에 게시물 URL을 넣어 게시물을 포함할 수도 있습니다. 메시지에 게시물을 포함하는 방법을 보여주기 위해 다음은 JSON 요청 본문의 예시입니다: 
{
 "text": "제가 말씀드린 게시물은 다음과 같습니다: https://x.com/SnowBotDev/status/1580559079470145536"
}
생성된 MessageCreate 이벤트에는 다음 메타데이터가 포함됩니다. 
{
    "referenced_tweets": [
        {
            "id": "1580559079470145536"
        }
    ]
}

​
인증

모든 X API v2 엔드포인트는 요청을 인증하기 위한 자격 증명(‘키와 토큰’)이 필요합니다. 모든 다이렉트 메시지는 비공개이며, 접근하려면 사용자 인가가 필요합니다. 이 다이렉트 메시지 엔드포인트는 OAuth 2.0 Authorization Flow with PKCE 또는 1.0a User Context를 사용해야 합니다. 즉, 성공적인 요청을 위해 API 키와 사용자 액세스 토큰을 함께 사용해야 합니다. 액세스 토큰은 여러분이 대신 요청하는 해당 사용자와 연결되어 있어야 합니다. 다른 사용자의 액세스 토큰 세트를 생성하려면, 그 사용자가 3-legged OAuth 플로우를 통해 여러분의 앱을 승인(또는 인증)해야 합니다. OAuth 사용자 컨텍스트는 다소 까다로울 수 있습니다. 이 인증 방식에 익숙하지 않다면, 라이브러리나 Postman 같은 도구를 사용해 요청을 올바르게 인증할 것을 권장합니다. OAuth 2.0 Authorization Code with PKCE는 애플리케이션의 스코프와 여러 기기에 걸친 인가 플로우를 더 세밀하게 제어할 수 있게 합니다. OAuth 2.0은 세분화된 특정 스코프를 선택해 사용자 대신 특정 권한을 부여하도록 합니다. 다이렉트 메시지 조회 엔드포인트에는 다음 스코프가 필요합니다: dm.write, dm.read, tweet.read, user.read. 앱에서 OAuth 2.0을 사용하려면, 개발자 포털의 앱 설정 섹션에 있는 앱의 인증 설정에서 이를 활성화해야 합니다.

​
개발자 포털, 프로젝트, 및 Developer 앱

X API v2 엔드포인트와 함께 사용할 인증 자격 증명 세트를 받으려면 승인된 개발자 계정을 보유하고, 해당 계정 내에 프로젝트를 설정한 뒤, 그 프로젝트 내에 Developer 앱을 생성해야 합니다. 그런 다음 Developer 앱에서 키와 토큰을 확인할 수 있습니다. 

​
요청 한도

매일 수천 명의 개발자가 X API에 요청을 보냅니다. 이러한 방대한 요청량을 관리하기 위해 각 엔드포인트에는 앱 또는 인증된 사용자를 대신하여 수행할 수 있는 요청 수를 제한하는 요청 한도가 적용됩니다. 다이렉트 메시지 관리 엔드포인트는 사용자별 및 X 앱 수준 모두에서 요청 한도가 적용됩니다. 즉, 요청을 대신하는 인증된 사용자는 해당 X 앱으로 특정 수의 메시지만 보낼 수 있습니다. 또한 X 앱이 보낼 수 있는 다이렉트 메시지의 일일 한도도 있습니다. POST 메서드의 경우 15분당 200개의 요청/메시지라는 사용자 요청 한도가 있습니다. 사용자는 또한 24시간당 1,000개의 다이렉트 메시지로 제한됩니다. 또한 X 앱은 24시간당 15,000개의 메시지 한도가 있습니다. 이러한 요청 한도는 POST 엔드포인트 전체에서 공유됩니다. 유용한 도구 다이렉트 메시지 조회 엔드포인트를 사용할 때 활용해 볼 것을 권장하는 몇 가지 유용한 도구는 다음과 같습니다: Postman Postman은 엔드포인트를 테스트하는 데 사용할 수 있는 훌륭한 도구입니다. 각 Postman 요청에는 모든 경로 및 본문 매개변수가 포함되어 있어 사용 가능한 항목을 빠르게 파악할 수 있습니다. Postman 컬렉션에 대한 자세한 내용은 Postman 사용하기 페이지를 참조하세요. 코드 샘플 v2 다이렉트 메시지 엔드포인트에 대한 Python 샘플 코드는 X API v2 샘플 코드 GitHub 저장소에서 확인할 수 있습니다. “Manage-Direct-Messages” 폴더에는 POST 메서드 예제가 포함되어 있으며, “Direct-Messages-lookup” 폴더에는 GET 메서드 예제가 포함되어 있습니다. XDev 소프트웨어 개발 키트(SDK) 다음 라이브러리는 v2 다이렉트 메시지 엔드포인트를 위해 업데이트 중이며 곧 준비될 예정입니다: 서드파티 라이브러리 커뮤니티에서 개발한 서드파티 라이브러리가 점점 늘어나고 있습니다. 이러한 라이브러리는 시작하는 데 도움이 되도록 설계되었으며, 여러 라이브러리가 곧 v2 다이렉트 메시지 엔드포인트를 지원할 것으로 예상됩니다. 적절한 버전 태그를 확인하여 v2 엔드포인트와 호환되는 라이브러리를 찾을 수 있습니다.