Skip to content
Appearance
Download

Developer docs

Getting started

Create an application in the developer portal, get a bot token, choose scopes and add your bot to a hub.

1. Create an application

  1. Sign in and open the developer portal. You can also reach it from your account menu.
  2. Choose Create an application (or New) and give it a name (up to 32 characters). Each application gets its own bot account with a handle, a picture and a Bot badge that can never be hidden or faked.
  3. Add a description (up to 400 characters) and a picture. You can own up to 25 applications, and share each with a team of up to 25 people as admins, developers or read only members.

2. Get the bot token

Open the Token tab and choose Create token (later, Reset token). Hubs asks for your password, and your second factor if you use one, then shows the token once. Copy it into your secret store right away; Hubs keeps only a hash.

Tokens start with hbot_ and match hbot_[0-9A-Za-z]{46}, so secret scanners can find them. Every message and file posted in Hubs is checked for tokens: a live token found anywhere is revoked at once and you get a notice in the portal. Resetting retires the old token immediately.

Never put a bot token in a web page, a hosted app bundle or a public repository. Send it only from your own server.

3. Choose scopes

Scopes are the parts of the API your application uses. List them in the portal; the install link asks for some of them; a hub admin approves them. Most scopes also need a permission inside the hub, which rides on the bot's own role there.

ScopeOpensNeeds permission
botAdds the bot to the hub as a member with a Bot badge.None
channels:readSee the names of the channels it can open.view_channels
messages:readRead messages in the channels it can open.read_history
messages:writePost messages as the bot where its role may post.send_messages
reactions:writeAdd and remove its own reactions.add_reactions
members:readSee who is in the hub: names, handles and hub roles.view_members
gatewayHear about new messages, reactions, members and channels as they happen, only for what its other scopes already allow.None
commandsOffer slash commands, buttons, menus and forms that people choose to use in chat.None
PermissionIn plain words
view_channelsSee channels. Only channels its role can already open.
read_historyRead message history. Earlier messages in those channels.
send_messagesSend messages. Where its role may post. Never announcements.
add_reactionsAdd reactions. Its own reactions on messages it can read.
view_membersSee the member list. Names, handles and hub roles of members.

Every call needs its scope, its permission and the hub's own channel rules for the bot's role. Narrowing your application's scope list narrows every install at once; widening it never widens an install that a hub already approved.

4. Add the bot to a hub

The portal shows your install link. Share it with an owner or admin of the hub. It looks like this:

Install link
https://hubs.example.com/oauth2/authorize?client_id=<application id>&scope=bot+messages:read+messages:write&permissions=read_history,send_messages
  • scope lists scopes separated by spaces, plus signs or commas. It must include bot.
  • permissions lists permissions separated by commas. Leave it out to ask for what the scopes need.
  • hub (optional) preselects one of the admin's hubs.

The install screen says what the bot can do and what it can never do before the admin approves. The bot then joins with its own role, and the hub's audit trail records the install.

5. Make your first call

Send the token in the Authorization header as Bot <token>. Every call is HTTPS and JSON.

curl https://hubs.example.com/api/developer/v1/users/@me \
  -H "Authorization: Bot $HUBS_BOT_TOKEN"
Response
{
  "id": "0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "handle": "dice_bot",
  "displayName": "Dice",
  "bot": true,
  "application": {
    "id": "c4d5e6f7-a8b9-4c0d-8e1f-2a3b4c5d6e7f",
    "name": "Dice"
  }
}

Hub API keys

Hub owners who want a quick script, not a bot, can make a hub API key in Manage, Developer tools. A key works for 1 to 20 chosen channels of one hub, for 1 to 90 days, with any of channels:read, messages:read and messages:write. Send it as Authorization: Bearer hubs_.... Posts made with a key are labeled as an integration and act for the owner who made it, so the key stops working if that person stops being the owner.

Next