메인 콘텐츠로 건너뛰기

​
Direct Message 엔드포인트 관리 시작하기

이 빠른 시작 가이드는 HTTP 요청을 관리하고 실행하는 도구인 Postman을 사용해 Direct Message 엔드포인트에 첫 요청을 보내는 방법을 안내합니다. Postman 컬렉션에 대해 더 알아보려면 Postman 사용법 가이드를 방문하세요. Python 기반 예제를 살펴보려면 X API v2 샘플 코드 GitHub 저장소를 방문하세요. 또한 공식 X Developer Platform 소프트웨어 개발 키트(SDK)는 이러한 Direct Message 엔드포인트를 지원하도록 업데이트될 예정입니다.  
사전 준비 사항이 가이드를 완료하려면 요청을 인증하기 위한 키와 토큰 세트가 필요합니다. 다음 단계에 따라 키와 토큰을 생성할 수 있습니다:
  • 개발자 계정에 가입하고 승인을 받으세요.
  • 개발자 포털에서 Project와 연결된 Developer 앱을 생성하세요.
  • 앱의 “Keys and tokens” 페이지로 이동해 필요한 자격 증명을 생성합니다. 모든 자격 증명은 안전한 위치에 저장하세요.

​
Direct Message 관리 요청 빌드 단계

이 예제에서는 단일 요청으로 새 그룹 대화를 만들고 그 대화에 첫 번째 메시지를 추가합니다. 그런 다음 생성된 대화에 두 번째 메시지를 추가합니다.

​
1단계: 도구 또는 라이브러리로 시작하기

Direct Message 관리 엔드포인트로 작업을 시작하기 위해 프로세스를 단순화할 수 있는 Postman 도구를 사용하겠습니다. XDev에서 작성한 X API v2 예시 요청 컬렉션을 활용해, 새로운 Direct Message를 생성하고 Direct Message 대화 이벤트를 나열하는 데 사용되는 여섯 개의 엔드포인트를 살펴보겠습니다. 컬렉션의 대부분은 미리 채워져 있지만, 이 API 요청을 실행하기 위해 생성한 X App을 기준으로 몇 가지 세부 정보를 직접 입력해야 합니다. 먼저 컬렉션을 로드/업데이트하겠습니다. X API v2 Postman 컬렉션을 환경에 로드하려면 다음 버튼을 클릭하세요:
Postman에서 X API v2 컬렉션을 로드했다면 “Manage Direct Messages” 폴더로 이동하세요. 이 폴더의 Authorization 탭은 가능한 범위에서 미리 구성되어 있으며, 몇 가지 설정을 업데이트해 X App의 인증 정보를 반영할 수 있습니다. 이 폴더에는 새로운 Direct Message를 생성하기 위한 세 개의 엔드포인트도 포함되어 있습니다. 또한 메시지 송수신, 대화 참가자의 참여 및 퇴장 시점 등을 포함하여 Direct Message 대화 이벤트를 조회할 수 있는 세 개의 엔드포인트가 있는 “Direct Message lookup” 폴더도 있습니다.  그룹 대화 생성은 X API v2의 흥미로운 신규 기능이므로, 이 예시는 이에 초점을 맞추겠습니다. 우리는 “New group DM and conversation” 예시로 작업할 것입니다. 이 요청을 사용해 Direct Message 그룹 대화를 생성합니다. 다음 단계는 엔드포인트에 대한 인증입니다. 2단계: 요청 인증 X API에 올바르게 요청하려면 해당 권한이 있는지 확인해야 합니다. 이 엔드포인트에 성공적으로 요청하기 위해 OAuth 2.0 Authorization Code Flow with PKCE를 사용할 것입니다. Postman 내에서 액세스 토큰을 생성할 수 있습니다.  Postman에서는 폴더 또는 요청 수준에서 인증 방법을 설정할 수 있습니다. 여기서는 폴더 수준에서 인증 정보를 구성하겠습니다. “Manage Direct Messages” 폴더로 이동해 “Authorization” 탭을 선택하고, Type이 “OAuth 2.0”으로 설정되어 있는지, “Add auth data to”가 “Request Headers”로 설정되어 있는지 확인하세요. “Current Token” 섹션에서 “header Prefix”가 Bearer로 설정되어 있는지 확인하세요.   새 토큰을 구성하고 생성하려면:
  1. “Manage DMs.”와 같은 토큰 이름을 지정합니다.
  2. Grant Type이 Authorization Code (with PKCE)로 설정되어 있는지 확인합니다.
  3. Callback URL을 설정합니다. v2 Dev Portal에 있는 애플리케이션의 Callback URL과 정확히 일치하도록 Callback URL을 업데이트해야 합니다. 이 예시에 사용된 X App의 경우 Callback URL은 - https://www.example.com. 로 설정되어 있습니다. (정확히 일치해야 하므로 https://example.com은 작동하지 않습니다.) 
  4. Auth URL이 https://x.com/i/oauth2/authorize로 설정되어 있는지 확인합니다.
  5. Access Token URL이 https://api.x.com/2/oauth2/token.Client ID - 개발자 포털에서 OAuth 2.0 client ID를 복사해 붙여넣습니다. Client Secret - 기밀 클라이언트 유형의 App을 사용하는 경우에만 필요합니다. 해당하는 경우 개발자 포털에서 OAuth 2.0 Client Secret을 복사해 붙여넣습니다. 
  6. Scope가 dm.read, dm.write, tweet.read, users.read로 설정되어 있는지 확인합니다.
  7. State가 “state.”로 설정되어 있는지 확인합니다.
  8. Client Authentication이 Send as Basic Auth header로 설정되어 있는지 확인합니다.
  9. Get New Access Token을 클릭하고, “Sign-in with X” 과정에서 “Authorize app”을 클릭합니다.
  10. “Proceed” 버튼을 클릭한 다음 “Use Token”을 클릭해 토큰을 적용합니다. 
  11. “Save” 버튼을 클릭해 이 구성 정보를 저장합니다.
X에 로그인되어 있지 않다는 메시지가 표시될 수 있습니다. 이 오류가 발생하면 Postman 내에서 게시를 진행하려는 해당 X 계정으로 로그인해야 합니다. 이제 OAuth 2.0 상세 설정이 폴더 수준에 적용되었으므로, 각 예제로 이동해 “Authorization” 탭에서 Type이 “Inherit auth from parent.”로 설정되어 있는지 확인하세요.  이 토큰은 곧 만료되므로 “Get New Access Token” 버튼을 클릭해 다시 발급받아야 합니다. 클릭하면 “Sign-in with X” 절차가 시작되고, 요청에 사용할 새 토큰이 발급됩니다.

​
3단계: 다이렉트 메시지 대화 참가자와 메시지 내용을 지정하기

“Body” 탭으로 이동해 예시 JSON 객체를 수정하세요. 다이렉트 메시지를 보낼 계정의 id를 participant_ids 속성에 설정하세요. { "message": {"text": "Hello to just you two, this is a new group conversation."}, "participant_ids": ["944480690","906948460078698496"], "conversation_type": "Group" }

​
4단계: 요청 보내기와 응답 검토

모든 설정이 완료되면 “Send” 버튼을 눌러 주세요. 아래 예시와 유사한 응답을 받게 됩니다. 위에서 토큰을 생성한 이후 만료되었다면, 폴더의 Authorization 탭으로 돌아가 “Get New Access Token”을 클릭하여 새 토큰을 발급받으세요. 
{
   "data": {
       "dm_conversation_id": "1582103724607971328",
       "dm_event_id": "1582103724607971332"
   }
}
반환된 응답의 “data” 객체에 dm_conversation_id와 dm_event_id가 포함되어 있다면, 새 다이렉트 메시지 대화를 성공적으로 생성한 것입니다. 이 대화와 관련된 이벤트를 조회하려면 Direct Message 조회 빠른 시작 가이드를 참조하세요.

​
5단계: 해당 그룹 대화에 메시지를 하나 더 추가하기

이제 “Add DM to conversation” 예제를 선택한 다음 “Params” 탭을 선택하세요. “Path Variables”에서 dm_conversation_id를 위에서 만든 대화의 ID로 업데이트하세요.
KeyValue
dm_conversation_id1582103724607971328
이 대화 ID를 사용하면 요청 경로는 다음과 같이 구성됩니다: https://api.x.com/2/dm_conversations/1582103724607971328/messages 또한 보내려는 메시지 텍스트를 포함한 요청 JSON으로 “Body” 탭을 업데이트하세요. 
{
   "text": "그룹 대화에 새 메시지 추가 중..."
}
모든 설정을 마쳤다면 “Send” 버튼을 눌러 주세요. 그러면 아래 예시와 유사한 응답을 받게 됩니다: 
{
   "data": {
       "dm_conversation_id": "1582103724607971328",
       "dm_event_id": "1582106224379559940"
   }
}