curl --request PUT \
--url https://api.cloudtalk.io/v1/user-statuses/{userId} \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"statusTypeId": "9",
"customText": "Back at 14:00"
}
'import requests
url = "https://api.cloudtalk.io/v1/user-statuses/{userId}"
payload = {
"statusTypeId": "9",
"customText": "Back at 14:00"
}
headers = {
"Authorization": "Basic <encoded-value>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
body: JSON.stringify({statusTypeId: '9', customText: 'Back at 14:00'})
};
fetch('https://api.cloudtalk.io/v1/user-statuses/{userId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cloudtalk.io/v1/user-statuses/{userId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'statusTypeId' => '9',
'customText' => 'Back at 14:00'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Basic <encoded-value>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.cloudtalk.io/v1/user-statuses/{userId}"
payload := strings.NewReader("{\n \"statusTypeId\": \"9\",\n \"customText\": \"Back at 14:00\"\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("Authorization", "Basic <encoded-value>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://api.cloudtalk.io/v1/user-statuses/{userId}")
.header("Authorization", "Basic <encoded-value>")
.header("Content-Type", "application/json")
.body("{\n \"statusTypeId\": \"9\",\n \"customText\": \"Back at 14:00\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudtalk.io/v1/user-statuses/{userId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"statusTypeId\": \"9\",\n \"customText\": \"Back at 14:00\"\n}"
response = http.request(request)
puts response.read_body{
"userId": "4207",
"status": "idle",
"statusType": {
"id": "9",
"name": "Idle",
"actAs": "idle"
},
"customText": "Back at 14:00",
"presence": "connected",
"source": "api",
"updatedAt": "2026-11-02T12:58:40.731Z"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"target": "<string>"
}
],
"target": "<string>"
},
"requestId": "<string>"
}{
"code": "UNAUTHORIZED",
"message": "You are not authorized to access this resource."
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"target": "<string>"
}
],
"target": "<string>"
},
"requestId": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"target": "<string>"
}
],
"target": "<string>"
},
"requestId": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"target": "<string>"
}
],
"target": "<string>"
},
"requestId": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"target": "<string>"
}
],
"target": "<string>"
},
"requestId": "<string>"
}<string>{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"target": "<string>"
}
],
"target": "<string>"
},
"requestId": "<string>"
}Set a user's status
Sets the status type a user has picked: an Online type, or an Idle type with an optional note. Offline cannot be set: it follows the user’s real connection. The user must be signed in on at least one device. PUT replaces the whole picked status, so leaving customText out or sending null clears the note.
- The Phone and the mobile app show the change at once. App versions that support it show the same notice a Dashboard override shows: an admin changed their status. Older mobile app versions apply the change without the notice.
- Queue routing follows: an Idle type pauses queue calls, an Online type resumes them.
- The
user.status_changedwebhook is sent. A change to the note alone also sends it, with the same data as before, because the webhook does not carry the note. - If the user is on a call,
statusTypechanges now andstatusstayson_calluntil the call ends. - Sending the same values again changes nothing and sends nothing.
sourcebecomesapi.
The note. The Phone shows customText only with the system Idle type (id 9). The mobile app, and the notice that tells the user an admin changed their status, show it with any type.
Order of checks. A body that is empty or is not valid JSON gets 400, and a media type the API cannot read at all gets 415, before anything else. Then a body that is not declared application/json, or a request with no Content-Type, gets 415, even when userId is malformed. Then a malformed userId gets 404, before the fields of the body are checked (400, then 422). For a well-formed request, the status type is checked first (422), then the user (404), then whether the user is signed in (409, USER_STATUS.USER_NOT_SIGNED_IN). A rejected request changes nothing.
The legacy List agents endpoint may not show a status set here.
curl --request PUT \
--url https://api.cloudtalk.io/v1/user-statuses/{userId} \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"statusTypeId": "9",
"customText": "Back at 14:00"
}
'import requests
url = "https://api.cloudtalk.io/v1/user-statuses/{userId}"
payload = {
"statusTypeId": "9",
"customText": "Back at 14:00"
}
headers = {
"Authorization": "Basic <encoded-value>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
body: JSON.stringify({statusTypeId: '9', customText: 'Back at 14:00'})
};
fetch('https://api.cloudtalk.io/v1/user-statuses/{userId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cloudtalk.io/v1/user-statuses/{userId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'statusTypeId' => '9',
'customText' => 'Back at 14:00'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Basic <encoded-value>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.cloudtalk.io/v1/user-statuses/{userId}"
payload := strings.NewReader("{\n \"statusTypeId\": \"9\",\n \"customText\": \"Back at 14:00\"\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("Authorization", "Basic <encoded-value>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://api.cloudtalk.io/v1/user-statuses/{userId}")
.header("Authorization", "Basic <encoded-value>")
.header("Content-Type", "application/json")
.body("{\n \"statusTypeId\": \"9\",\n \"customText\": \"Back at 14:00\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudtalk.io/v1/user-statuses/{userId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"statusTypeId\": \"9\",\n \"customText\": \"Back at 14:00\"\n}"
response = http.request(request)
puts response.read_body{
"userId": "4207",
"status": "idle",
"statusType": {
"id": "9",
"name": "Idle",
"actAs": "idle"
},
"customText": "Back at 14:00",
"presence": "connected",
"source": "api",
"updatedAt": "2026-11-02T12:58:40.731Z"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"target": "<string>"
}
],
"target": "<string>"
},
"requestId": "<string>"
}{
"code": "UNAUTHORIZED",
"message": "You are not authorized to access this resource."
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"target": "<string>"
}
],
"target": "<string>"
},
"requestId": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"target": "<string>"
}
],
"target": "<string>"
},
"requestId": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"target": "<string>"
}
],
"target": "<string>"
},
"requestId": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"target": "<string>"
}
],
"target": "<string>"
},
"requestId": "<string>"
}<string>{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"target": "<string>"
}
],
"target": "<string>"
},
"requestId": "<string>"
}Authorizations
HTTP Basic Authentication. Use your API Access Key ID as the username and your API Access Key Secret as the password. Generate keys in the CloudTalk Dashboard under Account -> Settings -> API Keys (https://dashboard.cloudtalk.io/menu/account/settings/API-keys).
Path Parameters
The user's id.
"4207"
Body
A status type id from List user status types. Its actAs must be online or idle.
"9"
Note, 1 to 30 characters after trimming. Allowed with any status type you can set. Leaving it out or sending null clears the note.
1 - 30"Back at 14:00"
Response
The user's status after the change.
The user's id.
"4207"
What the user is doing now: online, idle, offline, on_call or after_call_work. The same values as status on the user.status_changed webhook. New values may be added later, so handle unknown values.
"idle"
The status type the user picked. It is kept during calls and while signed out.
Show child attributes
Show child attributes
Short note shown next to the status. The Phone shows it only with the system Idle type (id 9). The mobile app, and the notice that tells the user an admin changed their status, show it with any type.
"Back at 14:00"
connected when the user is signed in on at least one device.
connected, disconnected Who set the current statusType: the user, an admin in the Dashboard, or this API. A user who never picked a status shows user. After an API change, api stays until the user or an admin picks a status.
user, admin, api Last time the user's connection, call state or picked status changed. UTC with milliseconds, for example 2026-11-02T12:58:40.731Z.