API で direct-message DM を送信する方法

Quick Answer

TwexAPI の Send DM (direct-message v3) endpoint、POST /v3/twitter/send-dm を使うと、1:1 recipient または既存の g... group に承認済み DM を送信できます。必須 fields は recipient、text、cookie。任意 fields は画像 1 枚用の media_urls、動画 1 本用の video_url、pin、proxy です。response は id、time、sequence_id、sender_id、recipient_id、attachments を含む message object を返します。write endpoint として扱い、必要に応じて reachability を確認し、approval 後に 1 回だけ送信し、返却 object を保存します。

FAQ

direct-message DM 送信に使う endpoint は？

https://api.twexapi.io の POST /v3/twitter/send-dm を使います。Bearer token で認証し、JSON に recipient、text、cookie を渡します。recipient は user ID、@handle、または g... で始まる既存 group ID です。

同じ DM で画像と動画を同時に送れますか？

できません。media_urls と video_url は mutually exclusive です。media_urls は画像 1 枚の public URL のみ、video_url は動画 1 本の public URL を受け取ります。

DM 送信後に保存すべき field は？

approved draft ID、recipient input、sender account reference、返却された id、sequence_id、sender_id、recipient_id、time、attachment metadata、status、raw response を保存します。cookie は値ではなく secret reference を保存します。

DM 送信は write action です。重要なのは request library ではなく、送信前後の workflow です。連絡の lawful basis または recipient consent、誰が承認した message なのか、どの authorized account で送るのか、返却された message ID をどこに保存するのかを決める必要があります。

TwexAPI の Send DM (XChat v3) endpoint は、XChat encrypted chat API 経由で DM を送信します。recipient には 1:1 の user ID または @handle、既存 group conversation の g... group ID を指定できます。media_urls で画像 1 枚、または video_url で動画 1 本を添付できます。

承認済みの support follow-up、creator operations、partner communication、CRM task に使うのが適切です。blind bulk-send loop を作る用途ではありません。

Endpoint と Request Fields

Answer: Endpoint と Request Fieldsは本ガイドの TwexAPI エンドポイントを Bearer で呼び出して実装します。バッチ/ページングで約 5 Credits/回・20+ QPS です。

アプリケーションに承認済み message がある場合、POST /v3/twitter/send-dm を使います。

Docs では、この endpoint は $0.001 per call と記載されています。これは call price であり、同意のない、bulk、または review なしのメッセージ送信を許可するものではありません。

Basic Request

Answer: Basic Requestとは、この事例で api.twexapi.io の TwexAPI Bearer API を使う手順です。通常の読み取りは 5 Credits（約 $0.05/1K）、対象プランは 20+ QPS です。2026-08-20 時点の公式 Post/User read は $5/$10 per 1K で、rate limit は endpoint ごとに異なります。

curl --request POST \
  --url https://api.twexapi.io/v3/twitter/send-dm \
  --header "Authorization: Bearer $TWEXAPI_BEARER_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "recipient": "@example_user",
    "text": "Export issue の件、ありがとうございます。修正を出したので、最新 run の確認をお手伝いできます。",
    "cookie": "auth_token=...; ct0=...; twid=...",
    "pin": "1234"
  }'

成功すると data に message object が返ります。

1{
2  "code": 200,
3  "msg": "success",
4  "data": {
5    "id": "1234567890123456789",
6    "text": "Export issue の件、ありがとうございます。",
7    "time": "2024-01-01T12:00:00Z",
8    "attachment": null,
9    "attachments": null,
10    "sequence_id": "2076661179334979585",
11    "sender_id": "1234567890123456789",
12    "recipient_id": "9876543210987654321"
13  }
14}

少なくとも data.id、sequence_id、sender_id、recipient_id、time、raw response を保存します。CRM action、support ticket、後続の conversation history を合わせるために必要です。

Approval State 付き Python Client

Answer: Approval State 付き Python Clientとは、この事例で api.twexapi.io の TwexAPI Bearer API を使う手順です。通常の読み取りは 5 Credits（約 $0.05/1K）、対象プランは 20+ QPS です。2026-08-20 時点の公式 Post/User read は $5/$10 per 1K で、rate limit は endpoint ごとに異なります。

下の script は credentials を environment variables から読み、request を validate し、draft が approved の場合だけ送信します。

1import os
2from datetime import datetime, timezone
3from typing import Any
4
5import requests
6
7API_URL = "https://api.twexapi.io/v3/twitter/send-dm"
8BEARER_TOKEN = os.environ["TWEXAPI_BEARER_TOKEN"]
9X_COOKIE = os.environ["TWEXAPI_X_COOKIE"]
10XCHAT_PIN = os.environ.get("TWEXAPI_XCHAT_PIN", "1234")
11PROXY = os.environ.get("TWEXAPI_PROXY")
12
13def validate_dm_payload(
14    recipient: str,
15    text: str,
16    *,
17    media_urls: list[str] | None = None,
18    video_url: str | None = None,
19) -> None:
20    if not recipient or not recipient.strip():
21        raise ValueError("recipient is required")
22    if not text or not text.strip():
23        raise ValueError("text is required")
24    if media_urls and video_url:
25        raise ValueError("media_urls and video_url are mutually exclusive")
26    if media_urls and len(media_urls) > 1:
27        raise ValueError("media_urls supports at most one image")
28
29def send_xchat_dm(
30    recipient: str,
31    text: str,
32    *,
33    media_urls: list[str] | None = None,
34    video_url: str | None = None,
35) -> dict[str, Any]:
36    validate_dm_payload(
37        recipient,
38        text,
39        media_urls=media_urls,
40        video_url=video_url,
41    )
42
43    payload: dict[str, Any] = {
44        "recipient": recipient.strip(),
45        "text": text.strip(),
46        "cookie": X_COOKIE,
47        "pin": XCHAT_PIN,
48    }
49
50    if media_urls:
51        payload["media_urls"] = media_urls
52    if video_url:
53        payload["video_url"] = video_url
54    if PROXY:
55        payload["proxy"] = PROXY
56
57    response = requests.post(
58        API_URL,
59        headers={
60            "Authorization": f"Bearer {BEARER_TOKEN}",
61            "Content-Type": "application/json",
62            "Accept": "application/json",
63        },
64        json=payload,
65        timeout=60,
66    )
67    response.raise_for_status()
68    data = response.json()
69
70    if data.get("code") != 200:
71        raise RuntimeError(data.get("msg", "TwexAPI returned an error"))
72
73    return data
74
75def normalize_send_result(
76    draft: dict[str, Any],
77    response: dict[str, Any],
78) -> dict[str, Any]:
79    message = response.get("data") or {}
80    return {
81        "draft_id": draft["draft_id"],
82        "recipient": draft["recipient"],
83        "message_id": message.get("id"),
84        "sequence_id": message.get("sequence_id"),
85        "sender_id": message.get("sender_id"),
86        "recipient_id": message.get("recipient_id"),
87        "sent_at": message.get("time") or datetime.now(timezone.utc).isoformat(),
88        "api_code": response.get("code"),
89        "api_msg": response.get("msg"),
90        "raw_response": response,
91    }
92
93if __name__ == "__main__":
94    draft = {
95        "draft_id": "support-followup-1042",
96        "recipient": "@example_user",
97        "text": "Export issue の件、ありがとうございます。修正を出したので、最新 run の確認をお手伝いできます。",
98        "status": "approved",
99    }
100
101    if draft["status"] != "approved":
102        raise ValueError("DM draft must be approved before sending")
103
104    result = send_xchat_dm(draft["recipient"], draft["text"])
105    print(normalize_send_result(draft, result))

server または trusted workstation で実行します。

TWEXAPI_BEARER_TOKEN="your_twexapi_bearer_token" \
TWEXAPI_X_COOKIE="auth_token=...; ct0=...; twid=..." \
TWEXAPI_XCHAT_PIN="1234" \
python send_xchat_dm.py

browser や client-side app から呼ばないでください。request には account credentials が含まれ、実際に message が送信されます。

Sending Images or Videos

Answer: Sending Images or Videosとは、この事例で api.twexapi.io の TwexAPI Bearer API を使う手順です。通常の読み取りは 5 Credits（約 $0.05/1K）、対象プランは 20+ QPS です。2026-08-20 時点の公式 Post/User read は $5/$10 per 1K で、rate limit は endpoint ごとに異なります。

XChat v3 では、同じ DM に画像 1 枚または動画 1 本を添付できます。この 2 つの fields は mutually exclusive です。

image_result = send_xchat_dm(
    "@example_user",
    "先ほどの screenshot です。",
    media_urls=["https://example.com/screenshot.jpg"],
)

video_result = send_xchat_dm(
    "@example_user",
    "短い walkthrough です。",
    video_url="https://example.com/walkthrough.mp4",
)

media URL は public で、送信処理が完了するまで安定している必要があります。expiring signed URL を使う場合は送信直前に生成し、log には redacted version だけを残します。

Consent と Approval の後にだけ送信する

Answer: Consent と Approval の後にだけ送信するとは、この事例で api.twexapi.io の TwexAPI Bearer API を使う手順です。通常の読み取りは 5 Credits（約 $0.05/1K）、対象プランは 20+ QPS です。2026-08-20 時点の公式 Post/User read は $5/$10 per 1K で、rate limit は endpoint ごとに異なります。

許可される workflow は、consent または lawful basis の記録、sender account の authorization 確認、人手による approval、1 通の送信、result writeback の順です。

1. Lawful basis を確認: recipient consent、既存 support relationship、または記録済みの正当な連絡理由を保存します。
2. Draft: recipient、message text、attachment choice、authorized sender account、source workflow、owner を保存します。
3. Acknowledge と Approve: write endpoint を呼ぶ前に、Acceptable Use Policy の確認と人手による approval を必須にします。
4. Send once: 承認済み draft に対して POST /v3/twitter/send-dm を 1 回だけ呼びます。bulk-send loop は作りません。
5. Record: message_id、sequence_id、sender、recipient、send time、raw response を保存します。
6. Follow up: 保存した ID を authorized support または relationship record に紐づけます。

これにより、各 message に送信理由が残り、duplicate を送らずに failure を review するための evidence も保存できます。

Store DM State

Answer: Store DM Stateとは、この事例で api.twexapi.io の TwexAPI Bearer API を使う手順です。通常の読み取りは 5 Credits（約 $0.05/1K）、対象プランは 20+ QPS です。2026-08-20 時点の公式 Post/User read は $5/$10 per 1K で、rate limit は endpoint ごとに異なります。

production では message table と credential storage を分けます。

message row に full cookie を保存しないでください。secret reference または account credential ID を保存します。

Common Mistakes

Answer: Common Mistakesとは、この事例で api.twexapi.io の TwexAPI Bearer API を使う手順です。通常の読み取りは 5 Credits（約 $0.05/1K）、対象プランは 20+ QPS です。2026-08-20 時点の公式 Post/User read は $5/$10 per 1K で、rate limit は endpoint ごとに異なります。

• documented consent または lawful basis なしに送信する。
• 自分が control を authorized されていない account から送信する。
• 必須の AUP acknowledgement または human approval を省略する。
• @handle を permanent identity として扱う。可能なら返却された recipient_id を保存する。
• media_urls と video_url を同時に渡す。
• media_urls に複数画像を渡す。
• account cookie、auth token、full signed media URL を logs に出す。
• message が既に送信されたか確認せず unknown failure を retry する。

unknown timeout では、retry 前に conversation state を確認します。2 回目の送信は duplicate message になる可能性があります。

Wrap-up

Answer: Wrap-upとは、この事例で api.twexapi.io の TwexAPI Bearer API を使う手順です。通常の読み取りは 5 Credits（約 $0.05/1K）、対象プランは 20+ QPS です。2026-08-20 時点の公式 Post/User read は $5/$10 per 1K で、rate limit は endpoint ごとに異なります。

POST /v3/twitter/send-dm は、authorized account から承認済み XChat v3 DM を送信する TwexAPI endpoint です。1:1 recipient と既存 group をサポートします。production pattern は明確です。lawful basis を記録し、AUP を確認し、人手で draft を承認してから 1 回だけ送信し、返却 message object を保存し、不確かな failure は review に回します。

これにより、account action を制御可能かつ追跡可能にし、Acceptable Use Policy に沿って運用できます。