HailMe Platform docsOpen cabinet →

Telegram BYOC & TEST lab

Connect your own bot

In TEST, an OWNER can enable Telegram in Options & channels and store a write-only encrypted bot token. Saving contacts no provider. By default, Bot API control and outgoing messages are paused. An operator can approve a short owner pilot for one real message to one confirmed recipient in TEST, with simulated balance and budgets. Production connection is control-only and uses a separate bot.

After a separately authorized activation, Verify checks bot identity, Register installs only the platform-owned webhook, Inspect reads status and Disconnect removes only that webhook. Existing foreign webhooks are never replaced or deleted. Keep the same operation ID after an uncertain result.

Recipients use a private five-minute bot start link, then their authenticated application backend confirms the same user reference. /stop, blocking, unlink and credential rotation revoke consent. Groups, phone numbers and Telegram usernames are not delivery targets.

Backend endpoints: /v1/telegram/byoc, /links, /links/{id}/confirm and /recipients/{id}/unlink. The server generates an official-domain callback; token and webhook secret are never returned. See Swagger for exact bodies and scopes.

Durable pacing: conservative20 bot requests/s,1/private chat/s; 429 honors retry_after. Ambiguous sends are UNKNOWN and never blindly retried. Provider acceptance is not delivery or read proof. The owner pilot has a durable one-attempt cap, including restarts and uncertain responses. General customer Telegram traffic remains disabled.

Try without a real bot

This staging lab simulates Telegram opt-in and delivery. No real bot, webhook or Telegram messages are connected. LIVE remains unavailable.

Try the complete flow

  1. In a TEST project, enable the Telegram option, then save the simulated bot connection.
  2. Create a five-minute TEST link for a fictional test:demo reference.
  3. Simulate private /start with fake:demo, then confirm. Only confirmed recipient IDs can receive FAKE sends.
  4. Activate simulated billing and funds. Preview the template and sample fee, then send FAKE. No payment or provider request occurs.
  5. Use Notifications and Usage filters TELEGRAM and CABINET; CSV honors filters and the selected UTC period.
  6. Unlink to block new sends and invalidate queued recipient snapshots before simulated submission.

Templates, billing and safeguards

The default English template is sandbox.telegram.v1 with a string parameter message. Publish exact locale versions in Templates. Telegram text is plain text, up to 4,096 characters including plan branding. No buttons, files or formatting mode yet.

The sample price is one TEST USD cent per message and zero provider cost. Affiliated projects inherit zero platform fee; the operator can enable TELEGRAM fees independently. This is a sandbox rate, not a commercial quote. Project budgets reserve before admission, settle once and release definitive failures. UNKNOWN remains held and is not blindly retried.

Backend API

/v1/telegram/test uses telegram:read/write. Link creation → simulated start → explicit confirmation returns a scoped telegramRecipientId. Use that UUID in the common notification API with notifications:write and a persisted Idempotency-Key. See Swagger for the exact contracts. The cabinet uses its OWNER session and CSRF protection, never a browser service key.

{
  "channel": "TELEGRAM",
  "recipient": {"telegramRecipientId": "<confirmed TEST UUID>"},
  "templateId": "sandbox.telegram.v1", "locale": "en",
  "parameters": {"message": "Synthetic order is approaching"},
  "expiresAt": "<UTC instant within 24 hours>", "clientReference": "demo"
}

Retry a lost response with the exact same key and body. ACCEPTED is FAKE provider admission, not delivery or read evidence.

SDK status

The Telegram typed method is implemented in the next JVM SDK source candidate. Published signed dev.3 does not include it yet; use the HTTP API until a new signed version is released.

Limits and next step

200 synthetic recipients per project, 1,000 queued capacity when first connected, 60 cabinet sends per organization/hour, plus existing budgets and queue limits. The module defaults off and is accepted only with TEST/FAKE and simulated billing. The BYOC adapter is implemented separately; real bot control and a single owner message require an explicit scoped operator permit. The cabinet clearly labels that real delivery exception.