API で direct-message グループ DM 履歴を取得する方法

Quick Answer

TwexAPI で既存 direct-message group history を export するには、POST /v3/twitter/dm-history を呼び、recipient に group の g... ID を指定します。この endpoint は history を読むだけで、group 作成、member 追加、message 送信は行いません。recoverable job では 10〜200 の count と all: false を使い、返却された conversation_id と messages を page ごとに保存し、has_more が true の間は最古 message の sequence_id を before にします。

FAQ

Group DM history はどう request しますか？

POST /v3/twitter/dm-history を呼び、recipient に g... で始まる既存 group ID を指定します。必須の cookie も渡します。pin、count、all、before、proxy は任意です。

この endpoint は direct-message group を作成または管理しますか？

いいえ。POST /v3/twitter/dm-history は既存 conversation を読むだけです。group 作成、member 追加、message 送信は行いません。

Group history では追加で何を保存すべきですか？

message fields に加えて、internal group_key、g... group ID、返却された conversation_id、sender_id、recipient_id、sequence_id、attachments、raw JSON を保存します。archive の review と resume がしやすくなります。

グループ DM の履歴は、1:1 の export よりも少し丁寧な構造が必要です。1 つの message stream に customer、support owner、campaign manager、reviewer が混在するため、text だけでなく group ID、sender ID、timestamp、attachments、archive がどこで止まったかを示す pagination cursor も残す必要があります。

TwexAPI の Get DM History (XChat v3) endpoint は、POST /v3/twitter/dm-history で XChat history を取得します。group conversation では、g... で始まる既存 group ID を recipient に渡します。

この endpoint は既存 conversation を読むためのものです。group 作成、member 追加、message 送信は行いません。

Endpoint と Group Request Fields

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

既知の XChat group ID を使って POST /v3/twitter/dm-history を呼びます。

Basic Group History Request

Answer: Basic Group History 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/dm-history \
  --header "Authorization: Bearer $TWEXAPI_BEARER_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "recipient": "g1234567890",
    "cookie": "auth_token=...; ct0=...; twid=...",
    "pin": "1234",
    "count": 50,
    "all": false
  }'

response は conversation_id、has_more、messages を含みます。

1{
2  "code": 200,
3  "msg": "success",
4  "data": {
5    "conversation_id": "g1234567890",
6    "has_more": true,
7    "messages": [
8      {
9        "id": "1234567890123456789",
10        "text": "Launch report is ready for review.",
11        "time": "2024-01-01T12:00:00Z",
12        "sequence_id": "2076661179334979585",
13        "sender_id": "1928096185664843776",
14        "recipient_id": "g1234567890",
15        "attachment": null,
16        "attachments": null
17      }
18    ]
19  }
20}

has_more が true の場合は、現在 page の最古 message の sequence_id を取り、次の request の before として渡します。

Python Group History Exporter

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

未確認の user input から raw g... value を直接受け取るのではなく、group registry を使います。これにより export が明確な business purpose と結びつきます。

1import os
2from datetime import datetime, timezone
3from typing import Any
4
5import requests
6
7API_URL = "https://api.twexapi.io/v3/twitter/dm-history"
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 fetch_group_history_page(
27    group_key: str,
28    *,
29    before: str | None = None,
30    count: int = 50,
31) -> dict[str, Any]:
32    if count < 10 or count > 200:
33        raise ValueError("count must be between 10 and 200")
34
35    payload: dict[str, Any] = {
36        "recipient": resolve_group_id(group_key),
37        "cookie": X_COOKIE,
38        "pin": XCHAT_PIN,
39        "count": count,
40        "all": False,
41    }
42    if before:
43        payload["before"] = before
44    if PROXY:
45        payload["proxy"] = PROXY
46
47    response = requests.post(
48        API_URL,
49        headers={
50            "Authorization": f"Bearer {BEARER_TOKEN}",
51            "Content-Type": "application/json",
52            "Accept": "application/json",
53        },
54        json=payload,
55        timeout=60,
56    )
57    response.raise_for_status()
58    data = response.json()
59
60    if data.get("code") != 200:
61        raise RuntimeError(data.get("msg", "TwexAPI returned an error"))
62
63    return data["data"]
64
65def normalize_group_message(
66    group_key: str,
67    group_id: str,
68    conversation_id: str,
69    message: dict[str, Any],
70) -> dict[str, Any]:
71    return {
72        "group_key": group_key,
73        "group_id": group_id,
74        "conversation_id": conversation_id,
75        "message_id": message["id"],
76        "text": message.get("text"),
77        "time": message.get("time"),
78        "sequence_id": message.get("sequence_id"),
79        "sender_id": message.get("sender_id"),
80        "recipient_id": message.get("recipient_id"),
81        "attachment": message.get("attachment"),
82        "attachments": message.get("attachments"),
83        "fetched_at": datetime.now(timezone.utc).isoformat(),
84        "raw": message,
85    }
86
87def export_group_history(
88    group_key: str,
89    *,
90    max_pages: int = 10,
91) -> list[dict[str, Any]]:
92    before = None
93    rows: list[dict[str, Any]] = []
94    group_id = resolve_group_id(group_key)
95
96    for _ in range(max_pages):
97        page = fetch_group_history_page(group_key, before=before)
98        conversation_id = page["conversation_id"]
99        messages = page.get("messages") or []
100
101        rows.extend(
102            normalize_group_message(group_key, group_id, conversation_id, msg)
103            for msg in messages
104        )
105
106        if not page.get("has_more") or not messages:
107            break
108
109        oldest = min(
110            messages,
111            key=lambda msg: int(msg.get("sequence_id") or 0),
112        )
113        before = oldest.get("sequence_id")
114        if not before:
115            break
116
117    return rows
118
119if __name__ == "__main__":
120    exported = export_group_history("launch_ops", max_pages=5)
121    print(f"Exported {len(exported)} group messages")

production では、次 page を取得する前に現在 page を保存します。3 page 目の後に export が失敗した場合は、最後に保存した before から再開し、全 archive を再取得しません。

Group History Workflow

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

1. Register the group: 許可された g... ID、internal key、owner、purpose、allowed reader account を保存します。
2. Request a page: POST /v3/twitter/dm-history を呼び、all: false、page size 10〜200 を使います。
3. Persist the page: checkpoint 更新前に、normalized rows と raw message JSON を保存します。
4. Advance the cursor: 現在 page の最古 message sequence_id を次の before にします。
5. Stop deliberately: has_more が false、message が空、または configured page limit に達したら停止します。

Page limit は意図的なものです。Group history は長くなるため、bounded job のほうが monitor と retry が簡単です。

When To Use all=true

Answer: **When To Use all=true**とは、この事例で 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 ごとに異なります。

all=true は、小さな group conversation を 1 回の call で完全 export したい場合に便利です。operations log、customer evidence、compliance-style archive では、page-level recovery がなくなるため向いていません。

Recurring export では all: false を維持し、cursor を保存しながら 1 page ずつ進めます。

Fields To Store

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

Full account cookie を archive に保存しないでください。Credential reference だけを保存し、secret manager に secret を置きます。

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

• Group workflow のはずなのに user ID や @handle を渡す。
• Export form で未確認の raw g... ID を入力させる。
• Newest message の sequence_id を before に使う。
• 長い group history に all=true を使い、checkpoint recovery を失う。
• 最初の page が text だけだったため attachment fields を捨てる。

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/dm-history に g... recipient を渡すと、既存 XChat group history を取得できます。信頼できる pattern は、group registry、最古 sequence_id による manual pagination、raw JSON storage、clean resume できる checkpoint です。