Skip to main content

​
App

An App is your integration, registered once with Octogle: a name, a client_id and client_secret, a redirect URI, and (from Phase 1b) a callback URL and signing secret. One App can be installed into many companies.

​
Installation

A company installs your App by approving it through the OAuth consent screen. That creates one installation per (App, company) pair, which owns:
  • one bot user in that company
  • one bot token, scoped to that company only
An installation moves between three states: active, disconnected (your App called POST /oauth/revoke), and uninstalled (the company or Octogle removed it). Reconnecting reactivates the same installation, the same bot user, and issues a new token.

​
Bot user

Your App’s bot is a real user in the company, with a display name (your App’s name) and avatar (your App’s icon). It can:
  • be a member of groups and channels, and post in the ones it’s a member of
  • receive and send direct messages to people, subject to who a bot may DM
It cannot log in, appear in search or the company directory, be @mentioned into a notification, or join a call.

​
Tokens and scopes

Your bot token doesn’t expire and isn’t refreshed — see OAuth install. It’s scoped to exactly what the company admin approved: Full list on the Scopes page.

​
IDs

Every id is an opaque, prefixed string. The prefix tells you what it is, but it isn’t a secret and every lookup is still scoped to your installation’s company: Store ids as opaque strings. Don’t parse them.

​
The response envelope

Every success is resource-keyed:
Every non-2xx response has the same shape:
code is stable and machine-readable — branch on it, not on message. New codes can appear over time (the API is additive-only within /v1); treat an unknown one as a generic failure rather than crashing. Full list on Errors.

​
Lists are cursor-paginated

GET /v1/users, GET /v1/conversations, and GET /v1/conversations/{conversation_id}/messages take limit (default 200, max 1000) and cursor, and return next_cursor, which is null on the last page. Details on Pagination.