API pipeline: Post your posts into groups at a pace set by their traffic and follow what was sent and deleted

Index: API pipelines — index · Lifecycle: API pipeline: Create, configure, start, stop, measure and delete a Telegram campaign of any kind

Goal: your oracles post your posts into a list of groups, each group at a pace set by its own traffic, and you follow what was sent, deleted and replied to. Replies to your posts are answered under your agenda.

Steps

1. Create (Paused).

POST /v0/my/campaigns
Idempotency-Key: ann-villas-1
{"title": "Villa offers", "kind": "mtproto_announcements", "project_nonce": "<Pro project>",
 "posts": ["<post or posts workspace>"], "tg_groups": ["<preset nonce>"], "oracles": ["<oracle nonce>"],
 "agenda": "<swappable agenda>", "speed": "medium", "mode": "linear", "forward": false, "join_missing": false}
→ {"nonce": "470380000000000001", "kind": "mtproto_announcements", "status": "Paused", …}

• posts: your post cards, or workspaces of them; each needs text.
• mode: linear (groups in turn) or magnet (largest groups first).
• speed: x_slow | slow | medium | fast | x_fast: how soon the next round goes; slower rounds wait until more groups are ready.
• forward: true: forward the original Telegram posts instead of sending copies; only posts Cabi.Chat imported from Telegram can be forwarded; otherwise start answers 400 and names the post.
• join_missing: true (default false): when a group's turn reaches an oracle that is not in that group yet, it joins; your post goes out to that group on a later round. The oracle stays in the group.

2. Start. POST /v0/my/campaigns/470380000000000001/start → {"success": true, "status": "Active", "is_active": true}.

3. Follow.

GET /v0/my/campaigns/470380000000000001/sends?page=1&limit=50
→ {"rows": [{"username": "example_group", "message_id": 17552, "post": "…", "oracle": "…",
             "sent_at": "…", "deleted_at": null, "replied_at": "…", "replies": 2}], "total": 56, "has_more": true, …}
GET /v0/my/campaigns/470380000000000001/performance
→ {"totals": {"sent": 56, "deleted": 33, "replied": 3, "groups": 39, "oracles": 2, …}, "timeline": […], "groups": […]}

The posts actually sent are also kept in the campaign's sent_posts_workspace.

4. Stop. POST …/stop. The campaign runs until you stop it.

Behind

• A group gets your next post once enough new messages have gone by there since your last one: busy groups get posts more often, quiet ones wait. Posts rotate.
• Your campaigns of one project share that distance: in a group, the last post from any of them counts. Each of your oracles keeps it too, whichever campaign it posts for: an oracle that posted in a group too recently is passed over there, and the next one in the order tries.
• Your oracles take turns per group: each group has its own order of oracles, so different groups start with different ones. If an oracle cannot post there right now, the next one in the order tries in the same round; one post per group per round.
• Each of your oracles also keeps a steady pace of its own for posts to groups, spread over the day and shared by all your campaigns; a newly connected oracle starts slower. An oracle that is not due yet is passed over and the next one in the order tries; when none of them is due, the group waits for a later round.
• An oracle Telegram asks to wait sits out until it may send again.
• A group that is gone, or that your oracles are banned from or cannot post in, is dropped from the rounds. Without join_missing, a group none of your oracles is in is skipped.
• A group whose admins remove most of your posts is paused automatically and tried again later.
• Replies to your posts are answered under agenda; those answers are AI runs; their cost shows in your AI spend: API pipeline: See your AI spend. Prices: link

Rules

• Start needs a Pro project, groups, oracles, posts and an agenda: 400 assign telegram groups before activating, assign oracles before activating, assign posts before activating, announcements require an agenda assigned: replies to your posts are answered under it.
• Respect each group's rules: posts its admins delete show up as deleted_at.

API surface