メインコンテンツへスキップ

​
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 をサポートするように更新予定です。  
前提条件このガイドを完了するには、リクエストを認証するためのキーおよびトークン一式が必要です。これらは次の手順で生成できます。

​
ダイレクトメッセージのリクエストを管理する手順

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

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

ダイレクトメッセージ管理用のendpointを使い始めるにあたり、プロセスを簡素化するためにPostmanを使用します。新規ダイレクトメッセージの作成や、ダイレクトメッセージの会話イベントの一覧取得に使う6つのendpointを試すため、XDev作成のX API v2リクエスト例コレクションを利用します。 コレクションの多くは事前に入力されていますが、これらのAPIリクエストを実行するために作成したX Appに基づくいくつかの情報は、あなたが指定する必要があります。まずはコレクションを読み込み・更新しましょう。 X API v2のPostmanコレクションを環境に読み込むには、次のボタンをクリックしてください。
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. “Manage DMs”などのトークン名を作成します。
  2. Grant Type が Authorization Code (with PKCE) に設定されていることを確認します。
  3. Callback URL を設定します。v2 Dev Portal でアプリケーションに設定している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: ダイレクトメッセージの会話参加者とメッセージ内容を指定する

「Body」タブに移動し、サンプルのJSONオブジェクトを更新します。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 が含まれていれば、新しいダイレクトメッセージの会話が正常に作成されています。この会話に関連するイベントを照会し始めるには、ダイレクトメッセージ検索のクイックスタート ガイドに進んでください。

​
ステップ5：そのグループ会話に別のメッセージを追加する

次に「Add DM to conversation」の例を選択し、「Params」タブを開きます。「Path Variables」で、上で作成した会話のIDに合わせて dm_conversation_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"
   }
}
⌘I