クイックスタート

​

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

このクイックスタートガイドでは、HTTP リクエストの作成・管理ツールである Postman を使って、ダイレクトメッセージエンドポイントへの最初のリクエストを実行する手順を説明します。Postman コレクションの詳細は、Postman の使用 ガイドをご覧ください。

Python の例を確認したい場合は、X API v2 サンプルコード の GitHub リポジトリをご覧ください。加えて、公式の X Developer Platform software development kits (SDKs) も、これらのダイレクトメッセージエンドポイントに対応するよう順次更新されます。

前提条件

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

• developer account に登録 し、承認を受ける。
• 開発者ポータルで Project と、関連付けられた developer App を作成する。
• アプリの “Keys and tokens” ページに移動して、必要なクレデンシャルを生成する。すべてのクレデンシャルは安全な場所に保管する。

​

Direct Message リクエストの管理を構築する手順

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

​

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

Manage Direct Message エンドポイントの操作を始めるにあたり、手順を簡素化するために Postman を使用します。XDev が作成した 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 lookup」フォルダには、送受信メッセージや会話参加者の参加・離脱を含む Direct Message の会話イベントを取得するための3つのエンドポイントもあります。 

グループ会話の作成は 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 を設定します。Callback URL は、v2 Dev Portal のアプリケーションに登録されている 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：ダイレクトメッセージの会話参加者とメッセージ内容を指定する

「Body」タブに移動し、例の JSON オブジェクトを更新します。participant_ids 属性に、ダイレクトメッセージを送信したいアカウントを設定します。

{ "message": {"text": "あなたたち2人へ。これは新しいグループ会話です。"}, "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」で、上で作成した会話のIDに合わせて dm_conversation_id を更新します。

Key	Value
dm_conversation_id	1582103724607971328

この会話IDを使用すると、リクエストパスは次のようになります: https://api.x.com/2/dm_conversations/1582103724607971328/messages

また、送信したいメッセージ本文のテキストを含むリクエストJSONを用意し、「Body」タブも更新します。

{
   "text": "グループ会話に新しいメッセージを追加中です…"
}

セットアップが完了したら「Send」ボタンをクリックすると、次の例と同様のレスポンスが返ってきます。

{
   "data": {
       "dm_conversation_id": "1582103724607971328",
       "dm_event_id": "1582106224379559940"
   }
}