Core concepts

Prime Bot's data model is intentionally small. If you understand these four objects you can predict the behaviour of every feature in the dashboard and every endpoint in the API.

Campaigns

A campaign is the top-level unit of work. It owns:

• A mode — either broadcast (you push to contacts) or auto_reply (you react to incoming DMs).
• A Telegram account that will do the sending.
• A status — draft, running, paused, completed, or stopped.
• A trigger keyword (auto-reply only) — an optional case-insensitive substring match against inbound messages.
• A set of contacts (broadcast only) imported from CSV or the API.

Campaigns are isolated from each other. Two campaigns can point at the same Telegram account; Prime Bot coordinates the rate limits so they don't collide.

Sequences

A sequence is an ordered list of messages belonging to a campaign. Position 0 is the first reply, position 1 is the second, and so on. Each step has:

• body — the text to send. Supports {{first_name}} and {{handle}} tokens.
• delay_seconds — how long to wait after the previous step before sending this one.
• attachments — optional file IDs (media uploaded through the dashboard).

If a contact replies while the sequence is still running, the remaining steps are paused automatically — nobody likes a bot that keeps talking.

Followups

Followups are conditional steps that fire only when a previous step didn't get a reply within a configured window. They are attached to a sequence step, not the campaign, so you can have different nudge cadences per stage.

{
  "step_id": 42,
  "followups": [
    { "after_hours": 24, "body": "Just bumping this in case it got buried 👀" },
    { "after_hours": 72, "body": "Last one from me — happy to pick this back up whenever." }
  ]
}

Auto-reply mode

In auto_reply mode, Prime Bot subscribes to new-message updates on the connected Telegram account and matches each inbound DM against every running auto-reply campaign on that account.

Match precedence:

1. Campaigns with a trigger_keyword are evaluated first, in creation order.
2. The first keyword hit wins. If a message matches two campaigns, only the earlier one fires.
3. Campaigns without a keyword act as a catch-all — they fire for any inbound message that didn't match a keyword campaign.

This means you can have one "pricing" campaign, one "support" campaign, and one catch-all, and they'll coexist cleanly on the same number.

Tip: keep catch-all replies short and polite. They fire on every message including test pings, group-migration notices, and Telegram service messages.