メインコンテンツへスキップDirect Messages のエンドポイント v2 では、会話および会話イベントを中核となる X API オブジェクトとして導入し、1 対 1 とグループ会話を区別します。1 対 1 の会話は常に参加者が 2 人のみで、グループ会話は 2 人以上が参加でき、メンバー構成が変化することがあります。
このページでは、Direct Messages のルックアップエンドポイントをシステムに統合する際に把握しておくべき、いくつかのツールと重要な概念について説明します。ページは次の 2 つのセクションで構成されています:
すべてのダイレクトメッセージは、ダイレクトメッセージの会話に属します。会話は1対1またはグループのいずれかです。本ローンチでは、ダイレクトメッセージの作成およびダイレクトメッセージの会話に関連するイベントの取得に必要な基盤的なエンドポイントを提供します。すべての会話には一意の dm_conversation_id があり、その会話を構成する各イベントには一意の dm_event_id が付与されています。
ダイレクトメッセージのルックアップエンドポイントは、会話に関連するイベントを取得する手段を提供します。これらの GET エンドポイントは、会話を構成するメッセージの取得に使用でき、グループ会話では、誰が参加・退出したかを把握する用途にも使用できます。
この初期リリースのダイレクトメッセージルックアップには、3つの GET メソッドが含まれます:
-
GET /2/dm_conversations/with/:participant_id/dm_events - 1対1の会話に関連するダイレクトメッセージイベントを取得します。:participant_id パスパラメータは、このリクエストを送信する認証済みユーザーと会話しているアカウントの数値のユーザーIDです。
-
GET /2/dm_conversations/:dm_conversation_id/dm_events - :dm_conversation_id パスパラメータで指定された特定の会話IDに関連するダイレクトメッセージイベントを取得します。1対1およびグループの会話IDの両方に対応しています。
-
GET /2/dm_events - 認証ユーザーに関連するダイレクトメッセージイベントを、1対1およびグループ会話の両方を含めて取得します。最大30日前までのイベントを利用できます。
これらの GET エンドポイントはすべて、event_types リクエリパラメータを使用して、イベントタイプ別に dm_events を取得することをサポートします。現在、サポートされている会話イベントタイプは3種類です:
-
MessageCreate - 新しいダイレクトメッセージが作成されたときに生成されます。このイベントオブジェクトには、メッセージの時刻とテキスト、送信者のアカウントID、会話IDおよびイベントIDが含まれる場合があります。
-
ParticipantsJoin - 新しい参加者がグループ会話に参加したときに生成されます。この dm_event オブジェクトには、参加者のID、created_at の時刻、および「invite」イベントの sender_id が含まれます。
-
ParticipantsLeave - 参加者が会話から退出したときに生成されます。このイベントオブジェクトには、退出した参加者のIDとイベントの時刻が含まれます。
詳細については、Direct Messages lookup API リファレンスをご覧ください。
v1.1 と v2 間で共有される会話 ID とイベント ID
ダイレクトメッセージのイベント fields と expansions
-
id、event_type、text は MessageCreate イベントのデフォルトです。
-
id、event_type、participant_ids は ParticipantsJoin と ParticipantsLeave イベントのデフォルトです。
-
dm_conversation_id と created_at はすべてのイベントで利用可能です。
-
attachments と referenced_tweets は MessageCreate イベントで利用可能です。
-
sender_id は MessageCreate と ParticipantsJoin イベントで利用可能です。
-
participant_ids は ParticipantsJoin と ParticipantsLeave イベントで利用可能です。
さらに、ダイレクトメッセージのルックアップエンドポイントは次のexpansionsをサポートします:
-
sender_id - メッセージを送信したユーザー、または会話に招待したユーザーに関連付けられた User オブジェクトを展開します。
-
referenced_tweets.id - ダイレクトメッセージのテキストに Post へのリンクが含まれている場合、その Post オブジェクトを展開します。
-
attachments.media_keys - ダイレクトメッセージにメディアの添付が含まれている場合、Media オブジェクトを展開します。
-
participant_ids - グループ会話に参加または退出したユーザーに関連付けられた User オブジェクトを展開します。
expansions には Posts、Users、Media オブジェクトが含まれるため、tweet.fields、user.fields、media.fields のリクエストクエリパラメータも使用できます。詳細は、fields と expansions の使い方ガイドをご覧ください。
以下は、Direct Message の MessageCreate、ParticipantsJoin、ParticipantsLeave イベントタイプの JSON オブジェクト例です。
利用可能な dm_event オブジェクトの fields: id, text, event_type, dm_conversation_id, created_at, sender_id, attachments, referenced_tweets, participant_ids。これらの fields をリクエストで選択する方法の詳細は「Fields and Expansion」セクションを参照してください。
MessageCreate イベントの例:
すべての dm_event の fields を指定した場合、シンプルなテキストの Direct Message に対するレスポンスは次のとおりです:
{ "text": "Hi everyone.", "sender_id": "944480690", "dm_conversation_id": "1578398451921985538", "id": "1582838499983564806", "event_type": "MessageCreate", "created_at": "2022-10-19T20:58:00.000Z" }
ParticipantsJoin イベントの例:
すべての dm_event の fields を指定した場合、参加者が会話に参加した際のレスポンスは次のとおりです:
{ "participant_ids": [ "944480690" ], "sender_id": "17200003", "dm_conversation_id": "1578398451921985538", "id": "1582835469712138240", "event_type": "ParticipantsJoin", "created_at": "2022-10-19T20:45:58.000Z" }
ParticipantsLeave イベントの例:
すべての dm_event の fields を指定した場合、参加者が会話から退出した際のレスポンスは次のとおりです:
{ "participant_ids": [ "944480690" ], "dm_conversation_id": "1578398451921985538", "id": "1582838535115067392", "event_type": "ParticipantsLeave", "created_at": "2022-10-19T20:58:09.000Z" }
すべての X API v2 エンドポイントでは、キーやトークンとも呼ばれる認証情報を用いてリクエストを認証する必要があります。Direct Message はすべて非公開であり、アクセスにはユーザーによる許可が必要です。
これらの Direct Message エンドポイントは OAuth 2.0 Authorization Flow with PKCE または 1.0a User Context の利用が必要です。つまり、リクエストを成功させるには API キー一式とユーザーの Access Token を使用する必要があります。Access Token は、あなたが代理でリクエストする対象のユーザーに紐づいている必要があります。別のユーザーの Access Token を生成する場合は、そのユーザーが 3-legged OAuth flow を使用してあなたのアプリを許可または認証する必要があります。
OAuth のユーザーコンテキストは扱いが難しい場合があります。この認証方式に不慣れな場合は、ライブラリ や Postman などのツールを使用して、リクエストを正しく認証することをおすすめします。
OAuth 2.0 Authorization Code with PKCE は、アプリケーションのスコープをより厳密に制御でき、複数デバイス間での認可フローも可能にします。OAuth 2.0 では、ユーザーに代わって特定の権限を付与する細かなスコープを選択できます。Direct Message の lookup エンドポイントには次のスコープが必要です: dm.read, post.read, user.read
アプリで OAuth 2.0 を有効化するには、開発者ポータルの App settings セクション内にあるアプリの認証設定で有効にしてください。
X API v2 のエンドポイントで使用できる認証情報一式を取得するには、承認済みの開発者アカウントを保有し、そのアカウント内でプロジェクトを作成し、さらにそのプロジェクト内に開発者アプリを作成する必要があります。キーとトークンは、作成した開発者アプリ内で確認できます。
毎日、何千人もの開発者が X API にリクエストを送信しています。こうした大量のリクエストを適切に管理するため、各エンドポイントにはレート制限が設けられており、アプリや認証済みユーザーに代わって行えるリクエスト数が制限されています。
Direct Message のルックアップエンドポイントはユーザーレベルでレート制限されています。つまり、あなたが代わってリクエストを送信する認証済みユーザーは、あなたの X アプリを通じて一定数までしかリクエストできません。GET メソッドには、15 分あたり 300 リクエストというユーザー単位のレート制限があります。これらのレート制限は GET エンドポイント間で共有されます。
これらのエンドポイントは、レスポンスを迅速に返すためにページネーションを利用します。単一のレスポンスで送信できる結果（最大100件のイベント）を超える場合は、ページネーションが必要です。1ページあたりに返す件数を指定するには max_results パラメータを、次ページの結果を取得するには pagination_token パラメータを使用します。詳しくはページネーションガイドをご確認ください。
便利なツール
Direct Messages のルックアップエンドポイントを利用する際に、ぜひ活用していただきたいツールをご紹介します。
Postman
Postman はエンドポイントの検証に最適なツールです。各 Postman リクエストには、利用可能な項目を素早く把握できるよう、すべてのパスおよびボディパラメータが含まれています。Postman コレクションの詳細は、Using Postmanをご覧ください。
コードサンプル
v2 Direct Messages エンドポイント向けの Python サンプルコードは、X API v2 sample code GitHub リポジトリで提供しています。“Manage-Direct-Messages” フォルダには POST メソッドの例が、“Direct-Messages-lookup” フォルダには GET メソッドの例が含まれています。
XDev Software Development Kits (SDKs)
これらのライブラリは v2 Direct Messages エンドポイントに対応するよう更新中で、まもなく利用可能になる予定です。
サードパーティライブラリ
コミュニティによって開発されたサードパーティライブラリが増えています。これらのライブラリは導入を支援するために設計されており、いくつかは近く v2 Direct Messages エンドポイントをサポートする予定です。適切なバージョンタグを確認することで、v2 エンドポイントで動作するライブラリを見つけられます。 
