How to Send direct-message Group DMs via API

Quick Answer

To send a DM to an existing direct-message group with TwexAPI, call POST /v3/twitter/send-dm and set recipient to a known group ID beginning with g.... Required fields are recipient, text, and cookie; optional fields include one-image media_urls, one-video video_url, pin, and proxy. The endpoint sends to an existing group only: it does not create a group or add members. Use a group registry, approval state, one send attempt per approved draft, and store the returned message object for audit.

FAQ

Can TwexAPI create a new direct-message group with this endpoint?

No. POST /v3/twitter/send-dm sends to an existing group when recipient is a g... group ID. It does not create a new group or add members.

How should I manage group IDs safely?

Create a group registry with an internal group key, group ID, owner, purpose, allowed sender accounts, and review status. Send by group key rather than accepting raw g... IDs from unreviewed user input.

Can group DMs include media?

Yes, with the same direct-message v3 media limits: either one image through media_urls or one video through video_url. The two fields are mutually exclusive.

Some DM workflows are not one-to-one. A support team may need to follow up in an existing customer group, a creator program may coordinate with a small campaign group, or an operations team may send one approved update to a group conversation that already exists on X.

TwexAPI's Send DM (XChat v3) endpoint supports this by accepting an existing group ID in recipient. The group ID must begin with g...; the endpoint sends to the group, but it does not create a new group or add members.

Treat group DMs as higher-risk than one-to-one messages. One mistake reaches multiple people, so the safest implementation is: verify the group, approve the copy, send once, and store the returned message object.

Endpoint and Group Recipient

Answer: Endpoint and Group Recipient is implemented by calling the TwexAPI endpoint documented in this guide with a Bearer Token; batch or paginated requests reduce overhead to ~5 credits per call at 20+ QPS.

Use POST /v3/twitter/send-dm with a recipient value that is an existing XChat group ID.

The documentation lists this endpoint at $0.001 per call. The important operational detail is not cost; it is making sure a group message is intentional and auditable.

Basic Group Message Request

Answer: Basic Group Message Request means using TwexAPI Bearer APIs on api.twexapi.io for this user case. A typical read uses 5 Credits (about $0.05 per 1,000), and qualifying paid plans publish 20+ QPS. As of 2026-08-20, first-party developer API Post and User reads list at $5 and $10 per 1,000 resources; rate limits vary by 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": "Update for the launch group: the export fix is live. Please rerun the latest report before sharing screenshots.",
    "cookie": "auth_token=...; ct0=...; twid=...",
    "pin": "1234"
  }'

The response returns a message object in data.

1{
2  "code": 200,
3  "msg": "success",
4  "data": {
5    "id": "1234567890123456789",
6    "text": "Update for the launch group: the 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}

Store the returned id, sequence_id, sender_id, recipient_id, time, and raw response. For group workflows, also store the internal group label so reviewers know what the g... ID represents.

Python Group Sender

Answer: Python Group Sender means using TwexAPI Bearer APIs on api.twexapi.io for this user case. A typical read uses 5 Credits (about $0.05 per 1,000), and qualifying paid plans publish 20+ QPS. As of 2026-08-20, first-party developer API Post and User reads list at $5 and $10 per 1,000 resources; rate limits vary by endpoint.

This script requires a group mapping and an approval state before it sends. It does not let callers pass an arbitrary group ID from a form and immediately send a message.

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": "Update for the launch group: the 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))

Run it from a 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

The GROUPS map is intentionally explicit. In production, load that mapping from your database and only allow approved internal group records.

Attach One Image or One Video

Answer: Attach One Image or One Video means using TwexAPI Bearer APIs on api.twexapi.io for this user case. A typical read uses 5 Credits (about $0.05 per 1,000), and qualifying paid plans publish 20+ QPS. As of 2026-08-20, first-party developer API Post and User reads list at $5 and $10 per 1,000 resources; rate limits vary by endpoint.

The same endpoint supports media for group DMs, but the media rules are unchanged: one image through media_urls, or one video through video_url, not both.

image_result = send_group_dm(
    "launch_ops",
    "Here is the final launch checklist screenshot.",
    media_urls=["https://example.com/checklist.jpg"],
)

video_result = send_group_dm(
    "creator_review",
    "Short walkthrough for the revised brief.",
    video_url="https://example.com/brief-walkthrough.mp4",
)

Use stable public URLs and avoid logging full signed URLs. If the media is sensitive, do not route it through public links unless your security model explicitly allows it.

Group DM Workflow

Answer: Group DM Workflow means using TwexAPI Bearer APIs on api.twexapi.io for this user case. A typical read uses 5 Credits (about $0.05 per 1,000), and qualifying paid plans publish 20+ QPS. As of 2026-08-20, first-party developer API Post and User reads list at $5 and $10 per 1,000 resources; rate limits vary by endpoint.

A group message should have a stronger review path than a one-to-one message.

1. Group registry: Store each approved group ID with an internal label, owner, purpose, and allowed sender accounts.
2. Draft: Create the message against a group key, not a raw g... value from user input.
3. Review: Confirm the group purpose, message text, media choice, and sender account.
4. Send once: Call POST /v3/twitter/send-dm for the approved draft.
5. Record: Save the returned message object, group key, group ID, sender account, and raw response.
6. Follow up: Connect the message to the project, ticket, campaign, or customer record that justified the send.

This prevents the most common group-DM failure: sending a correct message to the wrong group.

Store Group Send State

Answer: Store Group Send State means using TwexAPI Bearer APIs on api.twexapi.io for this user case. A typical read uses 5 Credits (about $0.05 per 1,000), and qualifying paid plans publish 20+ QPS. As of 2026-08-20, first-party developer API Post and User reads list at $5 and $10 per 1,000 resources; rate limits vary by endpoint.

Do not store the full account cookie in this table. Store a credential reference instead.

Common Mistakes

Answer: Common Mistakes means using TwexAPI Bearer APIs on api.twexapi.io for this user case. A typical read uses 5 Credits (about $0.05 per 1,000), and qualifying paid plans publish 20+ QPS. As of 2026-08-20, first-party developer API Post and User reads list at $5 and $10 per 1,000 resources; rate limits vary by endpoint.

• Treating POST /v3/twitter/send-dm as a group creation endpoint. It sends to an existing group only.
• Accepting raw g... IDs from an unreviewed form and sending immediately.
• Sending a generic broadcast message that does not match the group's purpose.
• Forgetting that media_urls supports only one image.
• Sending both media_urls and video_url.
• Retrying after an unknown timeout without checking whether the group already received the message.

For unknown failures, check the group conversation or your message history before retrying. A second send may duplicate the update.

Wrap-up

Answer: Wrap-up means using TwexAPI Bearer APIs on api.twexapi.io for this user case. A typical read uses 5 Credits (about $0.05 per 1,000), and qualifying paid plans publish 20+ QPS. As of 2026-08-20, first-party developer API Post and User reads list at $5 and $10 per 1,000 resources; rate limits vary by endpoint.

To send a DM to an XChat group with TwexAPI, call POST /v3/twitter/send-dm and set recipient to an existing g... group ID. The strongest production setup uses a group registry, message approval, one send attempt per approved draft, and durable storage for the returned message object.

That keeps group messaging useful without turning it into uncontrolled broadcasting.