V 2.0

Queue

Description

The Queue API provides functionality to retrieve and manage queue-related data in a call center environment. It offers detailed information about ongoing calls, agent statuses, and various queue metrics. This API is essential for call center managers and supervisors to monitor and analyze queue performance in real-time.

Authentication

All endpoints require authentication using either:

Ensure that you provide the necessary authentication parameters with each request.

Authentication Methods

  1. Session ID Authentication

    • Use the ssid parameter

    • Provides a quick and simple authentication method

  2. User ID and Token Authentication

    • Requires both userId and token parameters

    • Offers more granular access control

Error Codes

Queue API Specific Error Codes

Error Code Description Potential Cause Recommended Action
1501 Data already in processing A similar request is currently being processed Wait and retry the request after a short interval
1502 Invalid filter value The provided filter parameters are incorrect or malformed Review and correct the filter parameters

Additional Error Handling Guidelines

Best Practices

  1. Validate all input parameters before making a request

  2. Handle potential authentication failures

  3. Implement appropriate error handling and retry mechanisms

  4. Use the most specific authentication method for your use case

  5. Be mindful of request frequency to prevent server overload

Recommendation

For a complete understanding of all possible error codes and their implications, refer to the comprehensive SarvErrors documentation.

The documentation now provides a clear, structured overview of the Queue API's error handling, authentication methods, and best practices. The error codes table includes additional context like potential causes and recommended actions to help developers better understand and resolve issues.

callTakeover

{{brand}}/api/v2/queue/callTakeover

Introduction

This document provides detailed information about the Queue Call Takeover API endpoint. It includes request parameters, response formats, and examples.

Base URL

The base URL for this API endpoint is: deepcall/api/v2/queue

Authentication

Authentication is required for this endpoint using ssid (Session ID).


Queue Call Takeover

Endpoint

Description

The Queue Call Takeover endpoint allows supervisors or authorized users to take over an active call in the queue. This endpoint supports different methods to identify the call - either by call ID, caller number with agent ID, or caller number with call ID.

Use Cases

Request Parameters

Parameter Type Required Description
ssid string Yes Session ID
callId string No* Call ID to takeover (*required if callernumber not provided with agentid)
callernumber string No* Caller's phone number (*required if callId not provided)
agentid string No* Agent ID (*required when using callernumber)

Request Examples

Example 1: With Agent ID

{
  "ssid": "{{ssid}}",
  "callId": "{{callid}}",
  "agentid": "{{agentid}}"
}

Example 2: With Caller Number

{
  "ssid": "{{ssid}}",
  "callernumber": "{{callernumber}}",
  "agentid": "{{agentid}}"
}

Example 3: With Caller Number and Call ID

{
  "ssid": "{{ssid}}",
  "callernumber": "{{callernumber}}",
  "callId": "{{callid}}"
}

Response Details

Error Response

Status Code: 200

{
  "status": "error",
  "message": "Live call not found or invalid",
  "code": 1000
}

Field Type Description
status string Response status ("error" or "success")
message string Error message
code number Error code (1000)

Error Codes

Error Code Description
1000 Live call not found or invalid

Notes

Example cURL Request

curl -X POST "deepcall/api/v2/queue/callTakeover" \
  -H "Content-Type: application/json" \
  -d '{
    "ssid": "{{ssid}}",
    "callId": "{{callid}}",
    "agentid": "{{agentid}}"
  }'

callTakeover

var axios = require('axios');
var data = '{"ssid":"{{ssid}}","callId":"{{callid}}","agentid":"{{agentid}}"}';

var config = {
 method: 'post',
 url: '{{brand}}/api/v2/queue/callTakeover',
 headers: { 
'Content-Length': ''
 },
 data : data
};

axios(config)
.then(function (response) {
 console.log(JSON.stringify(response.data));
})
.catch(function (error) {
 console.log(error);
});
setUrl('{{brand}}/api/v2/queue/callTakeover');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
 'follow_redirects' => TRUE
));
$request->setHeader(array(
 'Content-Length' => ''
));
$request->setBody('{"ssid":"{{ssid}}","callId":"{{callid}}","agentid":"{{agentid}}"}');
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("{{brand}}")
payload = "{\"ssid\":\"{{ssid}}\",\"callId\":\"{{callid}}\",\"agentid\":\"{{agentid}}\"}"
headers = {
 'Content-Length': ''
}
conn.request("POST", "/api/v2/queue/callTakeover", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var client = new RestClient("{{brand}}/api/v2/queue/callTakeover");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
var body = @"{" + "\n" +
@"    ""ssid"":""{{ssid}}""," + "\n" +
@"    ""callId"":""{{callid}}""," + "\n" +
@"    ""agentid"":""{{agentid}}""" + "\n" +
@"}";
request.AddParameter("text/plain", body,  ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
curl --location -g --request POST '{{brand}}/api/v2/queue/callTakeover' \
--data-raw '{
    "ssid":"{{ssid}}",
    "callId":"{{callid}}",
    "agentid":"{{agentid}}"
}'
var request = http.Request('POST', Uri.parse('{{brand}}/api/v2/queue/callTakeover'));
request.body = '''{\n    "ssid":"{{ssid}}",\n    "callId":"{{callid}}",\n    "agentid":"{{agentid}}"\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 := "%7B%7Bbrand%7D%7D/api/v2/queue/callTakeover"
   method := "POST"

   payload := strings.NewReader(`{
    "ssid":"{{ssid}}",
    "callId":"{{callid}}",
    "agentid":"{{agentid}}"
}`)

   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/queue/callTakeover HTTP/1.1
Host: {{brand}}
Content-Length: 81

{
    "ssid":"{{ssid}}",
    "callId":"{{callid}}",
    "agentid":"{{agentid}}"
}
OkHttpClient client = new OkHttpClient().newBuilder()
   .build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "{\n    \"ssid\":\"{{ssid}}\",\n    \"callId\":\"{{callid}}\",\n    \"agentid\":\"{{agentid}}\"\n}");
Request request = new Request.Builder()
   .url("{{brand}}/api/v2/queue/callTakeover")
   .method("POST", body)
   .addHeader("Content-Length", "")
   .build();
Response response = client.newCall(request).execute();
var myHeaders = new Headers();
myHeaders.append("Content-Length", "");

var raw = "{\n    \"ssid\":\"{{ssid}}\",\n    \"callId\":\"{{callid}}\",\n    \"agentid\":\"{{agentid}}\"\n}";

var requestOptions = {
   method: 'POST',
   headers: myHeaders,
   body: raw,
   redirect: 'follow'
};

fetch("{{brand}}/api/v2/queue/callTakeover", 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, "%7B%7Bbrand%7D%7D/api/v2/queue/callTakeover");
   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    \"ssid\":\"{{ssid}}\",\n    \"callId\":\"{{callid}}\",\n    \"agentid\":\"{{agentid}}\"\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:@"%7B%7Bbrand%7D%7D/api/v2/queue/callTakeover"]
   cachePolicy:NSURLRequestUseProtocolCachePolicy
   timeoutInterval:10.0];
NSDictionary *headers = @{
   @"Content-Length": @""
};

[request setAllHTTPHeaderFields:headers];
NSData *postData = [[NSData alloc] initWithData:[@"{\n    \"ssid\":\"{{ssid}}\",\n    \"callId\":\"{{callid}}\",\n    \"agentid\":\"{{agentid}}\"\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    \"ssid\":\"{{ssid}}\",\n    \"callId\":\"{{callid}}\",\n    \"agentid\":\"{{agentid}}\"\n}";;

let reqBody = 
   let uri = Uri.of_string "%7B%7Bbrand%7D%7D/api/v2/queue/callTakeover" 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    `"ssid`":`"{{ssid}}`",`n    `"callId`":`"{{callid}}`",`n    `"agentid`":`"{{agentid}}`"`n}"

$response = Invoke-RestMethod '{{brand}}/api/v2/queue/callTakeover' -Method 'POST' -Headers $headers -Body $body
$response | ConvertTo-Json
require "uri"
require "net/http"

url = URI("{{brand}}/api/v2/queue/callTakeover")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Post.new(url)
request["Content-Length"] = ""
request.body = "{\n    \"ssid\":\"{{ssid}}\",\n    \"callId\":\"{{callid}}\",\n    \"agentid\":\"{{agentid}}\"\n}"

response = http.request(request)
puts response.read_body
printf '{
    "ssid":"{{ssid}}",
    "callId":"{{callid}}",
    "agentid":"{{agentid}}"
}'| http  --follow --timeout 3600 POST '{{brand}}/api/v2/queue/callTakeover' \
 Content-Length:
import Foundation
#if canImport(FoundationNetworking)
import FoundationNetworking
#endif

var semaphore = DispatchSemaphore (value: 0)

let parameters = "{\n    \"ssid\":\"{{ssid}}\",\n    \"callId\":\"{{callid}}\",\n    \"agentid\":\"{{agentid}}\"\n}"
let postData = parameters.data(using: .utf8)

var request = URLRequest(url: URL(string: "{{brand}}/api/v2/queue/callTakeover")!,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":"Wed
 01 Oct 2025 11:47:19 GMT"}
{"key":"Content-Type"
"value":"application\/json; charset=utf-8"}
{"key":"Content-Length"
"value":"73"}
{"key":"Connection"
"value":"keep-alive"}
{"key":"Access-Control-Allow-Origin"
"value":"*"}
{"key":"Access-Control-Allow-Methods"
"value":"GET
 PUT
 POST
 DELETE
 OPTIONS"}
{"key":"Access-Control-Allow-Headers"
"value":"session-token
Authorization
Origin
Accept
Content-Type
DNT
Authorization
Keep-Alive
User-Agent
X-Requested-With
If-Modified-Since
Cache-Control
Content-Type
Content-Range
Range"}
{"key":"Access-Control-Allow-Credentials"
"value":"true"}
{"key":"Vary"
"value":"Origin"}
{"key":"ETag"
"value":"W\/\"49-8H2mQbuNJIjbDY0n2Deu2JqLEpo\""}
{"key":"Strict-Transport-Security"
"value":"max-age=15724800; includeSubDomains"}
{"key":"Access-Control-Max-Age"
"value":"1728000"}]
 {
    "status": "error",
    "message": "Live call not found or invalid",
    "code": 1000
}