Bots and webhooks

Bots are automated members of a space. They answer slash commands, post messages with buttons and menus, open small forms and can take over routine work such as welcoming new members or posting news. Coviqo knows three kinds:

Recognising bots#

• Messages of bots carry a BOT badge next to the name. Messages from an incoming webhook show the webhook's own name and picture with an APP badge.
• Bots that use artificial intelligence are marked with the AI label on every message, as the EU AI Act requires.
• Bots are not people: they cannot sign in and they don't count as members or seats of your plan. You can send some bots direct messages (see Direct messages with bots).

Bots in this room#

The room info shows Bots in this room: every bot that can see the room, who operates it, where its server is, a link to its privacy information, and what it reads here – for example "reads all messages in this room", "reads files, notes and tasks", "sees who is online", "can listen in voice" or "receives meeting transcripts". A bot that may not write in the room is marked "does not write here".

In a voice room, a bot that listens is shown to everybody with Bot is listening, and bots appear in the participant list with the BOT badge. In a meeting, Bot receives transcript tells you which bots get the finished transcript and summary.

Using bots#

Slash commands#

Type / in the message field. A list of Commands from the bots in this room appears, each with the bot's name and a short description. Choose a command and add its options as name:value. Put values with spaces in quotes:

/poll question:"Lunch today?" options:"Pizza; Pasta; Salad" hours:2

The list explains which type each option expects (text, whole number, yes/no, @person, room or role) and tells you before sending if something is missing or not valid. If the bot sets limits, you see the allowed range next to the option – for example 1–10 for a number or ≤ 100 chars for a text – and a hint such as "days" must be at most 7 if a value doesn't fit. You only see commands if you are allowed to use bots in the room and the bot can see and write in it.

Some options suggest values while you type (marked with a small magnifier in the option list). As soon as you start typing the value, a list of Suggestions appears above the message field. Pick one with the arrow keys and Enter or Tab, or click it; Escape closes the list. The value is filled in for you (in quotes if it contains spaces). Some suggestions have a short second line with details. If the bot is slow or offline, simply no suggestions appear – you can always type the value yourself.

For a room option, a list Rooms for … with the rooms of the space appears as soon as you start typing its value; pick one and it is filled in for you. If the bot only accepts voice rooms or only text rooms, the list only shows those, and you get a hint such as "to" only accepts voice rooms if you enter another room.

Buttons, menus and forms#

Bot messages can have buttons and select menus. Click a button or choose from the menu, and the bot reacts – it may update the message (for example the counts of a vote), post an answer or open a form. A form shows the bot's name at the top ("Form from {bot}"); fill in the fields and click Submit. Some bots first show "{bot} is thinking …" and open the form a moment later – it only appears in the window where you clicked, and a bot can open it only within a minute. Bots use forms for example for reports or applications: what you type goes to the bot.

Some forms ask for files – for example screenshots for a clan application. Drag the files onto the field or click Choose files; the field shows how many files and which size and types are allowed. Each file is uploaded and checked for malware first ("Checking for malware …") – only then can you submit the form. Files that are too large, of a type the bot does not accept or blocked by the virus scan are marked in red; remove them with ×. The files go only to the bot that asked for them: they do not appear in the room's files or in search, and Coviqo deletes them after three days (files of a form you did not send after one day). The bot may keep its own copy – check its privacy information.

Answers only visible to you#

Some answers are marked Only visible to you. Nobody else sees them, and they are not saved: they disappear when you reload the page, and you can Dismiss them earlier. Buttons on such answers work for 15 minutes. Some bots let such an answer disappear by itself after a short time (for example a "Saved" confirmation) – it then also shows Disappears automatically and fades out briefly before it goes (without animation if your system reduces motion). It disappears on all your devices and does not come back.

When a bot needs a moment, you see "{bot} is thinking …" until the answer arrives. If the bot doesn't respond, Coviqo tells you that it could not answer.

Installing and managing bots (space admins)#

You need the Manage bots permission (bots.manage) in the space. Owners and administrators have it.

Installing a bot#

A developer gives you the bot's install link (…/bots/install/<id>), or you find the bot in the bot directory (see below). Opening it shows the install dialog:

1. Choose the space. Only spaces where you may manage bots can be selected; the dialog also shows how many bots the space has and the limit of its plan.
2. Check the permissions the bot asks for. They are grouped like in the role editor, and each one is a checkbox: untick what you don't want to grant. You can only grant permissions you have yourself. Moderation permissions (for example deleting other people's messages or timing out members) show an extra warning.
3. Check the data access. Some access is always included (commands and buttons, the member list with names and roles). Wider access – reading all messages in the rooms the bot can see, reading files, notes and tasks, seeing who is online, listening in voice rooms, receiving meeting transcripts, reading and working on tickets (Read tickets, Write and change tickets – see Tickets), opening tickets in the name of any member (Open tickets on behalf of members), replying to tickets in the name of their reporter or participants (Reply to tickets on behalf of members), managing rooms and room permissions (Manage rooms and room permissions), seeing who accepted or declined events (Event responses), changing team settings (Manage team settings), applying to teams or answering events in the name of any member (Apply to teams on behalf of members, Answer events on behalf of members) – has to be ticked one by one. Listening in voice rooms needs Community Pro or higher, meeting transcripts need Business or Enterprise; if your plan doesn't include them, they are shown but cannot be ticked.
4. Read who operates the bot, where its server is located, its privacy information and whether it uses AI. An own bot receives the content it works with in readable form, so only install bots you trust.
5. Click Install.

The bot joins the space with its own role "Bot: <name>". Nobody can grant a bot the right to administer the space, manage roles, billing or the audit log, or to manage other bots.

Changing what a bot may do#

Open Space settings › Apps & integrations › Bots and select the bot:

• Overview: profile, operator, commands, who installed it.
• Permissions: tick or untick the permissions of the bot's role at any time – again only permissions you hold yourself.
• Rooms: allow or deny permissions for single rooms, just like room permissions for a role. To keep a bot out of a room, deny View room there.
• Data access: approve or withdraw wider data access. For meeting transcripts, also choose the rooms whose meetings the bot may receive.

The bot's role appears in the role editor with the note "Managed by a bot"; it cannot be assigned to people, edited or deleted there. You also cannot kick or ban a bot – pause or remove it instead.

Letting a bot assign roles#

Some bots (for example a clan bot that mirrors ranks from another platform) ask for the data access Assign roles. After you approved it under Data access, open the tab Assign roles on the bot page and tick the roles the bot may give to and take from members. The list only offers roles below the bot's own role – drag the bot role above them under Roles first. Roles that can kick, ban, mute or invite people, and roles with special rights such as discussion lead or soundboard, are only allowed with the switch Allow roles with moderation permissions – a warning reminds you that the bot can then hand out moderation powers. Roles with admin rights (for example Administrator or Manage space) are only allowed with the switch Allow roles with admin rights, and only if they are below the bot role. Only the space owner and administrators can turn it on or tick such roles; you confirm a warning first, because the bot can then make anyone an admin – including your co-admins – or take admin roles away. The bot can give and take roles from every member, the owner included; ownership itself is not a role and the owner always keeps all rights. You need the permission Manage roles to change the list. Every change the bot makes appears in the audit log with the bot as actor.

Who joined through which invite#

Under Space settings › Invites & joining › Invites every invite shows how many people joined through it and are still members (N joined (active)). The member list shows below the join date how somebody joined – for example Via invite aB3dE7 from Ada, Via the link /yourname or Via single sign-on. Only people who may invite or manage members see this. Members who joined before this was introduced show nothing.

Letting a bot manage rooms#

With the data access Manage rooms and room permissions and the permissions Create rooms / Manage rooms a bot can create, edit, archive and delete rooms and categories – for example a clan bot that opens a voice room per squad – and set room permissions. It can only change permissions for roles below its own role and only grant what it may do itself; admins and other bots are never affected. A bot creates at most 50 rooms and categories per day. With Move members it can also move people to another voice room or disconnect them, but never people with a higher role. Everything appears in the audit log with the bot as actor.

Tickets, events and forums#

• A bot can open a ticket for you after you used one of its buttons or forms (for example Report). With the data access Open tickets on behalf of members, approved by an admin, it can also open tickets for any member – for example from a form on your clan website. Such tickets show Created by {bot} on behalf of {name}, and the list shows via {bot}. You get the usual ticket notifications. Bots can also attach files to tickets; the usual size limits, storage and virus scan apply. A bot can also hand a ticket it opened for itself over to you later (for example an older request from the website); the ticket then shows the same note, and its history shows Reporter: {bot} → {name}. A bot with the right to work on tickets – or the bot that opened the ticket – can correct the description; the history then shows Description edited. A bot can also post a reply in your name on a ticket you opened or follow – right after you used one of its buttons or forms, or with the data access Reply to tickets on behalf of members (for example to pass on your e-mail answer). Such a reply counts as yours and shows via {bot}; the team is notified as usual.
• With Event responses a bot sees who accepted, declined or answered "maybe" to events in rooms it can see. It can cancel events it created, or any event if it has Manage events. It can also move an event to another room – with Manage events in the old and the new room (its own events: Create events in the new room); answers, tickets and reminders stay, exactly as when a person moves it (see Calendar and events).
• A bot can apply to a team or answer an event for you right after you used one of its buttons or forms. With Apply to teams on behalf of members or Answer events on behalf of members, approved by an admin, it can do this for any member – for example from a recruitment form on your website. Such applications and answers show via {bot} – in the application inbox, under My applications and in the participant list of the event. All the usual rules apply (the team must take applications, the event must have free places). You can withdraw an application as usual; if you answer an event yourself, the marker disappears.
• With Manage team settings and the permission Manage teams, a bot can rename space teams, change how people join (open, by application, invitation only) and set the application question. It cannot open a team for everyone if the team (or a team above it) gives room permissions the bot does not have itself.
• In forum rooms bots write posts and replies like people, with the same permissions and tag rules.

Pausing and removing#

• Pause stops the bot in this space immediately; its commands disappear. Resume it whenever you like.
• Remove takes the bot out of the space together with its role. Its earlier messages stay.

Every installation, change and removal is recorded in the activity feed for moderators and in the audit log. What a bot does itself – for example deleting a message or timing out a member – appears there with the bot as the one who did it.

Bot directory#

Bot directory (from Space settings › Apps & integrations › Bots or …/bots/directory) lists bots that the operator of your Coviqo server has reviewed. Search by name, filter by category and open a bot to see its description, screenshots, the permissions and data access it asks for, who operates it, where its server is and its privacy information. A Verified badge means the operator checked who runs the bot. Install opens the usual install dialog. Report bot sends a report to the operator's Trust & Safety team.

Bots that are not in the directory can still be installed with their install link.

Direct messages with bots#

You can write to a bot that is installed in one of your spaces, or to a bot from the directory: open the bot in Bots in this room and choose Send message. Conversations with bots show the BOT badge in your direct messages.

• A bot only answers after you have written to it, or when you used one of its commands or buttons. It never starts a conversation on its own.
• A bot only sees conversations it takes part in – never your other messages.
• Block bot in the conversation stops the bot from writing to you, and you can unblock it at any time.
• Bots can't be added to group conversations.

Bots in voice rooms#

With Community Pro or higher, bots can join voice rooms – for example to play music or read out announcements. They appear in the participant list with the BOT badge.

• A bot can only hear the room if an admin approved "Listen in voice rooms" for it. While such a bot is in the room, everybody sees Bot is listening.
• A bot can only speak where it is allowed to speak, like people. Bots never use video or screen sharing.
• Bots never join meetings or direct calls. In rooms that external guests can see, bots may only join if a room manager switched on Bots may join despite external guests in the room settings under Voice & media › Audio & video.

Coviqo bots#

Coviqo bots are set up under Space settings › Apps & integrations › Bots › Coviqo bots. You need the Create Coviqo bots permission (bots.create) or Manage bots. Each Coviqo bot is its own bot with a name you can change, a picture, its own role and a switch to turn it off. It counts towards the bot limit of your plan. Its role only gets permissions you hold yourself.

Incoming webhooks#

An incoming webhook lets another tool post messages into a room – for example "Build 128 succeeded" from your build server. Set them up under Space settings › Apps & integrations › Bots › Webhooks (Manage bots needed):

1. Click Create webhook, choose the room, give it a name and optionally a picture.
2. Copy the address. It is shown only once – treat it like a password, because everyone who has it can post into the room.
3. Enter it in the other tool. The tool sends a message as JSON, for example {"content": "Build 128 succeeded"}.

Messages appear with the webhook's name and picture – also in notifications when a webhook message mentions you. In the background they are posted in the name of the person who created the webhook, so that person must be allowed to write in the room. If they leave the space or lose that right, the webhook stops working until another admin clicks Take over. Generate new URL creates a new address and makes the old one invalid immediately; you can also turn a webhook off or delete it. You can only edit or delete webhooks of rooms you can see yourself.

Plan limits#

The operator of your server may set different limits. When a limit is reached, you can't install or create more until you remove one or upgrade (see the chapter Plans and billing).

For developers#

Everyone with a regular account can build own bots under Settings › Developer:

• Create bot: you get a token (shown once, can be rotated) and a public key.
• Interaction URL: the https address of your bot where Coviqo sends commands, button clicks and form submissions. Coviqo checks it when you save it: your server has to answer a signed test request and reject one with a wrong signature.
• Details: operator, server location, privacy policy link and whether your bot uses AI – shown to admins in the install dialog.
• Permissions and data access your bot asks for, and the install link. Switch on Anyone with the link may install to let others install it; otherwise only you can.
• Installations: where your bot is installed, with a warning where an admin granted fewer permissions than requested.
• Events: an https address that receives signed events (new messages, members joining, tasks, file uploads and more), which events you want, and a log of the last 100 deliveries with Send again. Coviqo tests the address when you save it. If deliveries keep failing for a day, Coviqo stops them and tells you; Enable again restarts them. Instead of an address, your bot can also connect to the WebSocket gateway.
• Bot directory: submit your bot with a short and a long description, categories and screenshots. The operator reviews it; you get a notification when it is approved or rejected. Changing permissions, data access or addresses sends the listing back to review.

Developer mode: finding IDs#

Bots address spaces, rooms, people, roles and everything else by ID. Switch on Settings › Appearance › Developer mode (off by default, saved with your account) to see them:

• Copy ID in the menus (right-click or …) of spaces, categories, rooms, messages, people (member list, chat, profile …), teams, events, meetings, tasks, notes, files, folders, tickets and direct conversations. In Space settings › Roles right-click a role; in Invites the fingerprint button copies the invite ID.
• For developers boxes with the IDs and a copy button: room settings › General (room, space and category ID), space settings › Overview (space ID), Roles (role ID and the mention <@&id>), the installed bot's Overview (application, installation, bot user and role ID) and every incoming webhook (webhook ID, its URL without the secret, room ID).

Without developer mode none of this is shown. Settings › Developer always shows, per bot, IDs and endpoints – application ID, bot user ID, its mention <@id>, the API base URL, the gateway and the OpenAPI file of this installation (important when Coviqo runs on your own server) – plus links to rate limits and error codes, and for each installation the space and installation ID. This instance lists the same URLs and your own user ID before you create a bot. The public key checks interactions and events; a new token is created under Keys and token.

Login apps (Sign in with Coviqo): in the same area you can register a website or app that lets people sign in with their Coviqo account – you get a client ID and secret (see Integrations › Sign in with Coviqo; the developer reference has a chapter about it).

The developer reference – token interface, commands, buttons, forms, signatures, events and limits – is public on the website at /developers (English, with an OpenAPI 3.1 description for Postman / Insomnia and the example SDK as download; the developer area links to it). More internals are in the Technical Documentation (chapter Bot platform) and in docs/BOTS.md. A small Node example lives in examples/bot-sdk.