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

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

すべてのダイレクトメッセージは、ダイレクトメッセージの会話に属します。会話は1対1またはグループのいずれかです。今回のリリースでは、ダイレクトメッセージを作成し、ダイレクトメッセージの会話に関連するイベントを取得するために必要な基盤となるendpointを提供します。すべての会話には一意の dm_conversation_id があり、その会話を構成する各イベントにも一意の dm_event_id があります。   Manage Direct Message endpointは、新規メッセージを作成して会話に追加するための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 メソッドは、単一のメディアの添付に対応しています。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 で共通です。つまり、両バージョンを組み合わせて利用できます。 たとえば、ダイレクトメッセージの v1.1 endpoint には、単一のイベントを取得するメソッドやイベントを削除するメソッドがあります。これらのメソッドは v2 ではまだ提供されていません。ID は v1.1 と v2 で共通のため、v2 で得た ID に基づいて v1.1 リクエストを実行したり、X アプリ上の会話 URL に表示される会話 ID を参照したりできます。  

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

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

​
認証

すべての 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.write、dm.read、tweet.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 または認証済みユーザーに代わって実行できるリクエスト数が制限されています。  Manage Direct Message endpoints には、ユーザー単位と X App 単位の両方でレートリミットが適用されています。これは、あなたがリクエストを送信する対象の認証済みユーザーが、あなたの X App を使って送信できるメッセージ数に上限があることを意味します。加えて、あなたの X App が 1 日に送信できるダイレクトメッセージの総数にも上限があります。  POST メソッドについては、15 分あたり 200 リクエスト／メッセージのユーザー別レートリミットがあります。ユーザーは 24 時間あたり 1000 件のダイレクトメッセージにも制限されます。さらに、X App には 24 時間あたり 15000 件のメッセージ上限があります。これらのレートリミットは POST endpoint 全体で共有されます。  役立つツール ダイレクトメッセージのルックアップ endpoint を扱う際に、ぜひ活用をご検討いただきたいツールをご紹介します。  Postman Postman は endpoint をテストするのに有用なツールです。各 Postman リクエストには、利用可能な内容をすばやく把握できるよう、すべてのパスおよびボディパラメータが含まれています。Postman コレクションの詳細については、Using Postman ページをご覧ください。  コードサンプル v2 ダイレクトメッセージ endpoint 用の Python サンプルコードは、X API v2 sample code GitHub リポジトリで入手できます。“Manage-Direct-Messages” フォルダーには POST メソッドの例、“Direct-Messages-lookup” フォルダーには GET メソッドの例が含まれています。 XDev Software Development Kits (SDKs) これらのライブラリは v2 ダイレクトメッセージ endpoint に対応するよう更新中で、まもなく利用可能になる予定です。 サードパーティ製ライブラリ コミュニティによって開発されたサードパーティ製ライブラリが増えています。これらのライブラリは導入時の支援を目的として設計されており、いくつかは間もなく v2 ダイレクトメッセージ endpoint をサポートする見込みです。適切なバージョンタグを確認することで、v2 endpoint に対応するライブラリを見つけることができます。
⌘I