クイックスタート

​

Direct Message 管理用 endpoint の利用を開始する

このクイックスタート ガイドでは、HTTP リクエストの作成・管理ツールである Postman を使って、Direct Message の endpoint へ最初のリクエストを送信する方法を説明します。Postman コレクションの詳細は、Using Postman ガイドをご覧ください。

Python ベースのサンプルを確認したい場合は、X API v2 sample code の GitHub リポジトリをご覧ください。加えて、公式の X Developer Platform software development kits (SDKs) も、これらの Direct Message endpoint をサポートするように順次更新されます。  

前提条件

このガイドを完了するには、リクエストの認証に使用する一連の keys and tokens が必要です。以下の手順に従って、これらのキーおよびトークンを生成できます。

• デベロッパーアカウントに登録 し、承認を受けます。
• developer portal で Project を作成し、関連付けられた 開発者用 App を作成します。
• App の「Keys and tokens」ページに移動して、必要な認証情報を生成します。すべての認証情報は安全な場所に保存してください。

​

ダイレクトメッセージのルックアップリクエストを作成する手順

この例では、1 回のリクエストで新しいグループ会話を作成し、最初のメッセージを追加します。続いて、作成した会話に 2 件目のメッセージを追加します。

​

ステップ1: ツールまたはライブラリから始める

ダイレクトメッセージ管理用の endpoint を使い始めるにあたり、手順を簡素化するために Postman を使用します。XDevelopers が作成した X API v2 リクエストのサンプルコレクションを用いて、新規ダイレクトメッセージの作成やダイレクトメッセージの会話イベントの一覧取得に使う6つの endpoint を確認します。

コレクションの大部分は事前に入力されていますが、これらの API リクエストを実行するために作成した X App に基づいて、いくつかご自身で設定すべき項目があります。まずはコレクションを読み込み/更新しましょう。

X API v2 の Postman コレクションを環境に読み込むには、次のボタンをクリックしてください。

Postman に X API v2 を追加

Postman に X API v2 のコレクションを読み込んだら、「Manage Direct Messages」フォルダーに移動します。このフォルダーの Authorization タブは可能な限り事前入力されています。X App の認証情報を適用するため、いくつかの設定を更新する必要があります。

このフォルダーには、新規ダイレクトメッセージを作成するための3つの endpoint も含まれています。なお、送受信メッセージや会話参加者の参加・離脱などのダイレクトメッセージ会話イベントを取得できる3つの endpoint を含む「Direct Message lookup」フォルダーもあります。

グループ会話の作成は X API v2 の新機能のため、この例ではそこに焦点を当てます。「New group DM and conversation」の例を使用します。このリクエストでダイレクトメッセージのグループ会話を作成します。

次のステップは、endpoint で認証することです。

​

ステップ2：リクエストを認証する

X API に正しくリクエストするには、その権限があることを確認する必要があります。この endpoint に正常にリクエストするために、OAuth 2.0 Authorization Code Flow with PKCE を使用します。access token は 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 - 機密クライアントの 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：ダイレクトメッセージの会話イベントを取得する

この endpoint を使用してダイレクトメッセージの会話イベントを取得するには、会話の ID を指定する必要があります。会話 ID は endpoint のパスの一部です: https://api.x.com/2/dm_conversations/:dm_conversation_id/dm_events

Postman で「Params」タブに移動し、取得したい会話の ID を「Path Variables」セクションに入力します。

設定は次のとおりです:

Key	Value
dm_conversation_id	1228393702244134912

この会話を指定すると、最終的なパスは https://api.x.com/2/dm_conversations/1582103724607971328/dm_events になります。

「Send」ボタンをクリックすると、レスポンスにはデフォルトのダイレクトメッセージオブジェクトの fields として id、text、event_type が含まれます。また、結果数を示す「meta」オブジェクトに加え、利用可能な場合はさらなるイベント取得に使用されるページネーショントークンも含まれます。

{
   "data": [
       {
           "event_type": "MessageCreate",
           "id": "1580705921830768647",
           "text": "お二人ともこんにちは。新しいグループ会話を開始しました。"
       }
   ],
   "meta": {
       "result_count": 1,
       "next_token": "18LAA5FFPEKJA52G0G00ZZZZ",
       "previous_token": "1BLC45FFPEKJA52G0S00ZZZZ"
   }
}

追加の fields を取得するには、リクエストで field および/または expansion パラメータを使って、それらの fields を指定する必要があります。

この演習では、dm_event オブジェクトの追加の fields セットをリクエストします:

1. 既定の Direct Message オブジェクトの fields（id、text、event_type）

2. 追加の Direct Message オブジェクトの fields：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 の fields が含まれています。

{
   "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"
   }
}