Create an app

For org owners and admins

Org owners and admins create your organization’s own apps: bots that run on your servers, or a service’s, and post in your channels. You set what each app may do and what it hears about. A developer then uses the app’s token and signing secret to run it. See Build an app.

An organization can have up to 10 apps. Apps are free: they aren’t members and don’t take a seat.

Before you start#

• Use the desktop or web app. On a phone, the apps pages are read only: “To create or change apps, use the desktop or web app.”
• Have two-factor sign-in set up. Every action on the apps pages needs a code from your authenticator app, even while you’re signed in and even if your organization doesn’t require two-factor. When asked, Enter your two-factor code and select Verify. Without two-factor, the app asks you to Set up two-factor first.
• Apps need a connection. Nothing on these pages works offline.

Turn on apps#

Apps are off for a new organization.

1. Open Settings → Integrations → Apps.
2. Turn on Allow apps.

Turning Allow apps off later pauses every app at once: their tokens are refused and they get no events. Nothing is deleted, and turning apps back on resumes them.

Create the app#

Select Create app and fill in Create an app:

1. Name: 2 to 40 characters. It can’t look like a member’s name or another app’s, and it can’t use reserved words such as buildIt.social, Admin, System, Support, Security, Billing, Help or Feedback, so nobody mistakes the app for a person or for buildIt.social. Look-alike spellings count as the same name.
2. Description: what the app does, up to 300 characters. People see it on the app’s card.
3. Choose picture: a JPEG, PNG, WebP or GIF of up to 2 MB. It’s shown as a rounded square.
4. What it may do: the app’s permissions. Give it only what it needs:
   • Its channels: always on. It sees the channels it’s in, with their names, topics and members (names only, never emails).
   • Read messages: every message in its channels, earlier ones too, and new ones as they arrive.
   • Messages that mention it: only messages that @mention it. Choose this instead of Read messages for a bot that answers commands.
   • Post: post, change and delete its own messages, with cards, and react.
   • Calls: hear when calls start and end in its channels.
   • Work items: hear about work items of its channels’ projects, and read an item by its key.
5. Events it hears about, grouped as Channels, Messages, Cards, Calls and Work items. Each event needs one of the permissions above (the form says which, as Needs:), and turning a permission off clears its events. For a command bot: It is mentioned, Someone answers its card and Its card closes.
6. How the app gets events:
   • Webhook: “We send each event to your HTTPS URL, signed with the app’s secret. Needs a public URL.”
   • Polling: “Your app asks for its events with its token. No public URL needed.”
7. Who adds it to channels: Members (any member of a channel who isn’t a guest; org-wide channels: admins only) or Admins only.

Then select Create. The form starts with a command bot’s choices: Messages that mention it, Post and the It is mentioned event.

Copy the token and signing secret#

As soon as the app is created, Deploybot is ready shows two values:

• App token: the app calls the buildIt.social API with it. It starts with buildit_app_.
• Signing secret: the app checks with it that events really come from buildIt.social. It starts with buildit_whsec_.

Copy these now: you won’t see them again. Use Copy App token and Copy Signing secret, and put them straight into your app’s server settings or secret store, or hand them to your developer through a secret store. Never paste them into a chat, a ticket, an email or code. If you lose one, rotate it on the app’s page to get a new one.

Next steps#

1. Webhook apps: once the app’s server holds the signing secret, enter its Webhook URL on the app’s page and select Verify. No events are sent until the URL is verified. See Manage an app.
2. Add the app to a channel, from the channel’s details or by mentioning it. See Apps in your channels.