SparkTG

Update an agent (v2) Documentation

Update an agent (v2)

v2

Update an agent (v2)

Log in, log out, breaks and profile changes

API v2v21 Endpoint

Overview

Log an agent in or out, put them on a break, or change their phone number, country code or display name. This replaces PATCH /api/v1/agents. Identify the agent with exactly one of agent_number or agent_sip, then send at least one field to change; fields you leave out are not touched. The body is JSON, and any field not listed below is rejected with a 400. null and empty strings are rejected; nothing is cleared by this endpoint. Each successful call is metered once.

Available Endpoints

PUT/api/v2/agents

Key Parameters

agent_number(String)

The agent's current phone number. Send this or agent_sip, not both.

agent_sip(String)

The agent's SIP extension. Send this or agent_number, not both.

status(Integer)

0 logs the agent in (Available). 2 logs them out (Offline) or, with a break_id, puts them on that break. No other values are accepted.

break_id(Integer)

Which break to put the agent on. Must be a break enabled for your service. Sending break_id implies status 2, and it can't be combined with status 0. With status 2 and no break_id, the default break 7 (Offline) is used, which logs the agent out.

number(String)

New phone number: 4 to 15 digits, no +, spaces or dashes. Must not belong to another agent in the service. It can't be changed while the agent is on a call.

country_code(String)

1 to 4 digits without +, not starting with 0, for example 91 or 971.

Usage Scenarios

Log an agent in

Set status to 0. The agent becomes Available and starts receiving calls from their queues. This also brings an agent back from any break.

0 ParametersAvailable in Examples

Log an agent out

Set status to 2 without a break_id. The agent goes Offline (break 7) and stops receiving calls. Sending status 2 with break_id 7 does the same thing.

0 ParametersAvailable in Examples

Put an agent on a break

Send the break_id; status 2 is implied. The agent stops receiving calls until they are logged in again. Here the agent is picked by phone number instead of SIP extension.

0 ParametersAvailable in Examples

Change from one break to another

An agent can't move straight from one break to another; that call returns 409. Log them in first (status 0), then send the new break_id. Both calls are safe to retry.

0 ParametersAvailable in Examples

Update profile details

Change the name, phone number and country code together. Profile fields can be sent in the same call as status or break_id, but the number can't be changed while the agent is on a call.

0 ParametersAvailable in Examples

Quick Example

Try this API with a simple cURL command

Basic API Call
curl -X PUT 'https://telephonycloud.co.in/api/v2/agents' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"agent_sip": "10114", "status": 0}'
💡 Replace <YOUR_TOKEN> with your API token

Response Preview

Sample response from this API

Sample Response
{"status":"success","changed":["status","break_id"],"agent":{"id":735,"name":"Priya Sharma","number":"9876500000","country_code":"91","sip":"10114","status":2,"break_id":3}}
View complete response format in Response section