メインコンテンツへスキップ
Direct Messages エンドポイント v2 では、会話および会話イベントが X API の中核オブジェクトとして導入され、1 対 1 の会話とグループ会話が区別されます。1 対 1 の会話は常に参加者が 2 名のみである一方、グループ会話は 2 名以上が参加でき、メンバーシップは変動します。    このページでは、Manage Direct Messages エンドポイントをシステムに統合するにあたって把握しておくべきツールと主要概念について説明します。ページは次の 2 つのセクションで構成されています: 主要な概念

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

すべてのダイレクトメッセージは、ダイレクトメッセージの会話に属します。これらの会話は、1対1またはグループの会話です。本ローンチでは、ダイレクトメッセージを作成し、ダイレクトメッセージの会話に関連するイベントを取得するために必要な基盤となるエンドポイントを提供します。すべての会話には一意の dm_conversation_id があり、その会話を構成する各イベントにも一意の dm_event_id が付与されます。   Manage Direct Message エンドポイントは、新規メッセージを作成して会話に追加するための 3 つの POST メソッドを提供します:
  • POST /2/dm_conversations/with/:participant_id/messages - 1対1のダイレクトメッセージを作成します。既存の 1 対 1 の会話にメッセージを追加するか、新規の会話を作成します。:participant_id パスパラメータは、メッセージの受信先アカウントの User ID です。  こちらは 1 対 1 のダイレクトメッセージを送信するための JSON リクエストボディの例です:
{
   "text": "こんにちは。これまでメッセージのやり取りがない場合は新しい会話として表示され、既存のスレッドがある場合はそこに追加されます。"
}
  • POST /2/dm_conversations - 新しいグループ会話を作成し、ダイレクトメッセージを追加します。これらのリクエストには、会話の参加者リストが必要です。同じ参加者リストで複数の会話を作成できる点に注意してください。これらのリクエストは常に新しい会話IDを返します。以下は、新しいグループ会話を作成してダイレクトメッセージを追加するためのJSONリクエストボディの例です。「conversation_type」フィールドが必須で、値は「Group」（大文字小文字を区別）に設定する必要がある点に注意してください。
{
   "message": {"text": "お二人だけへ、新しいグループ会話です。"},
   "participant_ids": ["944480690","906948460078698496"],
   "conversation_type": "Group"
}
  • POST /2/dm_conversations/:dm_conversation_id/messages - 既存の会話にダイレクトメッセージを作成して追加します。:dm_conversation_id パスパラメータは、メッセージを追加する対象の会話のIDです。このメソッドは、1対1およびグループの会話の両方にメッセージを追加できます。 これは、1対1およびグループの会話の両方にダイレクトメッセージを送信するための JSON リクエストボディの例です:
{
   "text": "新しいメッセージがあります。"
}
これらの POST メソッドは、メディアを 1 点まで添付できます。POST リクエストの本文には、“text” と “attachments” のいずれか、または両方の fields を必ず含める必要があります。“attachments” field が含まれていない場合は “text” 属性が必須であり、“text” field が含まれていない場合は “attachments” field が必須です。詳細は次のセクションをご覧ください。 詳しくは、Manage Direct Messages API References を参照してください。

​
v1.1 と v2 で共有される会話 ID とイベント ID

重要なポイントとして、会話 ID とイベント ID は X プラットフォームの v1.1 と v2 で共通です。つまり、両バージョンを併用できます。 たとえば、Direct Messages v1.1 のエンドポイントには、単一のイベントを返すメソッドやイベントを削除するメソッドがあります。これらのメソッドは v2 ではまだ利用できません。ID は v1.1 と v2 で共通のため、v2 で取得した ID に基づいて v1.1 のリクエストを行ったり、X アプリの会話 URL に表示される会話 ID を参照したりできます。  

​
メディアの添付とPostの参照

Manage Direct Message エンドポイントはすべて、1件のメディア（写真、動画、またはGIF）の添付に対応しています。メディアを添付するには、v1.1 の Upload media エンドポイントで生成されたメディアIDが必要です。ダイレクトメッセージを送信する認証済みユーザー自身が、そのメディアをアップロードしている必要があります。アップロード後、メディアはメッセージに添付する目的で24時間利用可能です。 メディアを添付する方法の例として、以下に JSON リクエストボディを示します。 
{
 "text": "写真です...",
 "attachments": [{"media_id": "1583157113245011970}]
}
生成される MessageCreate イベントには、次のメタデータが含まれます。 
{
    "attachments": {
        "media_keys": [
            "5_1583157113245011970"
        ]
    }
}
メッセージ本文に Post の URL を記載することで、Post を含めることもできます。メッセージに Post を含める方法の例として、以下に JSON リクエストボディを示します。 
{
 "text": "これが私が話していたTweetです：https://x.com/SnowBotDev/status/1580559079470145536"
}
生成される MessageCreate イベントには、以下のメタデータが含まれます。 
{
    "referenced_tweets": [
        {
            "id": "1580559079470145536"
        }
    ]
}

​
認証

すべての X API v2 エンドポイントでは、キーやトークンとも呼ばれる一式の認証情報を使用してリクエストを認証する必要があります。ダイレクトメッセージはすべて非公開で、アクセスにはユーザーの許可が必要です。  これらのダイレクトメッセージ用エンドポイントでは、OAuth 2.0 Authorization Flow with PKCE または 1.0a User Context を使用する必要があります。つまり、API キー一式とユーザーのアクセス トークンを用いてリクエストを成功させる必要があります。アクセス トークンは、あなたが代理でリクエストする対象ユーザーに関連付けられていなければなりません。別のユーザーのアクセス トークンを生成する場合は、そのユーザーが 3-legged OAuth flow を使用してあなたのアプリを許可または認証する必要があります。 OAuth のユーザーコンテキストは扱いが難しい場合があります。この認証方式に不慣れな場合は、ライブラリ や Postman のようなツールを使用して、適切にリクエストを認証することをおすすめします。  OAuth 2.0 Authorization Code with PKCE は、アプリケーションのスコープや複数デバイスにまたがる認可フローをより柔軟に制御できます。OAuth 2.0 では、ユーザーに代わって特定の権限を付与する、きめ細かなスコープを選択できます。ダイレクトメッセージの lookup エンドポイントには、次のスコープが必要です：dm.write、dm.read、tweet.read、user.read。 アプリで OAuth 2.0 を有効にするには、開発者ポータルのアプリ設定セクションにある認証設定で有効化してください。

​
開発者ポータル、プロジェクト、開発者アプリ

X API v2 のエンドポイントで使用できる一連の認証情報を取得するには、承認済みの開発者アカウントを用意し、そのアカウント内でプロジェクトを作成し、さらにそのプロジェクト内に開発者アプリを作成する必要があります。キーとトークンは、開発者アプリ内で確認できます。 

​
レート制限

毎日、多数の開発者が X API にリクエストを送信しています。これらの膨大なリクエスト量を管理するため、各エンドポイントにはレート制限が設けられており、アプリや認証済みユーザーに代わって実行できるリクエスト数に上限があります。  Manage Direct Message エンドポイントには、ユーザー単位および X アプリ単位の両方でレート制限が適用されます。つまり、あなたが代行してリクエストを行う認証済みユーザーは、あなたの X アプリを通じて送信できるメッセージ数に上限があります。さらに、あなたの X アプリ自体が 1 日に送信できるダイレクトメッセージ数にも上限があります。  POST メソッドには、15 分あたり 200 件のリクエスト/メッセージというユーザー単位のレート制限があります。ユーザーは 24 時間あたり 1000 件のダイレクトメッセージにも制限されます。加えて、X アプリには 24 時間あたり 15,000 件のメッセージという上限があります。これらのレート制限は POST エンドポイント間で共有されます。  便利なツール Direct Messages の lookup エンドポイントを扱う際に、ぜひ活用してほしいツールをご紹介します。  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 エンドポイントに対応したライブラリを見つけられます。