Bots: how to create and connect one
What a bot is in Syncra, how to create one, get an access token and send a first message from your own program.
A bot is a workspace member that a program controls instead of a person. It is in the member list, belongs to channels and posts under its own name. Teams use bots so that their own services post about builds, errors and orders in channels, and so that a program can answer commands and react to what happens in the workspace.
Workspace owners and admins create and configure bots. Other members see the list of bots but not their settings or secrets.
How to create a bot
- Open the workspace settings and go to the Bots tab.
- Press New bot.
- Fill in Name. Description and avatar URL are optional.
- Press Create bot. The page of the new bot opens right away.
If you turn on AI responses on the bot page, the bot answers with the built-in AI when someone mentions it or writes to it in direct messages. Turning it on also shows the System prompt (optional) field, where you describe how the bot should answer. A bot that only posts messages from your program does not need AI responses.
How to get a token
- On the bot page, find API tokens and press Create token.
- Enter a Token name and confirm. The Token created window opens.
- Copy the token right away. It starts with
skb_and is shown once. Afterwards the bot page shows only its first characters, and nobody can recover the full token. If you lose it, create a new one. - Press Done.
A token belongs to one bot in one workspace. If a token leaks, press Revoke on its row in the API tokens list. A revoked token stops working at once.
How to add the bot to a channel
A bot sees and replies only in channels it has joined. On the bot page, in the Channels section, pick a channel in the Add to channel list and press Add. A bot can also join a channel by itself through the API, but only a public one.
The first message
From your program, send a request with the token and the id of the channel:
curl -X POST "https://ai-syncra.ru/api/bot/v1/messages" \
-H "Authorization: Bearer skb_..." \
-H "Content-Type: application/json" \
-d '{"channelId":"<channel id>","text":"Build 142 passed"}'
The answer {"ok":true,"messageId":"...","deduplicated":false} means the message is posted. To find a channel id, send GET /api/bot/v1/channels: it lists the public channels of the workspace and every channel the bot is in. The Bot API reference, linked at the end of this article, describes the other requests.
What a bot can and cannot do
- It can: write and edit its own messages, reply in threads, read the history of channels it belongs to, start direct messages, read tasks, comment on them, change a task’s assignee, due date, priority and status, and mark tasks as completed.
- It cannot, through this API: create tasks or knowledge base pages, add reactions, search, or list workspace members.
- A bot belongs to one workspace. You cannot install one bot into several workspaces.
How to switch a bot off or delete it
On the bot page, turning off the Bot enabled switch stops the bot and keeps its settings. Delete bot removes it together with its tokens, webhooks, subscriptions and commands.
Read next
Updated: