Skip to main content
The User status API at https://api.cloudtalk.io/v1 shows what each user in your company is doing right now and lets you set the status they picked, the way an admin can in the Dashboard. Use it for a wallboard, to pause a user’s queue calls from your workforce tool, or to set a note such as “Back at 14:00”.
Requests authenticate with an API key, like the rest of the CloudTalk API. The key acts as a company admin, and no header names a user. For live updates, subscribe to the user.status_changed webhook rather than polling.

​
Quick start

1

List the status types users can pick

Each type has an id and an actAs of online, idle or offline. You can set a type whose actAs is online or idle.
2

Read who is available

3

Set a user Idle with a note

The answer is the user’s status after the change, with source: "api".

​
Operations

List user statuses returns { "data": [...], "pagination": { "limit": 20, "next": "..." }, "requestId": "..." }: pass pagination.next as ?cursor= for the next page. The status types come in one response, { "data": [...], "requestId": "..." }.

​
How a status is worked out

Three inputs are checked in this order, and the first that applies wins:
  1. Whether the user is signed in on any device. If not, status is offline.
  2. Whether the user is on a call (on_call) or in after-call work (after_call_work).
  3. The status type the user picked, through its actAs: online, idle or offline.
status shows the result. statusType and customText show what was picked, which is kept during calls and while the user is signed out.

​
Setting a status

  • PUT replaces the whole picked status. Leaving customText out, or sending null, clears the note.
  • The user must be signed in on at least one device, otherwise 409 USER_STATUS.USER_NOT_SIGNED_IN. Offline cannot be set: it follows the user’s real connection (422 USER_STATUS.OFFLINE_NOT_ALLOWED).
  • An Idle type pauses the user’s queue calls and an Online type resumes them.
  • If the user is on a call, statusType changes now and status stays on_call until the call ends.
  • The change sends user.status_changed. Sending the same values again changes nothing and sends nothing.
  • source becomes api and stays so until the user or an admin picks a status.
  • The Phone and the mobile app show the change at once.
The reference lists every answer, and how the change shows on the user’s Phone and mobile app.

​
Errors

Requests are rate limited per company. Over the limit you get 429 with X-CloudTalkAPI-Limit, X-CloudTalkAPI-Remaining and X-CloudTalkAPI-ResetTime, and no error body. Errors from the service share one shape, { "error": { "code", "message", "target" }, "requestId" }. Branch on code. A 401 comes from the gateway instead, as { "code", "message" } with no error object. message is for people and can change. target names the field, parameter or header at fault when there is one. Quote requestId when you contact support: every answer also carries it in the X-Transaction-ID header. A user id that is malformed or belongs to another company gets 404 USER_STATUS.USER_NOT_FOUND, and so does a user with no status activity on Get.