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

Quick Answer

TwexAPI で既存 direct-message group に DM を送るには、POST /v3/twitter/send-dm を呼び、recipient に g... で始まる既知の group ID を指定します。必須 fields は recipient、text、cookie。任意 fields は画像 1 枚用の media_urls、動画 1 本用の video_url、pin、proxy です。この endpoint は既存 group への送信専用で、group 作成や member 追加は行いません。group registry、approval state、approved draft ごとの 1 回送信、返却 message object の保存を使います。

FAQ

この endpoint で新しい direct-message group を作れますか？

いいえ。POST /v3/twitter/send-dm は recipient が g... group ID の場合、既存 group に送信します。新規 group 作成や member 追加はしません。

group ID を安全に管理するには？

internal group key、group ID、owner、purpose、allowed sender accounts、review status を持つ group registry を作ります。未確認 input の raw g... ID ではなく group key で送信します。

group DM に media を添付できますか？

はい。ただし direct-message v3 の media limit は同じです。media_urls で画像 1 枚、または video_url で動画 1 本です。両方は同時に使えません。

DM workflow は 1:1 だけではありません。support team が既存 customer group に update を送る、creator program が campaign group と素材を確認する、operations team が既存 XChat conversation に承認済み update を送る、といった場面があります。

TwexAPI の Send DM (XChat v3) endpoint は、recipient に既存 group ID を渡すことでこの用途に対応します。group ID は g... で始まる必要があります。この endpoint は既存 group に送信しますが、新しい group を作成したり member を追加したりはしません。

Group DM は 1:1 より risk が高いです。1 つの mistake が複数人に届くため、group 確認、copy approval、1 回だけ送信、返却 message object の保存という流れが安全です。

Endpoint and Group Recipient

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

POST /v3/twitter/send-dm を使い、recipient に既存 XChat group ID を指定します。

Docs では $0.001 per call とされています。重要なのは cost よりも、group message が intentional で audit 可能であることです。

Basic Group Message Request

Answer: Basic Group Message 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": "g1234567890",
    "text": "Launch group update: export fix is live. Please rerun the latest report before sharing screenshots.",
    "cookie": "auth_token=...; ct0=...; twid=...",
    "pin": "1234"
  }'

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

1{
2  "code": 200,
3  "msg": "success",
4  "data": {
5    "id": "1234567890123456789",
6    "text": "Launch group update: export fix is live.",
7    "time": "2024-01-01T12:00:00Z",
8    "attachment": null,
9    "attachments": null,
10    "sequence_id": "2076661179334979585",
11    "sender_id": "1234567890123456789",
12    "recipient_id": "g1234567890"
13  }
14}

返却された id、sequence_id、sender_id、recipient_id、time、raw response を保存します。group workflow では、g... ID がどの group を指すか分かる internal group label も保存します。

Python Group Sender

Answer: Python Group Senderとは、この事例で 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 は group mapping と approval state を必須にしています。form から arbitrary group ID を受け取り、そのまま送信する設計にはしていません。

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
13GROUPS = {
14    "launch_ops": "g1234567890",
15    "creator_review": "g9876543210",
16}
17
18def resolve_group_id(group_key: str) -> str:
19    group_id = GROUPS.get(group_key)
20    if not group_id:
21        raise ValueError(f"Unknown group key: {group_key}")
22    if not group_id.startswith("g"):
23        raise ValueError("XChat group recipient must start with 'g'")
24    return group_id
25
26def validate_group_message(text: str) -> str:
27    cleaned = text.strip()
28    if not cleaned:
29        raise ValueError("text is required")
30    return cleaned
31
32def send_group_dm(
33    group_key: str,
34    text: str,
35    *,
36    media_urls: list[str] | None = None,
37    video_url: str | None = None,
38) -> dict[str, Any]:
39    if media_urls and video_url:
40        raise ValueError("media_urls and video_url are mutually exclusive")
41    if media_urls and len(media_urls) > 1:
42        raise ValueError("media_urls supports at most one image")
43
44    payload: dict[str, Any] = {
45        "recipient": resolve_group_id(group_key),
46        "text": validate_group_message(text),
47        "cookie": X_COOKIE,
48        "pin": XCHAT_PIN,
49    }
50
51    if media_urls:
52        payload["media_urls"] = media_urls
53    if video_url:
54        payload["video_url"] = video_url
55    if PROXY:
56        payload["proxy"] = PROXY
57
58    response = requests.post(
59        API_URL,
60        headers={
61            "Authorization": f"Bearer {BEARER_TOKEN}",
62            "Content-Type": "application/json",
63            "Accept": "application/json",
64        },
65        json=payload,
66        timeout=60,
67    )
68    response.raise_for_status()
69    data = response.json()
70
71    if data.get("code") != 200:
72        raise RuntimeError(data.get("msg", "TwexAPI returned an error"))
73
74    return data
75
76def normalize_group_send(
77    draft: dict[str, Any],
78    response: dict[str, Any],
79) -> dict[str, Any]:
80    message = response.get("data") or {}
81    return {
82        "draft_id": draft["draft_id"],
83        "group_key": draft["group_key"],
84        "group_id": resolve_group_id(draft["group_key"]),
85        "message_id": message.get("id"),
86        "sequence_id": message.get("sequence_id"),
87        "sender_id": message.get("sender_id"),
88        "recipient_id": message.get("recipient_id"),
89        "sent_at": message.get("time") or datetime.now(timezone.utc).isoformat(),
90        "api_code": response.get("code"),
91        "api_msg": response.get("msg"),
92        "raw_response": response,
93    }
94
95if __name__ == "__main__":
96    draft = {
97        "draft_id": "launch-group-update-2026-07-16",
98        "group_key": "launch_ops",
99        "text": "Launch group update: export fix is live. Please rerun the latest report before sharing screenshots.",
100        "status": "approved",
101    }
102
103    if draft["status"] != "approved":
104        raise ValueError("Group DM draft must be approved before sending")
105
106    result = send_group_dm(draft["group_key"], draft["text"])
107    print(normalize_group_send(draft, result))

trusted server environment で実行します。

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

GROUPS map は明示的にしておきます。production では database から読み込んでもよいですが、approved internal group record だけを許可します。

Attach One Image or One Video

Answer: Attach One Image or One Videoとは、この事例で 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 ごとに異なります。

Group DM でも media rules は同じです。media_urls で画像 1 枚、または video_url で動画 1 本を送ります。両方は同時に使えません。

image_result = send_group_dm(
    "launch_ops",
    "Final launch checklist screenshotです。",
    media_urls=["https://example.com/checklist.jpg"],
)

video_result = send_group_dm(
    "creator_review",
    "Revised brief の short walkthrough です。",
    video_url="https://example.com/brief-walkthrough.mp4",
)

stable public URL を使い、full signed URL を log に残さないでください。media が sensitive な場合、security model が明確に許可していない限り public link 経由にしない方が安全です。

Group DM Workflow

Answer: Group DM Workflowとは、この事例で 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 ごとに異なります。

Group message は 1:1 message より強い review path を持たせます。

1. Group registry: approved group ID ごとに internal label、owner、purpose、allowed sender accounts を保存します。
2. Draft: raw g... value ではなく group key に対して message を作成します。
3. Review: group purpose、message text、media choice、sender account を確認します。
4. Send once: approved draft に対して POST /v3/twitter/send-dm を 1 回だけ呼びます。
5. Record: returned message object、group key、group ID、sender account、raw response を保存します。
6. Follow up: message を project、ticket、campaign、customer record に紐づけます。

これにより、最も多い group DM accident、つまり正しい message を間違った group に送る問題を防ぎやすくなります。

Store Group Send State

Answer: Store Group Send 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 ごとに異なります。

この table に full account cookie を保存しないでください。credential reference を保存します。

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 ごとに異なります。

• POST /v3/twitter/send-dm を group creation endpoint として扱う。これは既存 group への送信専用です。
• unreviewed form から raw g... ID を受け取り即送信する。
• group purpose に合わない generic broadcast message を送る。
• media_urls が画像 1 枚だけであることを忘れる。
• media_urls と video_url を同時に渡す。
• group がすでに message を受け取ったか確認せず unknown timeout を retry する。

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

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 ごとに異なります。

TwexAPI で XChat group に DM を送るには、POST /v3/twitter/send-dm を呼び、recipient を既存の g... group ID にします。強い production setup は、group registry、message approval、approved draft ごとの 1 回送信、returned message object の durable storage です。

これにより、group messaging を useful に保ちながら uncontrolled broadcasting を避けられます。