Build on Telestars.

Quickstart

Choose REST for your application, or MCP for an AI assistant. Both access the same agency and share its usage limits.

1. Create your key

   Open Settings → Developer → API Keys, or Billing → API Key. Name the key, choose its expiration and keep only the permissions you need. Start with Read bots and Read statistics.

2. Save it on your server

   Copy the key once into your server’s secret manager as TELESTARS_API_KEY. It cannot be shown again. Never put it in frontend code, a URL or an AI prompt.

3. Read your bots

   Copy the Base URL shown in your API Keys panel. Send your key in the Authorization header and use a returned bot ID for reports or actions.

curl --fail-with-body \
  --header "Authorization: Bearer $TELESTARS_API_KEY" \
  "https://telestars-backend.onrender.com/api/v1/bots?limit=50"

{
  "result": {
    "data": [
      {
        "id": "<BOT_ID>",
        "display_name": "My creator",
        "bot_username": "my_creator_bot"
      }
    ],
    "next_cursor": null
  },
  "request_id": "<REQUEST_ID>",
  "usage_recorded": true,
  "billing": {
    "status": "included",
    "charged_usd": 0
  }
}

Build a reporting dashboard

Read each bot’s summary and daily history for your date range, then combine the results in your dashboard. Revenue is returned in Stars. Missing historical evidence is returned as null, not invented.

curl --fail-with-body --get "https://telestars-backend.onrender.com/api/v1/analytics/summary" \
  --header "Authorization: Bearer $TELESTARS_API_KEY" \
  --data-urlencode "bot_id=<BOT_ID>" \
  --data-urlencode "from=2026-10-01" \
  --data-urlencode "to=2026-10-14" \
  --data-urlencode "timezone=Europe/Paris"

MCP & OAuth

Connect an MCP client that supports Streamable HTTP and OAuth with dynamic client registration. Your permissions control exactly which tools it can use.

1. Copy the server URL

   Open Settings → Developer → MCP. Copy the MCP server URL and add it as a custom connector in your AI tool.

2. Authorize your agency

   Sign in to Telestars, select your agency and review the requested permissions. Write permissions are off by default. The client registers automatically; no client secret is required.

3. Ask your first question

   Try: “Which bots can I access?” Then ask for a report over a specific period. Revoke the connection at any time in Connected tools.

https://telestars-backend.onrender.com/api/mcp

codex mcp add telestars --url "https://telestars-backend.onrender.com/api/mcp"
codex mcp login telestars

Authentication & permissions

Every key and OAuth connection belongs to one agency. Only agency owners and admins can create or revoke access. A key never grants access to another agency, even when a bot or conversation ID is supplied.

Bot settings & media

Use separate permissions for bot settings, Creator Information and Voice Presets. Send only the fields you want to change inside changes; omitted fields keep their current values.

curl --fail-with-body --request PUT "https://telestars-backend.onrender.com/api/v1/bots/configuration" \
  --header "Authorization: Bearer $TELESTARS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"bot_id":"<BOT_ID>","idempotency_key":"<NEW_REQUEST_UUID>","changes":{"delivery_speed":"fast","allow_standard_emojis":true}}'

Bot settings updates use the app’s validation. They cannot enable or disable AI, change the Telegram identity or set provider credentials. Creator Information uses its own endpoint; changing it does not rewrite Voice.

Create a custom Voice Preset with its name and prompt, then select it through the activation endpoint. Built-in presets cannot be edited or deleted. Selecting a voice does not enable AI or send a message.

Upload media in three steps

1. Prepare the files

   Call /gallery/uploads/prepare with one bot and 1–10 files. Keep the returned upload_request_id and complete_request_id. Each signed upload URL expires after 10 minutes.

2. Upload the file bytes

   From your own application, PUT each file to its signed URL with the returned headers. Do not send your Telestars API key to that URL. MCP prepares and completes uploads; the client transfers the files.

3. Complete and check readiness

   Call /gallery/uploads/complete with upload_request_id and use complete_request_id as idempotency_key, with the same credential. Inspect the receipt after an uncertain outcome. Accepted media may still need Telegram preparation or gallery analysis; check processing-status before delivery.

AI & automation

Separate permissions control AI drafts, conversation processing and the bot’s AI switch. Grant only the capabilities your integration needs.

curl --fail-with-body --request POST "https://telestars-backend.onrender.com/api/v1/ai/replies" \
  --header "Authorization: Bearer $TELESTARS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"bot_id":"<BOT_ID>","message":"Hello!","idempotency_key":"<NEW_REQUEST_UUID>"}'

To process an existing conversation, first list its pending batches, then call /ai/conversations/run with bot_id, conversation_id, batch_id and a new idempotency_key. Read the corresponding request status instead of submitting a second action.

Enable or disable bot AI

Read /bots/ai/status, then change the switch through /bots/ai/activation. Enabling follows the app’s wallet, script and Telegram prerequisites and may resume eligible pending conversations. Human takeovers remain protected. A saved switch does not confirm that a reply was delivered.

curl --fail-with-body --request PUT "https://telestars-backend.onrender.com/api/v1/bots/ai/activation" \
  --header "Authorization: Bearer $TELESTARS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"bot_id":"<BOT_ID>","idempotency_key":"<NEW_REQUEST_UUID>","enabled":true}'

After an uncertain result, read /bots/ai/requests with the same idempotency_key before retrying. Status reads show the saved switch and disabled reason; they do not run readiness checks or probe Telegram.

The reference below covers scripts, steps, Offers, media delivery, albums, conversations, fans, tracking and team reports. Telegram account authentication and managed bot creation are still experimental and are not part of this public reference.

Team management

Use team:members:read to read members, invitations, bot assignments, shifts and schedules. Use team:manage for changes. These permissions are separate from team:read, which only reads performance reports.

Team operations keep the app’s Pro subscription and role checks. Creating an invitation can send the normal invitation email. The invited person must accept it through the usual sign-in flow; API access cannot accept on their behalf.

Removing a member marks their membership as removed, clears assignments and removes agency access. The membership history and user account are preserved. Changing the role cannot restore a removed membership. Inspect the action receipt before retrying.

Pricing & limits

All keys and MCP connections share one rolling 60-second allowance for the agency, based on its highest active subscription. Adding keys does not multiply the limit.

At capacity, follow Retry-After. There is no paid overage. Large agencies can request a higher limit after capacity validation, without an API surcharge.

Reports require one bot, at most 90 inclusive days and at most 100,000 deliveries. Split larger ranges and combine the results in your application.

Pagination, retries & errors

Page through results

Lists return result.data and result.next_cursor. Pass the cursor as after until it is null. Each page uses one call. UUID pagination is not chronological order; sort script steps by step_index and album items by position.

Retry safely

Create one UUID idempotency_key for each new write or AI action. Reuse the same UUID and identical parameters after a network failure. Never use a new UUID to retry an uncertain send. Read its request receipt first; a queued action is not proof of delivery.

MCP tool failures may arrive with HTTP 200 and isError: true. Inspect the tool result, including retry_after_seconds for capacity errors. Keep request_id when contacting support. Never share your API key.