Skip to main content
The Workchats public API lets your product send messages into Workchats: a direct message to a person, or a post in a group or channel. Your App gets its own bot user in each company that installs it, reads that company’s people and conversations, and sends, edits and deletes its own messages.

Quickstart

Register an App, install it on the sandbox, and send your first message.

Concepts

Apps, installations, bot users, tokens and scopes.

API reference

Every endpoint, generated from the OpenAPI spec, with a live playground against each version’s own environment.

Errors

The error envelope and every code you may see.

​
How it works

  1. Octogle registers your App once: a client_id, client_secret, and (for Phase 1b) a signing secret for callbacks.
  2. A company admin approves your App through an OAuth consent screen and picks which groups and channels it can post to.
  3. Your App gets a bot token scoped to that one company, and reads its people and conversations to figure out where to send messages.
  4. Your App sends, edits and deletes its own messages with POST /v1/messages, PATCH /v1/messages/{id} and DELETE /v1/messages/{id}.

​
What’s live today

  • OAuth install, token exchange, and revoke.
  • Listing users and conversations.
  • Reading a conversation’s message history and the files attached to it, scoped to what your bot can see.
  • Sending, editing and deleting messages, with idempotent sends.
Signed callbacks (app.uninstalled, directory.changed) and clickable message buttons ship in a later phase. Everything below is written for what’s live now, with upcoming work marked where it appears.
The API is versioned at /v1 and changes only additively within a version. See Versioning.