V 2.0
Group
Description
The Group API allows you to manage agent groups within the system. You can create, update, delete, and list groups. Groups are used to organize agents and manage their permissions and settings collectively.
Base URL
The base URL for all API endpoints is: deepcall/api/v2/Group
Authentication
All endpoints require authentication. Use one of the following methods:
-
SSID
-
User ID and Token
Error Responses
All endpoints may return the following error response:
Field | Type | Description |
---|---|---|
status | string | "error" |
message | string | Description of the error |
code | number | Error code |
Error Codes
Code | Description |
---|---|
1501 | The 'Name' field was not provided in the request |
1502 | GroupId is required |
1503 | Group not found or not authorized |
Notes
-
The
forward
parameter in the List Groups endpoint is used for permission checking. Iffalse
, it checks for the "AGENT_TO_AGENT_CALL" permission. -
The
quick
parameter in the List Groups endpoint, when set totrue
, returns a quicker response with potentially less detailed information. -
When filtering groups by name, the search is case-insensitive.
-
Group names are unique per user. If a duplicate name is provided, a number will be appended to make it unique.
-
When a group is deleted, all associated agent-group relations are also removed, and the group is removed from the agent profiles in Elasticsearch.
Submit Assign Group To Agent
Endpoint Details
- Method: POST
-
Path:
deepcall/api/v2/Group/submitAssignGroupToAgent/
Description
This API endpoint allows assigning agents to a specific group and manages agent-group relationships. It also updates Elasticsearch indices to maintain agent-group relationships. The endpoint requires authentication either through a session ID (ssid) or a combination of userId and token.
Request Body Parameters
Field | Type | Required | Description |
---|---|---|---|
ssid | string | Yes (if userId and token not provided) | Session ID for authentication |
userId | string | Yes (if ssid not provided) | User ID for authentication |
token | string | Yes (if ssid not provided) | Token for authentication |
groupId | string | Yes | ID of the group to assign agents to |
agent_unique_id | array | No | Array of agent IDs to be assigned to the group |
receive_call | array | No | Array of agent IDs who can receive calls |
Response Parameters
Field | Type | Description |
---|---|---|
status | string | "success" if the operation was successful |
message | string | Success or error message |
code | number | HTTP status code (200 for success) |
Example Request 1 - Using SSID
Field | Value |
---|---|
ssid | abc123xyz |
groupId | 1 |
agent_unique_id | ["1001", "1002", "1003"] |
receive_call | ["1001", "1003"] |
Example Request 2 - Using userId and token
Field | Value |
---|---|
userId | user123 |
token | auth_token_xyz |
groupId | 1 |
agent_unique_id | ["1001", "1002", "1003"] |
receive_call | ["1001", "1003"] |
Example Success Response
Field | Value |
---|---|
status | success |
message | Agents successfully assigned to the group, and Elasticsearch updated |
code | 200 |
Error Codes
Code | Description |
---|---|
1000 | Invalid parameters |
1502 | Group ID not provided |
1503 | Group not found or not authorized |
1015 | Permission denied |
1009 | Something went wrong (Generic error) |
1047 | Invalid Request Data |
Important Notes
Authentication:
- Mandatory: Must use either ssid OR userId+token combination
- Permission: Requires 'AGENT_TO_AGENT_CALL' permission
Agent Assignment:
- Optional Agent IDs: Not providing agent_unique_id removes all agents from group
- Call Reception: receive_call array controls which agents can receive calls
Operation Behavior:
- Atomic Operation: All changes apply or none
- Real-time Updates: Elasticsearch updates happen immediately
- Immediate Effect: Changes reflect instantly in database and search indices
Submit Assign Group To Agent
var axios = require('axios');
var data = '{"userId": "{{userid}}","token":"{{token}}","groupId": "4","agent_unique_id": ["2", "3", "4"],"receive_call": ["2", "3","4"] }';
var config = {
method: 'post',
url: 'https://ctv3-dev.sarv.com/api/v2/Group/submitAssignGroupToAgent',
headers: {
'Content-Length': ''
},
data : data
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
setUrl('https://ctv3-dev.sarv.com/api/v2/Group/submitAssignGroupToAgent');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
'follow_redirects' => TRUE
));
$request->setHeader(array(
'Content-Length' => ''
));
$request->setBody('{"userId": "{{userid}}","token":"{{token}}","groupId": "4","agent_unique_id": ["2", "3", "4"],"receive_call": ["2", "3","4"] }');
try {
$response = $request->send();
if ($response->getStatus() == 200) {
echo $response->getBody();
}
else {
echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
$response->getReasonPhrase();
}
}
catch(HTTP_Request2_Exception $e) {
echo 'Error: ' . $e->getMessage();
}
import http.client
conn = http.client.HTTPSConnection("ctv3-dev.sarv.com")
payload = "{\"userId\": \"{{userid}}\",\"token\":\"{{token}}\",\"groupId\": \"4\",\"agent_unique_id\": [\"2\", \"3\", \"4\"],\"receive_call\": [\"2\", \"3\",\"4\"] }"
headers = {
'Content-Length': ''
}
conn.request("POST", "/api/v2/Group/submitAssignGroupToAgent", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var client = new RestClient("https://ctv3-dev.sarv.com/api/v2/Group/submitAssignGroupToAgent");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
var body = @"" + "\n" +
@"{" + "\n" +
@" ""userId"": ""{{userid}}""," + "\n" +
@" ""token"":""{{token}}""," + "\n" +
@" ""groupId"": ""4""," + "\n" +
@" ""agent_unique_id"": [""2"", ""3"", ""4""]," + "\n" +
@" ""receive_call"": [""2"", ""3"",""4""] " + "\n" +
@"}";
request.AddParameter("text/plain", body, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
curl --location --request POST 'https://ctv3-dev.sarv.com/api/v2/Group/submitAssignGroupToAgent' \
--data-raw '{
"userId": "{{userid}}",
"token":"{{token}}",
"groupId": "4",
"agent_unique_id": ["2", "3", "4"],
"receive_call": ["2", "3","4"]
}'
var request = http.Request('POST', Uri.parse('https://ctv3-dev.sarv.com/api/v2/Group/submitAssignGroupToAgent'));
request.body = '''\n{\n "userId": "{{userid}}",\n "token":"{{token}}",\n "groupId": "4",\n "agent_unique_id": ["2", "3", "4"],\n "receive_call": ["2", "3","4"] \n}''';
http.StreamedResponse response = await request.send();
if (response.statusCode == 200) {
print(await response.stream.bytesToString());
}
else {
print(response.reasonPhrase);
}
package main
import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)
func main() {
url := "https://ctv3-dev.sarv.com/api/v2/Group/submitAssignGroupToAgent"
method := "POST"
payload := strings.NewReader(`{
"userId": "{{userid}}",
"token":"{{token}}",
"groupId": "4",
"agent_unique_id": ["2", "3", "4"],
"receive_call": ["2", "3","4"]
}`)
client := &http.Client {
}
req, err := http.NewRequest(method, url, payload)
if err != nil {
fmt.Println(err)
return
}
res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()
body, err := ioutil.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
POST /api/v2/Group/submitAssignGroupToAgent HTTP/1.1
Host: ctv3-dev.sarv.com
Content-Length: 152
{
"userId": "{{userid}}",
"token":"{{token}}",
"groupId": "4",
"agent_unique_id": ["2", "3", "4"],
"receive_call": ["2", "3","4"]
}
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "\n{\n \"userId\": \"{{userid}}\",\n \"token\":\"{{token}}\",\n \"groupId\": \"4\",\n \"agent_unique_id\": [\"2\", \"3\", \"4\"],\n \"receive_call\": [\"2\", \"3\",\"4\"] \n}");
Request request = new Request.Builder()
.url("https://ctv3-dev.sarv.com/api/v2/Group/submitAssignGroupToAgent")
.method("POST", body)
.addHeader("Content-Length", "")
.build();
Response response = client.newCall(request).execute();
var myHeaders = new Headers();
myHeaders.append("Content-Length", "");
var raw = "\n{\n \"userId\": \"{{userid}}\",\n \"token\":\"{{token}}\",\n \"groupId\": \"4\",\n \"agent_unique_id\": [\"2\", \"3\", \"4\"],\n \"receive_call\": [\"2\", \"3\",\"4\"] \n}";
var requestOptions = {
method: 'POST',
headers: myHeaders,
body: raw,
redirect: 'follow'
};
fetch("https://ctv3-dev.sarv.com/api/v2/Group/submitAssignGroupToAgent", requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
CURL *curl;
CURLcode res;
curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(curl, CURLOPT_URL, "https://ctv3-dev.sarv.com/api/v2/Group/submitAssignGroupToAgent");
curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
curl_easy_setopt(curl, CURLOPT_DEFAULT_PROTOCOL, "https");
struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Content-Length: ");
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
const char *data = "\n{\n \"userId\": \"{{userid}}\",\n \"token\":\"{{token}}\",\n \"groupId\": \"4\",\n \"agent_unique_id\": [\"2\", \"3\", \"4\"],\n \"receive_call\": [\"2\", \"3\",\"4\"] \n}";
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data);
res = curl_easy_perform(curl);
}
curl_easy_cleanup(curl);
#import
dispatch_semaphore_t sema = dispatch_semaphore_create(0);
NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://ctv3-dev.sarv.com/api/v2/Group/submitAssignGroupToAgent"]
cachePolicy:NSURLRequestUseProtocolCachePolicy
timeoutInterval:10.0];
NSDictionary *headers = @{
@"Content-Length": @""
};
[request setAllHTTPHeaderFields:headers];
NSData *postData = [[NSData alloc] initWithData:[@"\n{\n \"userId\": \"{{userid}}\",\n \"token\":\"{{token}}\",\n \"groupId\": \"4\",\n \"agent_unique_id\": [\"2\", \"3\", \"4\"],\n \"receive_call\": [\"2\", \"3\",\"4\"] \n}" dataUsingEncoding:NSUTF8StringEncoding]];
[request setHTTPBody:postData];
[request setHTTPMethod:@"POST"];
NSURLSession *session = [NSURLSession sharedSession];
NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
if (error) {
NSLog(@"%@", error);
dispatch_semaphore_signal(sema);
} else {
NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;
NSError *parseError = nil;
NSDictionary *responseDictionary = [NSJSONSerialization JSONObjectWithData:data options:0 error:&parseError];
NSLog(@"%@",responseDictionary);
dispatch_semaphore_signal(sema);
}
}];
[dataTask resume];
dispatch_semaphore_wait(sema, DISPATCH_TIME_FOREVER);
open Lwt
open Cohttp
open Cohttp_lwt_unix
let postData = ref "{\n \"userId\": \"{{userid}}\",\n \"token\":\"{{token}}\",\n \"groupId\": \"4\",\n \"agent_unique_id\": [\"2\", \"3\", \"4\"],\n \"receive_call\": [\"2\", \"3\",\"4\"] \n}";;
let reqBody =
let uri = Uri.of_string "https://ctv3-dev.sarv.com/api/v2/Group/submitAssignGroupToAgent" in
let headers = Header.init ()
|> fun h -> Header.add h "Content-Length" ""
in
let body = Cohttp_lwt.Body.of_string !postData in
Client.call ~headers ~body `POST uri >>= fun (_resp, body) ->
body |> Cohttp_lwt.Body.to_string >|= fun body -> body
let () =
let respBody = Lwt_main.run reqBody in
print_endline (respBody)
$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("Content-Length", "")
$body = "`n{`n `"userId`": `"{{userid}}`",`n `"token`":`"{{token}}`",`n `"groupId`": `"4`",`n `"agent_unique_id`": [`"2`", `"3`", `"4`"],`n `"receive_call`": [`"2`", `"3`",`"4`"] `n}"
$response = Invoke-RestMethod 'https://ctv3-dev.sarv.com/api/v2/Group/submitAssignGroupToAgent' -Method 'POST' -Headers $headers -Body $body
$response | ConvertTo-Json
require "uri"
require "net/http"
url = URI("https://ctv3-dev.sarv.com/api/v2/Group/submitAssignGroupToAgent")
https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Length"] = ""
request.body = "{\n \"userId\": \"{{userid}}\",\n \"token\":\"{{token}}\",\n \"groupId\": \"4\",\n \"agent_unique_id\": [\"2\", \"3\", \"4\"],\n \"receive_call\": [\"2\", \"3\",\"4\"] \n}"
response = https.request(request)
puts response.read_body
printf '
{
"userId": "{{userid}}",
"token":"{{token}}",
"groupId": "4",
"agent_unique_id": ["2", "3", "4"],
"receive_call": ["2", "3","4"]
}'| http --follow --timeout 3600 POST 'https://ctv3-dev.sarv.com/api/v2/Group/submitAssignGroupToAgent' \
Content-Length:
import Foundation
#if canImport(FoundationNetworking)
import FoundationNetworking
#endif
var semaphore = DispatchSemaphore (value: 0)
let parameters = "{\n \"userId\": \"{{userid}}\",\n \"token\":\"{{token}}\",\n \"groupId\": \"4\",\n \"agent_unique_id\": [\"2\", \"3\", \"4\"],\n \"receive_call\": [\"2\", \"3\",\"4\"] \n}"
let postData = parameters.data(using: .utf8)
var request = URLRequest(url: URL(string: "https://ctv3-dev.sarv.com/api/v2/Group/submitAssignGroupToAgent")!,timeoutInterval: Double.infinity)
request.addValue("", forHTTPHeaderField: "Content-Length")
request.httpMethod = "POST"
request.httpBody = postData
let task = URLSession.shared.dataTask(with: request) { data, response, error in
guard let data = data else {
print(String(describing: error))
semaphore.signal()
return
}
print(String(data: data, encoding: .utf8)!)
semaphore.signal()
}
task.resume()
semaphore.wait()
Example Response
[{"key":"Date"
"value":"Sat
16 Nov 2024 14:39:37 GMT"}
{"key":"Content-Type"
"value":"application\/json; charset=utf-8"}
{"key":"Content-Length"
"value":"112"}
{"key":"Connection"
"value":"keep-alive"}
{"key":"Access-Control-Allow-Origin"
"value":"*"}
{"key":"Access-Control-Allow-Methods"
"value":"POST
GET
OPTIONS
PATCH
DELETE"}
{"key":"Access-Control-Allow-Headers"
"value":"X-Requested-With
content-type"}
{"key":"Access-Control-Allow-Credentials"
"value":"true"}
{"key":"Vary"
"value":"Origin"}
{"key":"ETag"
"value":"W\/\"70-bAW07O3252krngsMtOySl9Cikpk\""}
{"key":"Strict-Transport-Security"
"value":"max-age=15724800; includeSubDomains"}]
{
"status": "success",
"message": "Agents successfully assigned to the group, and Elasticsearch updated",
"code": 200
}