Sinatra Docs
Configuration

Telegram

Link your Telegram account, then message Sinatra's bot to start a task and follow it in the task's own topic.

Message @SinatraDevBot in Telegram and Sinatra works in a topic of your chat with it: it answers questions, asks back when the request is vague, and changes code when you ask for it, opening a pull request like any other task. Telegram is available on every plan. There's nothing to connect: it's on in every workspace until an owner or admin turns it off.

Set up

  1. Link your Telegram account. In Settings → Linked accounts, select Link Telegram and sign in with Telegram on the page that opens. A Sinatra account can link one Telegram account, and a Telegram account can be linked to only one Sinatra account; to switch, Unlink first. Linking from a workspace's settings sends your new requests to that workspace.
  2. Open the bot. Once you're linked, the same row has an Open @SinatraDevBot button, or go to t.me/SinatraDevBot. Telegram's Start button sends /start, which gets a one-line welcome and starts no task.

If you message the bot before linking, it replies with a link: "Link your Sinatra account to continue". The link asks you to sign in to Sinatra first if you aren't, then goes through the same Telegram sign-in. The reply says the bot didn't run the message that prompted it, so send your request again once you're linked. Several messages within a minute get one reply between them; a message after that gets its own.

Linking an account doesn't grant access: you still need to be a member of a workspace that has Telegram on.

Sinatra works in direct messages only. If someone adds the bot to a group, it posts "Sinatra works in direct messages only. Message me privately to start a task." and leaves.

Which workspace your requests go to

A Telegram message doesn't name a workspace, so your link decides. New requests go to:

  • the workspace shown under New requests go to in Settings → Linked accounts, as long as you're still a member there and Telegram is on there;
  • otherwise, the one workspace you belong to that has Telegram on.

If you belong to several workspaces with Telegram on, choose one from that row's list. When there's nowhere to send a request, the bot starts nothing and replies with the reason:

  • you belong to several workspaces with Telegram on and haven't chosen one: a link to choose one in Settings → Linked accounts;
  • Telegram is off in your chosen workspace, your only one, or your sole other workspace when the choice is inactive or unavailable: "Telegram is turned off in" that workspace, asking you to get an owner or admin to turn it on in Settings → Integrations;
  • you aren't a member of any workspace: "You're not a member of a Sinatra workspace yet", asking you to get a workspace owner to invite you;
  • anything else, such as an inactive workspace or several with Telegram off and none chosen: "None of your workspaces can take Telegram requests right now", with a link to the dashboard.

A task's topic stays with its workspace. New requests go to only decides where new requests from the main chat go: if you switch it, replies and Stop presses in your older topics still reach their tasks, as long as you're still a member of the workspace they're in and Telegram is still on there. A topic from a workspace you've left gets "I don't know the task in this topic, so I didn't start anything", even if your remaining workspace has Telegram off; Stop says the task isn't in any of your workspaces. If you have no memberships at all, both instead say you aren't a member of a workspace. Request-workspace notices above apply to new requests: main-chat messages, unmatched main-chat replies, and topics you opened, not to an unknown task's topic.

Turn Telegram off for a workspace

The Telegram card in Settings → Integrations shows whether the workspace takes Telegram requests. An owner or admin can Turn off or Turn on Telegram there; other members see whether it's on but can't change it.

With Telegram off, messages from members start nothing in that workspace, and replies and Stop presses in its task topics are refused. Tasks that are already running keep running and still post to their topics, so stop them from the dashboard if you need to. Members' choice of workspace is kept: their New requests go to row says Telegram is turned off there, and their new requests go to their one other workspace with Telegram on, if they have exactly one. If several others have it on, the bot asks them to choose; if none does, it tells them Telegram is turned off there and to ask an owner or admin to turn it on.

Start a task

Send your request in the main chat with the bot. Each request there is a new task. Sinatra opens a topic for it, named after the task, and works there. In the main chat it posts a Started notice that names the topic and ends with an Open the task link to the task's page in the dashboard.

You can also open a topic yourself and send the request in it. Sinatra renames the topic after the task and works there, with no Started notice.

Sinatra reads the text of your messages and the captions on media. It can't read photos, voice notes or files; the agent is told when a message carried one, so describe what's in it.

Problems with billing or model access get a reply in the task's topic. Billing works the same as for any other task: Telegram tasks need model access, count against your plan's agents-at-a-time limit, and wait when it's reached.

Choosing a repository

A Telegram message doesn't come with a repository. Sinatra picks one in this order:

  • If your message contains repo: owner/name, it uses that repository. It must be connected to the workspace.
  • If the workspace has exactly one repository and it isn't empty, it uses that one.
  • Otherwise the agent chooses from the workspace's connected repositories when it needs code, based on what you asked. Name the repository in your message if it could be ambiguous.

A request that doesn't need code, such as a question, can be answered without checking out a repository at all. Until a repository is chosen, the dashboard shows the task's repository as Repository not chosen yet.

In the topic

Each agent run gets one status message in the task's topic, edited in place. It shows the task's name, then Working…, Waiting for a free agent slot, Waiting for you, Done, Stopped or Failed, and a link to each pull request the task opened. Failed carries the reason when it's one you can act on. Once the agent hands back, the status reads Waiting for you, including after it opens a pull request; Done means the task has finished, for example after its pull request merged. A task waiting for a free agent slot, because the workspace is at its agents-at-a-time limit, reads Waiting for a free agent slot, with a Stop button that takes it out of line.

While the status reads Working…, it carries a Stop button and the topic shows Sinatra typing. Typing shows only then, never while a task waits. The agent posts its answer, question or plan as messages in the topic. When a later agent starts, Sinatra posts a new status message below your latest message and deletes the previous one. Telegram doesn't let a bot delete a message older than 48 hours, so an older status message stays where it was, showing how that turn ended.

Replying

Send a message in the task's topic to continue the task: a follow-up, an answer, or the go-ahead on a plan. In the main chat, a Telegram reply to a task's Started notice continues that task too. A message in the main chat that isn't a reply starts a new task.

A message sent while the agent is running doesn't reach the running agent. Sinatra replies in the topic that it will pick the message up once the running agent finishes, and the message waits and starts the next agent once the running one hands back, the same as for a task started from the CLI, MCP or API. See Steering a run.

Once the task has opened a PR, leave code feedback on the PR, where Sinatra picks it up as review rework.

Stopping

Press Stop on the status message, or send stop on its own in the task's topic. Pressing Stop shows "Stopping…", and the status changes to Stopped. If nothing is running, Sinatra answers "Nothing was running; the task is idle." and leaves the task as it is. When it refuses a press, for example because Telegram is turned off for the task's workspace, the answer says why.

Stopping keeps the task, so send a message in its topic to continue. Messages you sent during the run you stopped are dropped, not run afterwards: Sinatra posts one message in the topic that quotes the start of each one it dropped, so you can send again the ones you still need. You can also stop a Telegram task with Stop in the Running list on the dashboard's overview, with sinatra stop <task-id>, or with the stop_task MCP tool or the HTTP API.

Restarting

Telegram has no restart command: restart in a topic is an ordinary message to the agent, and a Telegram task's page has no Restart button. To start over, send a new request in the main chat.

Unlinking

Unlink in Settings → Linked accounts removes your Telegram link. Messages from that Telegram account no longer act as you, and the next one gets the link prompt.