SynqDocs
Management APITelegram groups

Read a Telegram group again

Reads the group's title and kind, whether Synq's bot is its guard bot, and the bot's rights there from Telegram now: after an admin changed them, or the group became a supergroup. A change is recorded as `telegram_group.updated`; a bot no longer in the group as `telegram_group.bot_removed`. Needs `org.integrations.edit`, and an API with a Telegram bot (409 `telegram_unavailable`).

POST/v1/orgs/{org}/telegram-groups/{group}/check

Reads the group's title and kind, whether Synq's bot is its guard bot, and the bot's rights there from Telegram now: after an admin changed them, or the group became a supergroup. A change is recorded as telegram_group.updated; a bot no longer in the group as telegram_group.bot_removed. Needs org.integrations.edit, and an API with a Telegram bot (409 telegram_unavailable).

Authorization

bearer
AuthorizationBearer <token>

An org API key (sk_live_…, sk_test_…), or an access token from the Synq issuer (the synq brand, on the accounts host) for this API.

In: header

Path Parameters

org*string

The org's id

Match^org_[0-9a-hjkmnp-tv-z]{26}$
group*string

The Telegram group's id

Match^tgg_[0-9a-hjkmnp-tv-z]{26}$

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X POST "https://api.synq.build/v1/orgs/org_01h455vb4pex5vsknk084sn02q/telegram-groups/tgg_01h455vb4pex5vsknk084sn02q/check" \  -H "Authorization: Bearer $SYNQ_API_KEY" \  -H "Content-Type: application/json" \  -d '{}'
{  "id": "tgg_01h455vb4pex5vsknk084sn02q",  "brand_id": "brd_01h455vb4pex5vsknk084sn02q",  "chat_id": "-1001234567890",  "title": "RODAI Holders",  "username": "string",  "kind": "group",  "status": "connected",  "guard_bot": true,  "rights": {    "invite_users": true,    "restrict_members": true,    "pin_messages": true  },  "member_count": 0,  "invite_link": "string",  "own_bot": true,  "listed": true,  "listed_by": "brand",  "counts": {    "roles": 0,    "gated": true,    "managed": 0  },  "checked_at": "2026-10-21T12:00:00.000Z",  "connected_at": "2026-10-21T12:00:00.000Z"}

Start connecting a Telegram group POST

A one-time code, good for 15 minutes, and the link that adds Synq's bot to a group as an admin and sends it there; `command` is the same for a bot already in the group. Only an admin of the group can connect it, and people verify on `brand`'s hosted pages: they sign in the way they already do, link Telegram on their member profile and show what they hold with wallets, so the brand must offer wallets (400 at `brand` with the fix otherwise); it needn't offer Telegram sign-in. Synq's bot reads the group and its own rights when the code arrives, and the group is recorded as `telegram_group.connected`. At most 25 groups per org. Needs `org.integrations.edit` and a plan with token gating (403 `plan_feature_unavailable`), and an API with a Telegram bot (409 `telegram_unavailable`).

Announce a Telegram group's window POST

Reads the group and the bot's rights afresh, posts the announcement in the window's topic and pins it (without a notification), and starts the countdown: everyone already in the group, but its admins and bots, has until the deadline to verify. Takes the settings as `PUT …/window` does, saved first. The bot needs Pin messages and Ban users (409 with the fix). Synq posts it in the background (202), so the caller may go: the window answers `announce_queued_at` until it's posted, then `announced`, or `announce_failure` with the fix when nothing was posted; pressing it again meanwhile is the same announcement. What Synq knows without asking Telegram (no gate, announced already, the gate off) is refused at once. An API without a background runner posts at once (200). Recorded as `telegram_group.window_announced`, as who asked. Needs `org.integrations.edit`, a plan with token gating (403 `plan_feature_unavailable`) and an API with a Telegram bot (409 `telegram_unavailable`).