An app brings a program into an Otag server. People run its commands, press the buttons on the cards it posts and fill in its forms, and the app answers: with a card in the channel, a reply only that person sees, a form, or a change to a card everyone sees. Execute's CS2 matches are an app like this, built on exactly what this page describes.
An app is yours to build in any language. It talks to Otag over HTTPS and, if you like, a WebSocket: Otag sends it what people do, and it calls Otag's API as itself.
- Building with an AI coding agent? Give it the Otag app skill: one file that teaches it everything below.
- Want to start from working code? Download the example app (TypeScript, no packages needed to run it), or read its README.
Quick start
- Make the app. In Otag, open Settings → Developer → New app. Otag shows the app's token once: copy it and keep it secret. On the app's page you also find its app ID and its signing secret.
- Choose what it asks for. Under "It asks to", turn on what the app needs where it is added, such as View channels and Send messages, and save.
- Run it. Start the example app with your app's ID and token, or your own code. It can connect to Otag's gateway, so it runs on your own computer with no address of its own.
- Add it to your server. Open Server settings → Integrations, paste the app ID under "Add by link or ID", and add it. You need Manage Server there.
- Use it. Type
/in one of the server's text channels: its commands are listed.
How apps work
An app is a member. It has an account of its own, which wears an APP tag and joins every server it is added to. There it holds a role of its own, named after the app and ranked just below the highest role of whoever added it (at the top when the server's owner or an administrator adds it), so it can never act on anyone they couldn't. It gets the permissions it asks for, or fewer when the person adding it turns some off. Nobody else can hold that role, and nobody can take it from the app or delete it. An app is not kicked or banned: it is removed in Integrations. It makes no servers, friends or conversations of its own.
People use it in three ways. They run its commands (type /, or pick one from the composer's + menu), press the buttons and pick from the menus on its cards, and fill in the forms it opens. Each of these reaches the app as an interaction, which it answers within three seconds.
Two secrets. The token (otb_…) is the app: whoever has it acts as the app, so keep it on your server and never in a page or an app people download. The signing secret proves that something came from Otag: Otag signs every interaction it posts to the app with it.
Two ways to hear interactions. Give the app an interactions address (https) and Otag posts each interaction there, signed. Or leave the address empty and connect to Otag's gateway (a WebSocket) as the app: Otag sends the interactions there instead. The gateway needs no address of its own, so it suits your own computer; an address suits an app on a server. With an address set, Otag uses only the address.
Who may use it. In each server, the people managing it choose who may run the app's commands (everyone, or some roles). Pressing a card's button takes only seeing the channel; a button can also be shown to some people alone. Every interaction tells the app whether the person may use its commands.
It says hello. Whoever adds the app picks a channel for it to introduce itself in, and the app is asked what to post there (see Saying hello).
Making and setting up an app
Everything here is in Settings → Developer, on your app's page.
| Setting | What it is |
|---|---|
| Name | 2 to 32 characters. The app's account is named after it. |
| Icon | The app's picture, on its account and on its cards in the app list. At most 2 MB and 1024 pixels a side. |
| Mark | The app's logo on a see-through ground, shown beside Otag's in its lockup ("Otag × App"). A PNG, WebP or GIF, at most 2 MB and 1024 pixels a side. |
| Description | What it does, at most 400 characters. Shown in the app list and on its card. |
| Colour | #RRGGBB. It edges the app's cards and colours their first buttons. |
| Interactions address | An http or https address Otag posts interactions to. Saving it makes Otag ping it: the app must answer {"type": "pong"} within 5 seconds, or the address isn't saved. Leave it empty to use the gateway. |
| Signing secret | What Otag signs interactions with. New secret makes another; the old one stops at once. |
| Token | Shown once, when the app is made. New token makes another, stops the old one and closes the app's gateway connections. |
| It asks to | The permissions the app asks for where it is added (see Permissions). |
| Anyone can add it | On: anyone who manages a server can add it by its link or ID. Off: only you can. |
| The app list | Ask Otag's admins to list it (see Getting on the app list). |
| App ID | The app's ID, to add it by. To link to adding it: otag://app/<app ID> opens Otag's desktop app on it, and Otag's web app does with ?app=<app ID> after its address. |
You can make up to 10 apps. Deleting an app takes it out of every server; what it posted stays, from "Deleted app".
Calling Otag as the app
Otag's API is at https://api.otag.chat/api/v1. The app sends its token in every request:
Authorization: Bot otb_…
Content-Type: application/json
Bodies and answers are JSON. Every ID is a string. An app may call these, as far as its role in each server lets it:
| What | Endpoints |
|---|---|
| Its servers and their channels, roles and members | GET /state (everything the app's gateway READY holds), GET /guilds/{gid}/members, GET /guilds/{gid}/roles, GET /users/{id} |
| Messages | GET /channels/{id}/messages?before={message_id}&limit=50, POST /channels/{id}/messages {content?, card?, thread_id?, also_in_channel?, reply_to?, reply_mention?, poll?, title?, tag_ids?}, PATCH /channels/{id}/messages/{mid} {content?, card?}, DELETE /channels/{id}/messages/{mid}, GET /channels/{id}/messages/{mid}/thread?before={message_id}&limit=50 (the message and its replies, {root, replies}) |
| Polls | PUT /channels/{id}/messages/{mid}/poll/votes {option_ids}, POST /channels/{id}/messages/{mid}/poll/close |
| Forums | GET /channels/{id}/posts?sort=&tags=&q=&after=&limit=30 ({posts, next?}), PATCH /channels/{id}/posts/{mid} {title?, tag_ids?, pinned?, locked?} |
| Reactions | PUT and DELETE /channels/{id}/messages/{mid}/reactions/{emoji} |
| Pinned messages | GET /channels/{id}/pins?thread_id= (newest pin first), PUT and DELETE /channels/{id}/pins/{mid} (Manage messages) |
| Search | GET /search?q=&channel_id=&author_id=&limit= |
| Channels and categories | POST /guilds/{gid}/channels {kind: "text", "forum" or "voice", announcement?, name, topic?, category_id?, position?}, PATCH and DELETE /channels/{id}, POST /guilds/{gid}/categories, PATCH and DELETE /categories/{id}, PUT and DELETE /channels/{id}/overrides/{role_id} |
| Members | PATCH /guilds/{gid}/members/{id} {role_ids?, nick?}, DELETE /guilds/{gid}/members/{id} (kick), GET /guilds/{gid}/bans, PUT and DELETE /guilds/{gid}/bans/{id} |
| Voice | GET /guilds/{gid}/voice (who sits in which voice room: [{user_id, channel_id, self_mute, self_deaf, server_mute, streaming, camera}]), POST /voice/{user_id}/move {channel_id}, PUT and DELETE /voice/{user_id}/mute, DELETE /voice/{user_id} (disconnect) |
| Itself | GET /apps/{id}, GET and PUT /apps/{id}/commands, GET /guilds/{gid}/apps, POST /guilds/{gid}/leave (takes the app out of that server) |
Anything else answers 403 app_not_allowed. Messages hold up to 4000 characters of markdown, and <@user_id> mentions someone. thread_id replies in the thread under a message of the channel, and also_in_channel: true shows the reply in the channel too; the history leaves out replies that stay in their thread, and each reply carries its thread_id. reply_to answers a message the channel shows, under a quote of it, and reply_mention: true mentions that message's author. poll: {options, multi?} asks a poll, content being the question (at most 300 characters; 2-12 options of at most 100); votes reach you as POLL_VOTE, and a poll can't be edited. In a forum (a channel of kind forum), a message is a post with a title and maybe tag_ids from the channel's forum.tags, and its replies are the thread under it, so thread_id answers it as anywhere. An announcement channel (announcement: true) is a text channel whose @everyone may not write: let your app's role in with an override, or post through a webhook. Words between two bars, ||like this||, are a spoiler, which the apps hide until someone clicks it. A message pinned to its conversation carries pin {user_id, pinned_at}, and pinning writes a line in the conversation that is nobody's words: a message with system {kind: "pin", message_id}, its author being who pinned. Leave such lines alone: they take no reply, reaction or edit. A message people send may be a voice message, with no words and one attachment marked voice: true, with its duration_ms and a waveform, or a sticker, with no words and its sticker_id (and the sticker itself while it exists); neither is edited. The app posts up to 5 messages a second (bursts of 20). The app joins no voice rooms.
Commands
The app sets its commands itself, with its token:
PUT /apps/{app_id}/commands
[
{
"name": "match",
"description": "Open a match",
"description_localizations": {"tr": "Maç aç"},
"menu": true,
"options": [
{"name": "map", "description": "The map", "type": "string", "required": false,
"choices": [{"name": "Mirage", "value": "de_mirage"}, {"name": "Nuke", "value": "de_nuke"}]}
]
}
]
The list replaces the app's commands, at most 50 of them. Set it each time the app starts: it is cheap, and the servers hear of the change.
| Field | Rules |
|---|---|
name |
1 to 32 lowercase letters, digits, - and _, unique. People type /name. |
description |
1 to 100 characters. description_localizations gives it in other languages by code, such as {"tr": "…"}. |
menu |
true lists it in the composer's + menu too, under its description. |
options |
At most 10: {name, description, description_localizations?, type, required?, choices?}, type one of string, integer, boolean, user (someone in the server), channel (one of its channels). choices ([{name, value}]) limits a string or integer to those. |
Otag checks a command before it reaches the app: the person may use the app there, and every option fits its type and choices (422 missing_option and invalid_option otherwise). A list that doesn't fit is 422 invalid_command.
Receiving interactions
At an address
Otag posts each interaction to the app's interactions address as JSON, with two headers:
| Header | What it holds |
|---|---|
X-Otag-Timestamp |
When Otag sent it, in Unix seconds. |
X-Otag-Signature |
sha256= and the hex HMAC-SHA256 of <timestamp>.<body> under the app's signing secret. |
Check both before anything else, on the body exactly as it came: refuse the request (401) when the signature doesn't match or the timestamp is more than five minutes from now. Then answer within three seconds with 200 and the answer as JSON.
import { createHmac, timingSafeEqual } from 'node:crypto';
function fromOtag(secret: string, timestamp: string, signature: string, body: Buffer): boolean {
if (!signature.startsWith('sha256=')) return false;
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const want = createHmac('sha256', secret).update(`${timestamp}.`).update(body).digest();
const got = Buffer.from(signature.slice(7), 'hex');
return got.length === want.length && timingSafeEqual(got, want);
}
When you save the address, Otag sends a ping the same way, which has no person behind it: answer {"type": "pong"}.
Over the gateway
With no interactions address, the app hears interactions on Otag's gateway:
- Open a WebSocket to
https://api.otag.chat/api/v1/gateway(wss://forhttps://). - Send
{"t": "IDENTIFY", "d": {"token": "otb_…"}}. - Otag answers
READY, with the app's servers andheartbeat_ms, then sends the events of those servers as a member gets them, andINTERACTION_CREATEwith each interaction meant for the app. - Answer each one within three seconds:
POST /interactions/{id}/{token}/callbackwith the answer as the body,{type, data?, open?}.
Every frame is {"t": "<TYPE>", "d": {…}}. Otag pings the socket every heartbeat_ms (25 seconds), and most WebSocket clients answer by themselves. To notice a dead connection, send {"t": "PING"} as often and expect {"t": "PONG"}; with none for 15 seconds, connect again. A new connection gets a fresh READY.
What an interaction holds
{
"id": "105372067926376450",
"token": "…",
"type": "command",
"app_id": "105372067926376448",
"guild_id": "105372067704078336",
"channel_id": "105372067725049856",
"user": {"id": "105372067603415040", "username": "alice", "display_name": "Alice"},
"member": {"role_ids": ["…"], "nick": "Ali", "permissions": "3", "can_use_commands": true},
"locale": "en",
"data": {"name": "match", "options": {"map": "de_mirage"}}
}
| Field | What it is |
|---|---|
id, token |
The interaction, and the token that follows it up for 15 minutes (see Follow-ups). |
type |
command, action, form, configure, added or ping. |
user |
Who did it. member is how the server has them: their roles, nickname and permissions there, as a decimal string, and can_use_commands: whether the server lets them use the app's commands. |
locale |
The language their Otag speaks now: en or tr. Answer in it. |
data |
A command: {name, options}, options by name. An action: {action_id, values?, message_id?} (or reply_id? for a button on a reply), with the card's message. A form: {form_id, values, message_id?}. A configure and an added: {}. |
Answering
The answer is {type, data?, open?}:
type |
What happens |
|---|---|
reply |
data: {content?, card?} shows to the person alone, at the foot of the channel, marked "Only you can see this". |
message |
data: {content?, card?} is posted by the app in the channel, for everyone. The app needs View channels and Send messages there. |
update |
For a button or menu: data: {content?, card?} changes the message (or reply) that was clicked. Each part changes only when given, and "card": null takes the card off. |
form |
data is a form (see Forms) that opens for the person. Not as the answer to a form's own sending. |
defer |
Nothing yet: the app follows up later (see Follow-ups). |
open |
data: {url, window?} opens a link for the person. |
pong |
Only for ping. |
Any answer may also carry open: {url, window?}. A link is http, https or steam://connect and steam://run; window: "popup" opens an https address in a small window over Otag, apart from it, for a sign-in.
When the app is not reachable Otag tells the person, and the app's answer isn't used: no address and no gateway connection (503 app_offline), no answer within three seconds (504 app_timeout), or an answer that doesn't fit (502 app_error, or the 422 of what doesn't fit).
Follow-ups
For 15 minutes after an interaction, the app can follow it up with the interaction's id and token alone, no other sign-in needed (once a second, bursts of 20):
| Request | What it does |
|---|---|
PATCH /interactions/{id}/{token}/reply {content?, card?, close_window?} |
Sets or changes the reply the person sees. close_window: true closes a window their Otag opened from that reply, once your sign-in is done. |
DELETE /interactions/{id}/{token}/reply |
Takes the reply back. |
POST /interactions/{id}/{token}/messages {content?, card?} |
Posts in the channel. |
PATCH /interactions/{id}/{token}/message {content?, card?} |
Changes the message that was clicked. |
The pattern for slow work: answer defer at once, do the work, then follow up.
Saying hello
Whoever adds the app to a server picks one of its text channels for the app to introduce itself in, or none. The app then gets an added interaction: channel_id is that channel, user and member the person who added it, and locale their language. Answer with a message, which Otag posts there as the app, or defer and post it within 15 minutes with POST /interactions/{id}/{token}/messages. Anything else is not posted.
The hello is how the server first meets the app, and everyone in the channel sees it: say in a line or two what the app does and how to start, and put the first step on a button. The app is asked only when it may write in that channel, adding it never waits for the hello, and it isn't asked again when its settings there change.
Cards
A message or a reply from an app may carry a card:
{
"color": "#13877B",
"title": "Team A vs Team B",
"status": {"text": "Open · 1 of 10 seated", "tone": "accent"},
"description": "5v5 · Mirage",
"lists": [
{"title": "Team A", "people": [{"user_id": "105372067603415040", "note": "Host"}], "slots": 5},
{"title": "Team B", "people": [], "slots": 5}
],
"actions": [
{"type": "button", "id": "join:b", "label": "Join Team B", "style": "primary"},
{"type": "button", "id": "start", "label": "Start", "style": "success", "users": ["105372067603415040"]},
{"type": "link", "label": "Open in the app", "url": "https://example.com/match/1"}
],
"footer": "Room 3BUGRA"
}
| Field | Rules |
|---|---|
color |
#RRGGBB, the card's edge. The app's colour when left out. |
title |
At most 120 characters. url (http or https) makes it a link. |
description |
Markdown, at most 2000 characters. |
image, thumbnail |
A banner across the top, and a small picture beside the title: http or https (see Pictures). |
status |
{text, tone}: a short line (at most 100) in a tone of neutral, accent (the app's colour), success, warning, danger or live (the app's colour, moving). |
fields |
At most 12 {name, value, inline?}: name at most 64, value at most 512 characters of markdown. |
lists |
At most 4, such as teams: {title?, people, slots?, empty?}. At most 12 people, each {user_id} (someone on Otag, drawn as Otag shows them) or {name}, with a note of at most 32 characters. slots (at most 12) draws the empty places, named empty. |
footer |
At most 200 characters. |
actions |
At most 10, below. |
| Action | Fields |
|---|---|
| Button | {type: "button", id, label, style?, disabled?}: style is primary, secondary (the default), success or danger. |
| Link | {type: "link", label, url, window?}: as links in answers. A link reaches no app: it just opens. |
| Menu | {type: "select", id, placeholder?, options}: at most 25 {value, label, description?}; the choice comes as data.values. |
Every id is unique in the card, at most 100 characters; labels are at most 40. users shows an action to those people alone, and except hides it from them (at most 100 each). A card shows something, and only apps and webhooks post cards. Anything that doesn't fit is 422 invalid_card, saying what. Changing only a message's card doesn't mark it edited.
Buttons need nothing kept between clicks: an id can carry what the app needs to answer it (wave:3, join:b).
Anyone who can see the channel can press a card's buttons. For a button that does what a command does, check member.can_use_commands and answer those who may not with a reply.
Forms
{
"id": "match",
"title": "Open a match",
"submit": "Open",
"sections": [
{"fields": [
{"type": "choice", "id": "mode", "label": "Mode", "style": "segmented", "value": "5v5",
"options": [{"value": "5v5", "label": "5v5"}, {"value": "1v1", "label": "1v1"}]},
{"type": "multi", "id": "maps", "label": "Maps", "min": 1, "max": 3,
"options": [{"value": "de_mirage", "label": "Mirage"}, {"value": "de_nuke", "label": "Nuke"}],
"show_when": {"field": "mode", "is": ["5v5"]}}
]},
{"title": "More options", "collapsed": true, "fields": [
{"type": "toggle", "id": "knife", "label": "Knife round", "value": true},
{"type": "text", "id": "name", "label": "Team name", "max_length": 32}
]}
]
}
At most 5 sections and 25 fields. A section may have a title and start collapsed. A field is {type, id, label, description?, placeholder?, required?, value?, show_when?}:
type |
What it is |
|---|---|
text |
Words: max_length (at most 4000, 200 by default), multiline?. |
number |
min?, max?, step?. |
toggle |
On or off. |
choice |
One of its options, as tiles, a list or segmented. |
multi |
Some of its options, between min and max, as tiles or a list. |
select |
One of its options, from a menu. |
note |
Words only, nothing to fill in. |
Options are {value, label, description?, image?, group?}, at most 50: image puts a picture on a tile, and group heads the options that follow. show_when shows a field only while an earlier choice, select or toggle ("true", "false") holds one of is.
The person sends the form once. The app gets a form interaction whose values hold each shown field by its id: text, a number, true or false, or a list. Otag checks them first (422 missing_value and invalid_value, naming the field).
Settings in a server
When someone who manages a server opens Server settings → Integrations → your app → Its settings, the app gets a configure interaction for that server. Answer with a form; its sending comes back as a form interaction. Keep the settings on your side by server, and check member.permissions when they are saved: Manage Server is 32768.
Pictures
Otag fetches the pictures that cards and forms link (PNG, JPEG, GIF or WebP; at most 4 MB and 4096 pixels a side) and keeps them, once per address. People's Otag loads them from Otag, never from the app's address. A picture Otag can't fetch is left off, and an address on a private or local network is never fetched.
Webhooks
For a system that only posts, such as a build server, a monitor or a shop, a webhook is simpler than an app. Make one in Server settings → Integrations → Webhooks: it posts into one channel, under its own name and picture, at an address shown once.
POST https://api.otag.chat/api/v1/webhooks/{id}/{token}
Content-Type: application/json
{"content": "Build 128 passed", "card": {"title": "main", "status": {"text": "Passed", "tone": "success"}}}
No sign-in is needed: the address is the secret. A webhook's card holds only link actions. It posts up to 2 messages a second (bursts of 10); ?wait=true answers with the message posted.
Permissions
An app asks for permissions as one number, the sum of these:
| Permission | Value |
|---|---|
| View channels | 1 |
| Send messages | 2 |
| Attach files | 4 |
| Add reactions | 8 |
| Manage messages | 16 |
| Connect (join voice) | 32 |
| Speak | 64 |
| Share screen | 128 |
| Mute members | 256 |
| Move members | 512 |
| Manage channels | 1024 |
| Manage roles | 2048 |
| Create invites | 4096 |
| Kick members | 8192 |
| Ban members | 16384 |
| Manage server | 32768 |
| Administrator | 65536 |
| Change nickname | 131072 |
| Manage nicknames | 262144 |
| Add emoji and decorations | 524288 |
| Manage emoji and decorations | 1048576 |
| Time out members | 4194304 |
| View audit log | 8388608 |
An app that posts cards and answers needs View channels and Send messages (3). Ask for no more than it uses: the people adding it see the list and can turn things off.
Limits and errors
| Limit | |
|---|---|
| Apps per account | 10 |
| Apps per server | 25 |
| Commands per app, options per command | 50, 10 |
| Time to answer an interaction | 3 seconds (a ping: 5) |
| Follow-ups | 15 minutes, once a second, bursts of 20 |
| An app's messages | 5 a second, bursts of 20 |
| Interactions a person starts | 2 a second, bursts of 10 |
| Webhook posts | 2 a second, bursts of 10 |
An error is a status with {code, message}. 429 rate_limited says when to try again in retry_after_ms. The ones apps meet most:
| Code | Meaning |
|---|---|
unauthorized (401) |
The token is wrong, or was replaced. |
app_not_allowed (403) |
Apps can't call that. |
missing_permission (403) |
The app's role lacks the permission there. |
invalid_card, invalid_form, invalid_command (422) |
The message names what doesn't fit. |
unknown_interaction (404) |
The interaction's 15 minutes are over, or its token is wrong. |
app_offline, app_timeout, app_error |
What people see when the app didn't answer, or answered something that doesn't fit. |
Testing your app
- Keep it private ("Anyone can add it" off) and add it to a server of your own while you build it.
- Run it over the gateway on your computer: no address, no tunnel. Set the interactions address only when it runs where Otag can reach it, or through a tunnel to your computer.
- Switch Otag to Turkish (Settings → App) to see your answers in
tr. - To see the app's hello again, remove it from your server in Integrations and add it again.
- If the app is slow to answer, people see "The app didn't answer in time": answer
deferfirst and follow up.
Getting on the app list
Server admins add apps from the list in Server settings → Integrations, where Otag's admins choose which apps appear and which are featured first. To ask:
- Make the app public ("Anyone can add it"), with a description and an icon. A mark makes its "Otag × App" lockup.
- On the app's page, under The app list, choose Ask to be listed.
- Otag's admins review it. You get an email with their decision, and a refusal says why.
A listed app that goes private leaves the list. Anyone can still add a public app by its link or ID, listed or not.
Keeping it safe
- Keep the token on your server. If it leaks, make a new one at once: the old one stops.
- Check the signature of every interaction posted to the app, and refuse what doesn't check out.
- Ask for the permissions the app uses, and no more.
- Show people only what is theirs to see: answer with
replyfor one person, and useusersandexcepton actions.