SectionBots

Bots

Learn what a Syncra bot is, who can create one, how to get its key and what it can do through the API.

A bot is a workspace member that your program controls. Create one when you want your services to post about builds, orders and errors, answer messages or update tasks without a person doing it. A workspace owner or admin creates the bot and issues its key in the workspace settings, on the Bots tab.

What a bot is

  • A bot is a real member. It shows up in the member list and in channels, posts under its own name and avatar, and carries a BOT badge next to its name.
  • A bot belongs to one workspace. You cannot install one bot into several workspaces. Each workspace gets its own.
  • A bot sees messages and posts only in the channels it has joined.
  • Your program controls the bot with a key. The key starts with skb_, and your program sends it in a header of every request.

Other members can see the list of bots, but not the keys or other secrets. On the Bots tab they see the note Only workspace owners and admins can manage bots.

Create a bot

  1. Open the workspace settings: the gear icon Workspace settings next to the workspace name in the left sidebar.
  2. Go to the Bots tab. Its direct address is https://ai-syncra.ru/w/<workspace-slug>/settings/bots.
  3. Click New bot.
  4. Fill in Name. You can leave Description (optional), Avatar URL (optional) and System prompt (optional) empty.
  5. Click Create bot. The new bot’s page opens right away.

The AI responses switch lets Syncra’s built-in AI reply as the bot: the bot then answers when someone mentions it with @ and when someone writes to it in a direct message. Leave it off if your own program writes the bot’s messages through the API.

What is on a bot’s page

Section What it is for
Profile Name, description, avatar, the Bot enabled switch, the Delete bot button
API tokens Keys for the bot API
Incoming webhooks An address that accepts text in one request: incoming webhooks
Channels The channels the bot is a member of
Slash commands Commands that members run from the message field: slash commands
Task runner A built-in demo agent. Your program does not need it
Event subscriptions Requests to your address when something happens in the workspace: event subscriptions

Get a key

Syncra’s interface calls the key an API token.

  1. On the bot’s page find the API tokens section and click Create token.
  2. In the Create API token dialog fill in Token name. Name it after the system that will use it.
  3. The Token created dialog shows a key that looks like skb_.... Copy it right away. Syncra will not show it again.
  4. Click Done.

What to know about a key:

  • Syncra shows the full key once. After that the list of keys shows only its first 12 characters. A lost key cannot be recovered, so issue a new one.
  • A key belongs to one bot and one workspace. Requests made with it see only that workspace.
  • A bot can have several keys, for example one per service of yours.
  • The Revoke button in a key’s row turns it off at once. Requests with a revoked key get a 401 response. A revoke cannot be undone.
  • A key has no expiry date. It works until it is revoked and while the bot is enabled.

Store the key like a password: in your service’s secrets, not in code and not in a repository.

Add the bot to a channel

On the bot’s page, in the Channels section, pick a channel in the Add to channel field and click Add. From then on the bot reads the channel and can post in it.

A bot can join a public channel on its own with POST /channels/:channelId/join. A private channel is different: an owner or admin has to add the bot through this section.

Check the key

To check that a key works, call GET /me. It returns the bot that owns the key.

curl "https://ai-syncra.ru/api/bot/v1/me" \
  -H "Authorization: Bearer skb_..."

Response 200:

{
  "botId": "5f0c2a7e9b1d4c3a8e6f1a2b3c4d5e6f",
  "userId": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "name": "Deploy bot",
  "workspaceId": "0f1e2d3c4b5a69788796a5b4c3d2e1f0",
  "workspaceSlug": "acme"
}

A 401 response with the body {"error":"Unauthorized"} means the key was not copied in full, was revoked, or the bot is disabled.

What a bot can do through the API

What Where it is described
List channels and join a public channel Messages and channels
Post a message, reply in a thread, edit or delete its own message Messages and channels
Read the history of a channel it is a member of Messages and channels
Open a direct chat with a member and write in it Messages and channels
Attach a file to a message Messages and channels
Read tasks and projects, comment, change the assignee, due date, priority and status, complete a task Tasks and projects

The bot API has no way to create tasks or knowledge base pages, add reactions, pin messages, search, list members, start calls or download files. The page What exists and what does not lists every limit.

Disable or delete a bot

  • Turning off the Bot enabled switch in Profile stops the bot and keeps its settings. A disabled bot does not reply and does not send events, and requests with its keys get 401.
  • The Delete bot button removes the bot together with its keys, webhooks, subscriptions and commands. The messages it sent stay.

Where to go next