Getting started
The TeleBoost API is available on the Pro and Business plans. Create a key under Settings → Developers → API keys — it's shown once, so copy it then. All requests use HTTPS and return JSON.
curl https://teleboost.app/api/v1/contacts \ -H "Authorization: Bearer tb_live_your_key_here"
List endpoints return { "data": [...], "next_cursor": "...", "has_more": true }. Pass next_cursor back as ?cursor= to page.
Authentication & scopes
Two mechanisms, one scope model. Use an API key (Authorization: Bearer tb_live_…) for scripts and automation, or OAuth 2.1 for AI apps connecting over MCP. Keys are workspace-scoped: a key is bound to your solo data or one team at creation.
| Scope | Grants |
|---|---|
| workspace.read | Workspace metadata, team members, plan usage and quotas |
| accounts.write | Update connected account settings such as daily sending quotas |
| contacts.read / write | Leads, custom fields, notes, statuses and engagement scores |
| lists.read / write | Custom lists and their members |
| groups.read / write | Saved Telegram groups (campaign & scraping targets) |
| inbox.read | Conversations and message history across accounts |
| messages.send | Send messages from a connected account |
| campaigns.read / write | DM & group campaigns, stats, start / pause |
| templates.read / write | Message templates and AI personalities |
| tickets.read / write | Tickets, statuses, priorities, SLA and reminders |
| analytics.read | Aggregated metrics, dashboards and heatmaps |
API resources
All paths are relative to https://teleboost.app/api/v1. A selection is shown below — the full, always-current reference of every endpoint is the OpenAPI spec.
| Method | Path | Description | Scope |
|---|---|---|---|
| GET | /accounts | List connected accounts (status only) | workspace.read |
| PATCH | /accounts/{id}/quota | Update an account's sending quota | accounts.write |
| GET | /contacts | List and search contacts | contacts.read |
| POST | /contacts | Create a contact | contacts.write |
| PATCH | /contacts/{id} | Update status, custom fields | contacts.write |
| GET | /lists | List custom lists with counts | lists.read |
| POST | /lists/{id}/contacts | Add contacts to a list | lists.write |
| GET | /groups | List saved Telegram groups | groups.read |
| GET | /conversations | List inbox conversations | inbox.read |
| GET | /conversations/{id}/messages | Message history | inbox.read |
| POST | /messages | Send a message | messages.send |
| GET | /campaigns/dm | List DM campaigns | campaigns.read |
| POST | /campaigns/dm/{id}/start | Start / resume a DM campaign | campaigns.write |
| POST | /campaigns/group | Create a group campaign | campaigns.write |
| GET | /templates | List message templates | templates.read |
| GET | /personalities | List AI personalities | templates.read |
| GET | /tickets | List tickets | tickets.read |
| POST | /tickets | Create a ticket | tickets.write |
| POST | /reminders | Create a reminder | tickets.write |
| GET | /analytics/summary | Aggregated KPIs | analytics.read |
| GET | /analytics/activity | 7×24 inbound activity heatmap | analytics.read |
| GET | /workspace/usage | Plan usage and API quotas | workspace.read |
MCP server
TeleBoost runs a hosted MCP server so any MCP-compatible AI — Claude, ChatGPT, Cursor, Zed, and automation tools like n8n and Make — can work with your pipeline directly.
MCP endpoint: https://mcp.teleboost.app/mcp 1. Copy the URL from Settings → Developers → Connected AI apps 2. Add it as a custom connector in your AI tool 3. Authorize via the TeleBoost consent screen (OAuth 2.1 + PKCE)
The server exposes tools that mirror the API: search_contacts, get_conversation, create_ticket, send_message, start_campaign, get_analytics_summary, and more. Tools outside a connection's granted scopes are never exposed.
Webhooks
Register an HTTPS endpoint under Settings → Developers → Webhooks. Each delivery carries an X-TeleBoost-Signature header — an HMAC-SHA256 of the body with your endpoint secret. Verify it before trusting the payload.
import hmac, hashlib
def verify(body: bytes, header: str, secret: str) -> bool:
expected = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, header)Deliveries retry with exponential backoff for up to 24 hours; endpoints that keep failing are auto-disabled with an alert. Available events:
Rate limits
Limits are per plan and returned on every response via X-RateLimit-* headers. A 429 includes Retry-After.
| Plan | Per minute | Per day | Sends / hour |
|---|---|---|---|
| Pro | 120 | 10,000 | 30 |
| Business | 300 | 50,000 | 100 |
Message sends also respect each account's own safety quota — the hourly API cap is in addition to, not instead of, those limits.