Quickstart

This walks through the shortest path from nothing to a message landing in a Workchats DM: register your App, install it on the sandbox company, confirm the token works, then send. All of this runs against the staging sandbox (https://public-api.staging.workchats.com), never a real company. See Sandbox for how to get access.

Apps are registered by Octogle, not self-serve. Tell your Octogle contact:

the App’s name (shown on the consent screen and on every message it sends)
the OAuth redirect URI your backend will receive code on

You get back a client_id and a client_secret, and access to a sandbox company with a staging App registration. Tokens issued in the sandbox are prefixed wc_bot_test_ rather than wc_bot_live_, so they’re easy to tell apart in logs.Keep client_secret server-side. It’s a credential, not something to ship in a browser or mobile build.

Install on the sandbox

Send the company admin to the authorize URL your Octogle contact gives you for the sandbox (a staging counterpart of https://app.workchats.com/oauth/authorize), with:

?client_id=<your client_id>
&redirect_uri=<your registered redirect_uri, exactly>
&scope=users:read users:read.email conversations:read messages:write
&state=<opaque, single-use, generated by you>

The admin sees a consent screen naming your App and the scopes it’s asking for, and picks which groups and channels the bot may join. On approval, Workchats redirects to redirect_uri?code=<code>&state=<state>.Exchange the code for a token:

curl -X POST https://public-api.staging.workchats.com/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "'"$CODE"'",
    "redirect_uri": "'"$REDIRECT_URI"'"
  }'

const res = await fetch("https://public-api.staging.workchats.com/oauth/token", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Basic " + Buffer.from(`${process.env.CLIENT_ID}:${process.env.CLIENT_SECRET}`).toString("base64"),
  },
  body: JSON.stringify({
    grant_type: "authorization_code",
    code: process.env.CODE,
    redirect_uri: process.env.REDIRECT_URI,
  }),
});
const token = await res.json();
console.log(token.access_token); // wc_bot_test_...

200

{
  "access_token": "wc_bot_test_0Xa9…",
  "token_type": "Bearer",
  "scope": "users:read users:read.email conversations:read messages:write",
  "workspace": { "id": "cmp_3f0c1b9e-5d0a-4a57-9a53-2f4f1c9d6b10", "name": "Corpwise" },
  "bot_user_id": "usr_8a1d2c3e-4b5f-4a6b-8c7d-9e0f1a2b3c4d"
}

This token doesn’t expire and there’s no refresh token — save it now. Reinstalling later keeps the same bot user but issues a new token, and the old one stops working (401 token_revoked). Replace the stored token whenever you finish a new install.

Confirm the token works

curl https://public-api.staging.workchats.com/v1/auth/test \
  -H "Authorization: Bearer $ACCESS_TOKEN"

const res = await fetch("https://public-api.staging.workchats.com/v1/auth/test", {
  headers: { Authorization: `Bearer ${process.env.ACCESS_TOKEN}` },
});
console.log(await res.json());

200

{
  "ok": true,
  "workspace": { "id": "cmp_3f0c1b9e-5d0a-4a57-9a53-2f4f1c9d6b10", "name": "Corpwise", "domain": "corpwise.ae" },
  "bot_user_id": "usr_8a1d2c3e-4b5f-4a6b-8c7d-9e0f1a2b3c4d",
  "scopes": ["users:read", "users:read.email", "conversations:read", "messages:write"]
}

Send a DM

Look up a recipient by email, then send:

curl "https://public-api.staging.workchats.com/v1/users/[email protected]" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

curl -X POST https://public-api.staging.workchats.com/v1/messages \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-1:usr_9a1d2c3e" \
  -d '{
    "to": { "type": "user", "id": "usr_9a1d2c3e-4b5f-4a6b-8c7d-9e0f1a2b3c4d" },
    "text": "Hello from my App"
  }'

const lookup = await fetch(
  "https://public-api.staging.workchats.com/v1/users/[email protected]",
  { headers: { Authorization: `Bearer ${process.env.ACCESS_TOKEN}` } }
);
const { user } = await lookup.json();

const sent = await fetch("https://public-api.staging.workchats.com/v1/messages", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ACCESS_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": `quickstart-1:${user.id}`,
  },
  body: JSON.stringify({
    to: { type: "user", id: user.id },
    text: "Hello from my App",
  }),
});
console.log(await sent.json());

201

{
  "ok": true,
  "message": {
    "id": "dmsg_4e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b",
    "conversation_id": "dm_77a1b2c3-d4e5-4f60-8a7b-9c0d1e2f3a4b",
    "thread_id": null,
    "created_at": "2026-09-28T11:05:12Z"
  }
}

The Idempotency-Key matters as soon as you retry on a timeout. See Idempotency before you write real send logic.

Sending messages covers blocks, edits and deletes.
Errors lists every code you can get back.
Concepts explains Apps, installations and scopes in more depth.

Getting Started

Guides

Reference

Changelog

Policies

Next

​Next

Next