Telegram API Integration: IDs, Pagination and Retries
Use these conventions when integrating the Telemetr.io REST API: keep identifier types distinct, follow each endpoint's pagination model and retry only when the operation permits it.
Keep identifier types separate
| Identifier | Use |
|---|---|
internal_id | Channel/group identifier returned by Telemetr.io |
telegram_id | Numeric Telegram identifier, resolved through the utility endpoint |
message_id | Message identifier within a chat |
snapshot_id, diff_id | Opaque IDs returned by snapshot operations |
Preserve IDs without guessing their format. Snapshot changes return internal channel IDs, which can be used with channel information endpoints.
Match the pagination model
| Endpoint family | Request | Response continuation |
|---|---|---|
| Channel search and catalog | limit, skip | Advance within the endpoint's documented bounds |
| Messages, mentions and post search | cursor | cursor |
| Snapshot/diff lists and changes | limit, cursor | next_cursor |
Stop when continuation is absent or null. Keep every other filter fixed during a cursor traversal. For diff changes, keep both the diff ID and change_type fixed; traverse added and removed separately.
An endpoint's total count is not necessarily the current page length. Search results are live; a stored diff is fixed at its creation time.
Dates and missing values
ISO date-time fields include the timezone. Some query filters use Unix seconds; verify the reference instead of sending milliseconds. Message lists use from_date/to_date, while post search uses date_from/date_to.
Optional fields can be omitted or null. Treat missing metrics as missing data instead of converting them to zero automatically.
Retry deliberately
Use timeouts and bounded backoff with jitter for transient read failures. Honor Retry-After when present. Distinguish temporary 429 conflicts from exhausted active-resource caps.
A timed-out creation request can already have changed state. The API does not promise client-side deduplication for arbitrary repeated POST requests. Check resource lists before deciding to retry. Automatic retry of bot key rotation is handled by its separate confirmation operation; it is not a general public API idempotency contract.
Never retry an unchanged 401, 402, 403, 412 or 426 in a tight loop. Resolve authentication, funding, entitlement or quota first. See the error guide.
Choose the environment explicitly
Production examples use https://api.tlmtr.io. A development integration must use its development base URL and credentials consistently. The downloadable schema and interactive reference should describe the same selected environment.
Keep API keys on the backend and sanitize request/response logs. Log endpoint, status, a safe application correlation ID and credit cost rather than authentication headers.