連携ガイド

このガイドでは、アプリケーションに Direct Messages ルックアップエンドポイントを統合するために必要となる基本的な概念を説明します。

認証

DM エンドポイントにおいて非公開の会話にアクセスするには、ユーザー認証が必要です。

Method	Description
OAuth 2.0 Authorization Code with PKCE	推奨
OAuth 1.0a User Context	レガシーサポート

App-Only 認証はサポートされていません。すべてのダイレクトメッセージは非公開です。

必要なスコープ (OAuth 2.0)

スコープ	必要となるケース
`dm.read`	DM イベントの読み取り
`tweet.read`	`dm.read` と併せて必須
`users.read`	`dm.read` と併せて必須

会話タイプ

1対1

参加者は常に2人だけです。Conversation ID の形式: {smaller_user_id}-{larger_user_id}

グループ

2人以上の参加者がいます。参加メンバーは時間の経過とともに変わることがあります。

イベントタイプ

イベント	説明	主なフィールド
`MessageCreate`	メッセージが送信された	`text`, `sender_id`
`ParticipantsJoin`	ユーザーがグループに参加した	`participant_ids`, `sender_id`
`ParticipantsLeave`	ユーザーがグループから退出した	`participant_ids`

イベントの例

MessageCreate

{
  "id": "1582838499983564806",
  "event_type": "MessageCreate",
  "text": "Hi everyone.",
  "sender_id": "944480690",
  "dm_conversation_id": "1578398451921985538",
  "created_at": "2022-10-19T20:58:00.000Z"
}

ParticipantsJoin

{
  "id": "1582835469712138240",
  "event_type": "ParticipantsJoin",
  "participant_ids": ["944480690"],
  "sender_id": "17200003",
  "dm_conversation_id": "1578398451921985538",
  "created_at": "2022-10-19T20:45:58.000Z"
}

ParticipantsLeave

{
  "id": "1582838535115067392",
  "event_type": "ParticipantsLeave",
  "participant_ids": ["944480690"],
  "dm_conversation_id": "1578398451921985538",
  "created_at": "2022-10-19T20:58:09.000Z"
}

フィールドと Expansions

デフォルトフィールド

イベントタイプ	デフォルトフィールド
MessageCreate	`id`, `event_type`, `text`
ParticipantsJoin/Leave	`id`, `event_type`, `participant_ids`

利用可能なフィールド

フィールド	説明	イベント
`dm_conversation_id`	会話ID	すべて
`created_at`	イベントのタイムスタンプ	すべて
`sender_id`	送信または招待を行ったユーザー	MessageCreate, Join
`attachments`	メディアの添付ファイル	MessageCreate
`referenced_tweets`	共有された投稿	MessageCreate

利用可能な expansions

Expansion	返されるオブジェクト
`sender_id`	送信者のユーザーオブジェクト
`participant_ids`	参加者のユーザーオブジェクト
`attachments.media_keys`	メディアオブジェクト
`referenced_tweets.id`	ポストオブジェクト

expansions を指定した例

cURL

curl "https://api.x.com/2/dm_events?\
dm_event.fields=created_at,sender_id,attachments&\
expansions=sender_id,attachments.media_keys&\
user.fields=username,profile_image_url&\
media.fields=url,type" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

# expansions を指定して DM イベントを取得する
for page in client.dm_events.list(
    dm_event_fields=["created_at", "sender_id", "attachments"],
    expansions=["sender_id", "attachments.media_keys"],
    user_fields=["username", "profile_image_url"],
    media_fields=["url", "type"],
    max_results=100
):
    for event in page.data:
        print(f"Event: {event.event_type} - {event.text}")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

const paginator = client.dmEvents.list({
  dmEventFields: ["created_at", "sender_id", "attachments"],
  expansions: ["sender_id", "attachments.media_keys"],
  userFields: ["username", "profile_image_url"],
  mediaFields: ["url", "type"],
  maxResults: 100,
});

for await (const page of paginator) {
  page.data?.forEach((event) => {
    console.log(`Event: ${event.event_type} - ${event.text}`);
  });
}

ページネーション

DM イベントは逆時系列 (新しいものが先) で返されます。

cURL

# 最初のリクエスト
curl "https://api.x.com/2/dm_events?max_results=100" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

# ページネーション用トークンを使った後続リクエスト
curl "https://api.x.com/2/dm_events?max_results=100&pagination_token=NEXT_TOKEN" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

# SDK がページネーションを自動的に処理します
all_events = []

for page in client.dm_events.list(max_results=100):
    if page.data:
        all_events.extend(page.data)

print(f"Found {len(all_events)} DM events")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

async function getAllDMEvents() {
  const allEvents = [];

  // SDK がページネーションを自動的に処理します
  const paginator = client.dmEvents.list({ maxResults: 100 });

  for await (const page of paginator) {
    if (page.data) {
      allEvents.push(...page.data);
    }
  }

  return allEvents;
}

// 使い方
const events = await getAllDMEvents();
console.log(`Found ${events.length} DM events`);

30 日前までのイベントを取得できます。

v1.1 との ID 互換性

会話 ID とイベント ID は、v1.1 と v2 の両方のエンドポイントで共有されています。つまり、次のことができます。

v2 を使ってイベントを取得し、その後 v1.1 を使って特定のメッセージを削除する
x.com の URL に含まれる会話 ID を API リクエストで参照する

次のステップ

クイックスタート

初めてのDMルックアップリクエストを送信する

DMを送信

ダイレクトメッセージを送信する

APIリファレンス

エンドポイントの詳細なドキュメント

サンプルコード

実行可能なコード例

概要

投稿

ユーザー

ダイレクトメッセージ

いいね

リスト

スペース

コミュニティ

コミュニティノート

トレンド

ニュース

メディア

X のアクティビティ

利用状況

ストリーム接続

コンプライアンス

Enterprise v2

いいねのストリーム

GNIP 2.0

認証

必要なスコープ (OAuth 2.0)

会話タイプ

1対1

グループ

イベントタイプ

イベントの例

フィールドと Expansions

デフォルトフィールド

利用可能なフィールド

利用可能な expansions

expansions を指定した例

v1.1 との ID 互換性

次のステップ

クイックスタート

DMを送信

APIリファレンス

サンプルコード