クイックスタート

​

ダイレクトメッセージ管理エンドポイントのはじめ方

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

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

前提条件

このガイドを完了するには、リクエストを認証するための keys and tokens が必要です。以下の手順に従うことで、これらのキーとトークンを生成できます。

• 開発者アカウントにサインアップし、承認を受ける。
• 開発者ポータルで Project と、それに関連付けられた 開発者アプリ を作成する。
• アプリの「Keys and tokens」ページに移動し、必要なクレデンシャルを生成する。すべてのクレデンシャルは安全な場所に保存してください。

​

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

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

​

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

Direct Message 管理用エンドポイントの操作を始めるにあたり、手順を簡素化するために Postman を使用します。X Developers が作成した X API v2 リクエストのサンプルコレクションを使って、新しい Direct Message の作成や Direct Message の会話イベントの一覧取得に用いる6つのエンドポイントを確認します。

コレクションの多くはあらかじめ入力済みですが、これらの API リクエストを実行するために用意した X アプリに基づいて、いくつかの情報を入力する必要があります。まずはコレクションを読み込む／更新しましょう。

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

X API v2 を Postman に追加

Postman に X API v2 コレクションを読み込んだら、「Manage Direct Messages」フォルダに移動します。このフォルダの Authorization タブは可能な限り事前入力されています。X アプリの認証情報を使用できるよう、いくつかの設定を更新してください。

このフォルダには、新しい Direct Message を作成するための3つのエンドポイントも含まれています。なお、送受信メッセージや参加者の参加・退出など、Direct Message の会話イベントを取得できる3つのエンドポイントを収めた「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 アプリでは、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：ダイレクトメッセージの会話イベントを取得する

このエンドポイントでダイレクトメッセージの会話イベントを取得するには、会話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」ボタンをクリックすると、レスポンスにはデフォルトのダイレクトメッセージオブジェクトの 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"
   }
}