빠른 시작

​

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 도구를 사용하겠습니다. XDevelopers가 작성한 X API v2 요청 예제 컬렉션을 활용하여, 새로운 Direct Message를 생성하고 Direct Message 대화 이벤트를 나열하는 데 사용되는 여섯 개의 엔드포인트를 살펴보겠습니다.

컬렉션 대부분은 미리 구성되어 있지만, 이 API 요청을 실행할 X App을 기준으로 입력해야 하는 몇 가지 세부 정보가 있습니다. 먼저 컬렉션을 로드/업데이트하겠습니다.

X API v2 Postman 컬렉션을 환경에 로드하려면 다음 버튼을 클릭하세요:

Postman에 X API v2 추가

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. “DM lookup”과 같은 토큰 이름을 지정합니다.

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 - Developer Portal에서 OAuth 2.0 Client ID를 복사해 붙여넣습니다. Client Secret - 비공개 클라이언트(confidential client) 유형의 App을 사용하는 경우에만 필요합니다. 해당하는 경우 Developer Portal에서 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단계: 다이렉트 메시지 대화 이벤트 가져오기

이 엔드포인트로 다이렉트 메시지 대화 이벤트를 조회하려면 대화 ID를 지정해야 합니다. 대화 ID는 엔드포인트 경로의 일부입니다: https://api.x.com/2/dm_conversations/:dm_conversation_id/dm_events

Postman에서 “Params” 탭으로 이동한 뒤 “Path Variables” 섹션에 이벤트를 조회할 대화의 ID를 입력합니다.

설정은 다음과 같습니다:

Key	Value
dm_conversation_id	1228393702244134912

이 대화를 지정하면 최종 경로는 https://api.x.com/2/dm_conversations/1582103724607971328/dm_events 가 됩니다.

“Send” 버튼을 클릭하면 응답에 기본 다이렉트 메시지 오브젝트 필드인 id, text, event_type이 반환됩니다. 또한 결과 수와, 가능한 경우 추가 이벤트 조회에 사용되는 페이지네이션 토큰이 포함된 “meta” 오브젝트도 함께 제공됩니다.

{
   "data": [
       {
           "event_type": "MessageCreate",
           "id": "1580705921830768647",
           "text": "두 분 모두 안녕하세요, 새로운 그룹 대화입니다."
       }
   ],
   "meta": {
       "result_count": 1,
       "next_token": "18LAA5FFPEKJA52G0G00ZZZZ",
       "previous_token": "1BLC45FFPEKJA52G0S00ZZZZ"
   }
}

추가 필드를 받으려면 요청에서 field 및/또는 expansion 매개변수를 사용해 해당 필드를 지정해야 합니다.

이 실습에서는 dm_event 객체에 대해 다음과 같은 추가 필드 집합을 요청합니다:

1. 기본 Direct Message 객체 필드: id, text, event_type

2. 추가 Direct Message 객체 필드: dm_conversation_id, created_at, sender_id, attachments, participant_ids, referenced_tweets

Postman에서 “Params” 탭으로 이동한 뒤 “Query Params” 표에 다음 키:값 쌍을 추가하세요:

Key	Value
dm_event.fields	dm_conversation_id,created_at,sender_id,attachments,participant_ids,referenced_tweets

이제 “Send” 버튼 옆에 다음 URL이 표시됩니다:

https://api.x.com/2/dm_conversations/:dm_conversation_id/dm_events?dm_event.fields=id,text,event_type,dm_conversation_id,created_at,sender_id,attachments,participant_ids,referenced_tweets

​

4단계: 요청을 보내고 응답을 검토하기

모든 설정을 마쳤다면 “Send” 버튼을 다시 클릭하세요. 아래 예시와 유사한 응답을 받게 됩니다. 이 응답에는 사용 가능한 모든 dm_event 필드가 포함되어 있다는 점에 유의하세요.

{
   "data": [
       {
           "text": "두 분께 안녕하세요, 새로운 그룹 대화입니다.",
           "id": "1580705921830768647",
           "dm_conversation_id": "1580705921830768643",
           "event_type": "MessageCreate",
           "sender_id": "17200003",
           "created_at": "2022-10-13T23:43:54.000Z"
       }
   ],
   "meta": {
       "result_count": 1,
       "next_token": "18LAA5FFPEKJA52G0G00ZZZZ",
       "previous_token": "1BLC45FFPEKJA52G0S00ZZZZ"
   }
}