How to Send direct-message DMs via API

Quick Answer

Use TwexAPI's Send DM (direct-message v3) endpoint, POST /v3/twitter/send-dm, to send an approved direct message to a one-to-one recipient or an existing g... group. The required fields are recipient, text, and cookie; optional fields include media_urls for one image, video_url for one video, pin, and proxy. The response returns a message object with fields such as id, time, sequence_id, sender_id, recipient_id, and attachments. Treat it as a write endpoint: check reachability when needed, require approval, send once, and store the returned message object.

FAQ

Which endpoint sends direct-message DMs?

Use POST /v3/twitter/send-dm on https://api.twexapi.io. Authenticate with a Bearer token and send JSON with recipient, text, and cookie. recipient can be a user ID, @handle, or an existing group ID beginning with g....

Can I send an image and a video in the same DM?

No. media_urls and video_url are mutually exclusive. media_urls supports a public URL for one image only; video_url supports one public video URL.

What should I store after sending a DM?

Store the approved draft ID, recipient input, sender account reference, returned id, sequence_id, sender_id, recipient_id, time, attachment metadata, status, and raw response. Store a secret reference for the cookie, not the cookie itself.

Sending a DM is a write action, so the most important design choice is not the request library. It is the workflow around the send: the lawful basis or recipient consent, which authorized account is sending it, who approved the message, and where the final message ID is stored.

TwexAPI's Send DM (XChat v3) endpoint sends a message through XChat's encrypted chat API. It supports one-to-one recipients by user ID or @handle, and existing group conversations by a g... group ID. The endpoint can also attach one image through media_urls or one video through video_url.

Use this endpoint for approved support follow-ups, creator operations, partnership conversations, or CRM tasks where you already have a legitimate reason to contact the recipient. Do not build blind bulk-send loops around it.

Endpoint and Request Fields

Answer: Endpoint and Request Fields 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 when your application has an approved message ready to send.

The docs list this endpoint at $0.001 per call. Treat that as the API call price, not as permission for unsolicited, bulk, or unreviewed messaging.

Basic Request

Answer: Basic 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": "@example_user",
    "text": "Hi, thanks for asking about the export issue. We shipped a fix and can help verify your latest run.",
    "cookie": "auth_token=...; ct0=...; twid=...",
    "pin": "1234"
  }'

A successful response returns a message object in data.

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

Save at least data.id, sequence_id, sender_id, recipient_id, time, and the raw response. Those fields help you reconcile CRM actions, support tickets, and later conversation history.

Python Client with Send Approval

Answer: Python Client with Send Approval 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 reads credentials from environment variables, validates the request, and refuses to send unless the draft is explicitly 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": "Hi, thanks for asking about the export issue. We shipped a fix and can help verify your latest 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))

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

Do not run this from a browser or client-side app. The request contains account credentials and can send real messages.

Sending Images or Videos

Answer: Sending Images or Videos 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.

XChat v3 supports either one image or one video in the same DM. The fields are mutually exclusive.

image_result = send_xchat_dm(
    "@example_user",
    "Here is the screenshot I mentioned.",
    media_urls=["https://example.com/screenshot.jpg"],
)

video_result = send_xchat_dm(
    "@example_user",
    "Here is a short walkthrough.",
    video_url="https://example.com/walkthrough.mp4",
)

Keep media URLs public and stable long enough for the send operation. If your storage uses expiring signed URLs, generate them immediately before sending and log only a redacted version.

Send Only After Consent and Approval

Answer: Send Only After Consent and Approval 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 permitted workflow is: document consent or another lawful basis, confirm the sender account is authorized, obtain human approval, send one message, then write the result back.

1. Establish a lawful basis: Record recipient consent, an existing support relationship, or another documented lawful reason to contact the recipient.
2. Draft: Store recipient, message text, attachment choice, authorized sender account, source workflow, and owner.
3. Acknowledge and approve: Require an Acceptable Use Policy acknowledgement and a human approval state before calling the write endpoint.
4. Send once: Call POST /v3/twitter/send-dm once for the approved draft. Do not use a bulk-send loop.
5. Record: Store message_id, sequence_id, sender, recipient, send time, and raw response.
6. Follow up: Use stored IDs to connect the DM with the authorized support or relationship record.

This gives every message an explainable reason for being sent and preserves the evidence needed to review failures without sending duplicates.

Store DM State

Answer: Store DM 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.

For production use, keep a message table separate from credential storage.

Never store the full cookie in the message row. Store a secret reference or account credential ID 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.

• Sending without documented consent or another lawful basis.
• Sending from an account the user is not authorized to control.
• Skipping the required AUP acknowledgement or human approval.
• Treating @handle as permanent; store returned recipient_id when available.
• Sending both media_urls and video_url in one request.
• Passing more than one image in media_urls.
• Logging account cookies, auth tokens, or full signed media URLs.
• Retrying unknown failures without checking whether the message was already sent.

For unknown timeouts, check conversation state before retrying. A second send may create a duplicate message.

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.

POST /v3/twitter/send-dm is the TwexAPI XChat v3 endpoint for sending an approved DM from an authorized account to a one-to-one recipient or an existing group. The production pattern is straightforward: document the lawful basis, acknowledge the AUP, obtain human approval, send once, store the returned message object, and route uncertain failures to review.

That keeps account actions controlled, attributable, and consistent with the Acceptable Use Policy.