メインコンテンツへスキップ
ダイレクトメッセージの endpoint v2 では、会話および会話イベントを中核的な X API のオブジェクトとして導入し、1 対 1 とグループ会話を区別します。1 対 1 の会話には常に 2 人、かつ 2 人のみの参加者が存在し、グループ会話には 2 人以上が参加でき、メンバーシップは変動する可能性があります。    このページでは、ダイレクトメッセージの lookup endpoint をシステムに統合する際に把握しておくべき複数のツールと主要概念について説明します。ページは次の 2 セクションで構成されています:

​
重要な概念

​
ダイレクトメッセージの会話

すべてのダイレクトメッセージは、ダイレクトメッセージの会話に含まれます。会話は1対1またはグループのいずれかです。本リリースでは、ダイレクトメッセージの作成と、ダイレクトメッセージの会話に関連するイベントの取得に必要な基本的なendpointを提供します。すべての会話には一意の dm_conversation_id があり、その会話を構成するイベントにはすべて一意の dm_event_id があります。   ダイレクトメッセージのルックアップ用endpointは、会話に関連するイベントの取得方法を提供します。これらの GET endpoint は、会話を構成するメッセージの取得に使用でき、グループ会話では、参加者の出入りを把握するためにも使用できます。 このダイレクトメッセージ・ルックアップの初期リリースには、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 endpoint はすべて、event_types リクエスト query パラメータを使用して、イベント種別ごとに dm_events を取得することをサポートします。現在サポートされている会話イベントの種別は3つです:
  • MessageCreate - 新しいダイレクトメッセージが作成されたときに生成されます。このイベントオブジェクトには、メッセージの時刻とテキスト、送信者のアカウントID、会話IDとイベントIDが含まれる場合があります。 
  • ParticipantsJoin - 新しい参加者がグループ会話に参加したときに生成されます。この dm_event オブジェクトには、参加した参加者のIDに加え、created_at の時刻および「invite」イベントの sender_id が含まれます。 
  • ParticipantsLeave - 参加者が会話から離脱したときに生成されます。このイベントオブジェクトには、離脱した参加者のIDとイベントの時刻が含まれます。 
詳細については、Direct Messages lookup API Referencesを参照してください。

​
v1.1 と v2 間で共有される会話およびイベントの ID

重要な概念として、会話およびイベントの ID は X プラットフォームの v1.1 と v2 で共通です。つまり、両バージョンを組み合わせて利用できます。たとえば、ダイレクトメッセージの v1.1 endpoint には単一のイベントを取得するメソッドやイベントを削除するメソッドがあり、これらはまだ v2 では提供されていません。ID は v1.1 と v2 で共通のため、v2 が返す ID に基づいて v1.1 のリクエストを送信したり、X アプリケーションの会話 URL に表示される会話 ID を参照したりできます。  

​
ダイレクトメッセージのイベント fields と expansions

X API v2 では、fields と expansions と呼ばれるツールセットを使用して、API のレスポンスに含めるデータを正確に指定できます。たとえば、ダイレクトメッセージのルックアップ endpoint は、以下の dm_events の fields をサポートします:
  • 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 イベントで利用可能です。
さらに、ダイレクトメッセージのルックアップ endpoint は以下のexpansionsをサポートします:
  • sender_id - メッセージの送信者、または会話に誰かを招待したユーザーに対応する ユーザーオブジェクト を展開します。
  • referenced_tweets.id - ダイレクトメッセージのテキストに Post へのリンクが含まれている場合、Post オブジェクトを展開します。
  • attachments.media_keys - ダイレクトメッセージにメディア添付が含まれている場合、Media オブジェクトを展開します。
  • participant_ids - グループ会話に参加または退出したユーザーに対応する ユーザーオブジェクト を展開します。
expansions には Posts、Users、Media の各オブジェクトが含まれるため、tweet.fields、user.fields、media.fields のリクエスト query パラメータも使用できます。詳細は、fields と expansions の使い方に関するガイドをご覧ください。

​
会話イベントの種類

以下は、ダイレクトメッセージにおける 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 を指定した場合、テキストのみのダイレクトメッセージに対するレスポンスは次のとおりです: { "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 の endpoint では、リクエストの認証に「キーおよびトークン」とも呼ばれる一連の認証情報が必要です。すべてのダイレクトメッセージは非公開であり、アクセスにはユーザーの認可が必要です。  これらのダイレクトメッセージの endpoint では、OAuth 2.0 Authorization Flow with PKCE または 1.0a User Context の使用が必要です。つまり、リクエストを成功させるには、一連の API Key とユーザーの Access Tokens を使用する必要があります。Access Tokens は、あなたが代理でリクエストしているユーザーに関連付けられていなければなりません。別のユーザーのために Access Tokens を生成する場合、そのユーザーは 3-legged OAuth フロー を使用してあなたの App を認可または認証する必要があります。 OAuth のユーザーコンテキストは扱いが難しい場合があります。この認証方式に不慣れな場合は、library や Postman のようなツールを使用して、リクエストを適切に認証することを推奨します。  OAuth 2.0 Authorization Code（PKCE 付き） は、アプリケーションのスコープや複数デバイス間にわたる認可フローをより細かく制御できます。OAuth 2.0 では、ユーザーに代わって特定の権限を付与する細分化されたスコープを選択できます。ダイレクトメッセージのルックアップ endpoint には次のスコープが必要です: dm.read, post.read, user.read App で OAuth 2.0 を有効にするには、developer portal の App settings セクションにある App の authentication settings で有効化する必要があります。

​
developer portal、Project、および開発者用 App

X API v2 の endpoint で動作する一連の認証情報を取得するには、承認済みのデベロッパーアカウントを取得し、そのアカウント内に Project を作成し、さらにその Project 内に開発者用 App を作成する必要があります。その後、開発者用 App 内でキーおよびトークンを確認できます。 

​
レートリミット

毎日、多数の開発者が X API にリクエストを送信しています。これらの大量のリクエストを管理するため、各 endpoint にレートリミットが設定されており、App または認証済みユーザーの代理で行えるリクエスト数が制限されています。 Direct Message の lookup endpoint はユーザーレベルのレートリミットが適用されます。つまり、あなたが代理でリクエストを行う認証済みユーザーは、あなたの X App を用いて行えるリクエスト数に上限があります。GET メソッドには、15分あたり300リクエストのユーザーレートリミットが適用されます。これらのレートリミットは、GET endpoint 間で共有されます。  これらのendpointはページネーションを利用して、レスポンスを迅速に返します。単一のレスポンスで送信できる結果（最大100件のイベント）を超える場合は、ページネーションが必要です。1ページあたりに返す結果数を指定するには max_results パラメータを、次のページの結果を取得するには pagination_token パラメータを使用してください。詳細はページネーションガイドをご参照ください。 役に立つツール ダイレクトメッセージのlookup endpointを扱う際に、ぜひ活用していただきたいツールをご紹介します。  Postman Postmanは、endpointのテストに利用できる優れたツールです。各Postmanリクエストには、利用可能な内容を素早く把握できるよう、すべてのパスおよびボディパラメータが含まれています。Postmanコレクションの詳細については、Using Postmanページをご覧ください。  コードサンプル v2 ダイレクトメッセージ endpoint向けのPythonサンプルコードは、X API v2 サンプルコード GitHubリポジトリで入手できます。“Manage-Direct-Messages” フォルダーにはPOSTメソッドの例が、“Direct-Messages-lookup” フォルダーにはGETメソッドの例が含まれています。 XDev Software Development Kits (SDKs) これらのライブラリは、v2 ダイレクトメッセージ endpointに対応するよう更新中で、間もなく利用可能になる予定です。 サードパーティライブラリ コミュニティによって開発されたサードパーティライブラリが増えています。これらのライブラリは導入を支援するために設計されており、複数がまもなく v2 ダイレクトメッセージ endpointをサポートする見込みです。適切なバージョンタグを確認することで、v2 endpointで動作するライブラリを見つけられます。
⌘I