連携ガイド

このガイドでは、アプリケーションに Direct Messages を管理するエンドポイントを統合するために必要な主要な概念を説明します。

認証

DM エンドポイントではユーザー認証が必要です。

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

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

必要なスコープ (OAuth 2.0)

Scope	必要な操作
`dm.write`	メッセージの送信と削除
`dm.read`	`dm.write` と併せて必須
`tweet.read`	DM 関連スコープで必須
`users.read`	DM 関連スコープで必須

エンドポイントの概要

Method	Endpoint	説明
POST	`/2/dm_conversations/with/:participant_id/messages`	1対1のメッセージを送信
POST	`/2/dm_conversations`	グループ会話を作成
POST	`/2/dm_conversations/:dm_conversation_id/messages`	会話にメッセージを追加
DELETE	`/2/dm_events/:event_id`	メッセージを削除

メッセージを送信する

1 対 1 メッセージ

特定のユーザーにメッセージを送信します。既存の会話がない場合は、新しい会話を作成します:

cURL

curl -X POST "https://api.x.com/2/dm_conversations/with/9876543210/messages" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello!"}'

from xdk import Client

client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

# 1 対 1 の DM を送信
response = client.dm_conversations.create_message(
    participant_id="9876543210",
    text="Hello!"
)
print(response.data)

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

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

// 1 対 1 の DM を送信
const response = await client.dmConversations.createMessage({
  participantId: "9876543210",
  text: "Hello!",
});
console.log(response.data);

グループ会話

新しいグループ会話を作成し、最初のメッセージを送信します:

cURL

curl -X POST "https://api.x.com/2/dm_conversations" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_type": "Group",
    "participant_ids": ["944480690", "906948460078698496"],
    "message": {"text": "Welcome to our group!"}
  }'

from xdk import Client

client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

# グループ会話を作成
response = client.dm_conversations.create(
    conversation_type="Group",
    participant_ids=["944480690", "906948460078698496"],
    message={"text": "Welcome to our group!"}
)
print(response.data)

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

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

// グループ会話を作成
const response = await client.dmConversations.create({
  conversationType: "Group",
  participantIds: ["944480690", "906948460078698496"],
  message: { text: "Welcome to our group!" },
});
console.log(response.data);

conversation_type フィールドは大文字小文字を区別するため、値を必ず "Group" に設定する必要があります。

既存の会話に追加する

参加しているいずれの会話にもメッセージを送信できます:

cURL

curl -X POST "https://api.x.com/2/dm_conversations/1582103724607971328/messages" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Another message"}'

from xdk import Client

client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

# 既存の会話にメッセージを追加
response = client.dm_conversations.add_message(
    dm_conversation_id="1582103724607971328",
    text="Another message"
)
print(response.data)

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

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

// 既存の会話にメッセージを追加
const response = await client.dmConversations.addMessage({
  dmConversationId: "1582103724607971328",
  text: "Another message",
});
console.log(response.data);

メディアの添付

各メッセージにつきメディアは 1 つだけ添付できます (写真、動画、または GIF) 。

メディアをアップロードする

Media Upload エンドポイントを使用してファイルをアップロードし、media_id を取得します。

メッセージに含める

{
  "text": "この画像を見てください！",
  "attachments": [{"media_id": "1583157113245011970"}]
}

メディアは認証済みユーザー自身がアップロードしたものである必要があります
メディアはアップロードから 24 時間利用可能です
各メッセージで添付できるメディアは 1 つだけです

メッセージ本文にポストのURLを追加して、ポストを含めます。

{
  "text": "Have you seen this? https://x.com/XDevelopers/status/1580559079470145536"
}

レスポンスには、ポストのIDを格納した referenced_tweets フィールドが含まれます。

メッセージ要件

フィールド	必須	注記
`text`	はい*	添付ファイルがない場合は必須
`attachments`	はい*	`text` がない場合は必須

*text と attachments の少なくとも一方は指定する必要があります。

v1.1 との ID 互換性

会話 ID とイベント ID は、v1.1 と v2 のエンドポイント間で共通です。これにより、次のようなハイブリッドなワークフローが可能になります。

v2 でメッセージを作成する
v1.1 でメッセージを削除する (v2 ではまだ利用できません)
x.com の URL に含まれる会話 ID を参照する

エラー処理

ステータス	エラー	解決策
400	無効なリクエスト	リクエストボディの形式を確認してください
401	認証されていません	アクセストークンを確認してください
403	アクセスが拒否されました	スコープとユーザー権限を確認してください
429	リクエストが多すぎます	しばらく待ってから再試行してください

よくある問題

ユーザーに送信できない

受信者が、知らないユーザーからのメッセージを受け取らないDM設定にしているか、あなたをブロックしている可能性があります。

メディアの添付に失敗した

メディアが同じ認証済みユーザーのアカウントからアップロードされており、かつアップロードから24時間以内のものであることを確認してください。

グループの作成に失敗した

すべての参加者idが有効であり、ユーザーがグループDMへの招待を許可していることを確認してください。

次のステップ

クイックスタート

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

DMルックアップ

DM会話を取得する

メディアアップロード

添付メディアをアップロードする

APIリファレンス

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

概要

投稿

ユーザー

ダイレクトメッセージ

いいね

リスト

スペース

コミュニティ

コミュニティノート

トレンド

ニュース

メディア

X のアクティビティ

利用状況

ストリーム接続

コンプライアンス

Enterprise v2

いいねのストリーム

GNIP 2.0

認証

必要なスコープ (OAuth 2.0)

エンドポイントの概要

メッセージを送信する

1 対 1 メッセージ

グループ会話

既存の会話に追加する

メディアの添付

メッセージ要件

v1.1 との ID 互換性

エラー処理

よくある問題

次のステップ

クイックスタート

DMルックアップ

メディアアップロード

APIリファレンス

認証

必要なスコープ (OAuth 2.0)

エンドポイントの概要

メッセージを送信する

1 対 1 メッセージ

グループ会話

既存の会話に追加する

メディアの添付

投稿を共有する

メッセージ要件

v1.1 との ID 互換性

エラー処理

よくある問題

次のステップ

クイックスタート

DMルックアップ

メディアアップロード

APIリファレンス