Webex Meetings > Develop and Test > WebACD API


WebACD Server SOAP API

WebACD provides a set of public SOAP APIs for 3rd party applications. These APIs are used to interact with the WebACD server via SOAP / XML calls. The format of these APIs are based on Web Services / SOAP to align with the future SOAP architecture of Webex's integration platform.
All SOAP APIs have the form:

Note: https://[SITE_NAME].webex.com/[SITE_NAME]/webacd/acd.wbx

[SITE_NAME] is the Webex site name.


SOAP Envelope/WSDL Overview

This section presents the details for generating SOAP messages using the WebACD WSDL. WSDL allows a user to determine what functions are available on the server. The client is then able to use SOAP to call one of the functions listed by the WSDL. Any special data types are embedded in the WSDL in the form of an XML schema. A complete list of SOAP functions that are available through the WSDL is listed in Table 3-1.


SOAP APIs Summary

The table below describes the details of each SOAP API provided by WebACD. Click to easily navigate between sections.

SOAP API Action
List Available CSRs Returns a list of available CSRs for a queue.
List Queues Returns a list of queues and it's summary information.
Get Queue Status Returns the status of a queue and detailed queue information.
Routing Trigger Notification Routes a request from a previous trigger call.
Get Request Status Returns request status and detailed request information
Cancel Request Cancels a request made to the WebACD server.
Get CSR Status Returns CSR status.
Set CSR Status Sets CSR status.
Show Leave Message Form Third-party applications tells the WebACD server to show "leave-message" for a request.




List Available CSR

Return to SOAP API Summary
This API returns a list of CSRs with an "Available" status for a site or for a queue based on an input request.

List Available CSR Request Element

Element Name Value(s)/Limits Description Required
queueid If queueid = 0, returns all available CSRs for a site.
If queueid > 0, returns all available CSRs for a given queue.
If queueid < 0, invalid queueid. 		Unique identifier for a queue. Yes.


List Available CSRs request example:

 

?
1
  <get>     <type>csr</type>     <select>csr</select>     <where>       <and>         <eq>           <path>csr/status</path>           <value>Available</value>         </eq>         <eq>           <path>csr/queues/queueid</path>           <value>nnn</value>         </eq>       </and>     </where>   </get>



List Available CSR Response Elements

Element Name Value(s)/Limits Description Required
result SUCCESS/FAILURE Returns the result of the request  
exceptionID Possible return codes:
100: Invalid queue ID.
101: No available CSR.
102: Missing queue ID.
103: Wrong queue ID for a site
112: Not a WebACD enabled site. 		In case of FAILURE returns appropriate exceptionID. Yes.
reason N/A Error message for associated error code. Yes, if the return code is not 0.
csrs N/A CSRs elements that requests are routed to. Yes, if the return code is 0.
csr N/A CSR element that a request is routed to.  
csrID N/A Unique identifier for a CSR.  
name N/A Name of a CSR.  


List Available CSR response example:

 

?
1
2
3
4
<strong>Success:</strong>
     <wbxapi>     <securityContext>       <cred>1804289383</cred>     </securityContext>     <response>       <result>SUCCESS</result>     </response>     <return>       <csrs>         <csr>           <csrID>xxx</csrID>           <name>xxx</name>         </csr>       <csr>          ... ...       </csr>       </csrs>     </return>   </wbxapi>
<strong>Failure:</strong>
     <wbxapi>     <securityContext>       <cred>1804289383</cred>     </securityContext>     <response>       <result>FAILURE</result>       <reason>No available CSR</reason>       <exceptionID>101</exceptionID>     </response>   </wbxapi>



List Queues

Return to SOAP API Summary
This API returns a list of queues used to serve the customers for a site.

List Queues Request Element

Element Name Value(s)/Limits Description Required
name ID > 0 Unique identifier for a queue. Yes.


List Queue request example:

 

?
1
<get>   <type>queue</type>   <select>queue</select>   <where>     <all/>   </where> </get>



List Queues Response Elements

Element Name Value(s)/Limits Description Required
result SUCCESS/FAILURE Returns the result of the request  
exceptionID Possible return codes 112: Not a WebACD enabled site. In case of FAILURE returns appropriate exceptionID. Yes.
reason N/A Error message for associated error code if it is not 0. Yes, if the return code is not 0.
Queues N/A Queue elements. This API does not return WebACD personal queues. Yes, if the return code is 0.
Queue N/A Queue element. Yes.
queueID N/A Unique identifier for the queue. Yes.
name N/A Queue name. Yes.
status The possible queue statuses are:
Available: there are available agents monitoring the queues.
Unavailable: There is no agent monitoring the queue.
Shutdown: Queue has reached its waiting requests limit.
Closed: It is outside the queue's business hours. 		Status of queue. Yes.
URL N/A Entry form URL for a queue. Yes.
totalCSRs N/A Total number of CSRs assigned to a queue. Yes.
loginCSRs N/A Total number of CSRs logged in and monitoring a queue. Yes.
availableCSRs N/A Total number of CSRs available for a queue. Yes.


List Queues response example:

 

?
1
   <wbxapi>     <securityContext>       <cred>1804289383</crd>     </securityContext>     <response>       <result>         SUCCESS       </result>     </response>     <return>       <Queues>         <Queue>           <queueID>39447</queueID>           <name>xxx</name>           <status>Unavailable</status>           <URL>xxx</URL>           <totalCSRs>xx</totalCSRs>           <loginCSRs>xx</loginCSRs>           <availableCSRs>xx</availableCSRs>         </Queue>        <Queue>           ... ...        </Queue>       </Queues>     </return>   </webapi>




Get Queue Status

Return to SOAP API Summary
This API returns status and other information for a given queue. The possible queue statuses are:

  • Available: There are available agents monitoring the queue.
  • Unavailable: There are no agents monitoring the queue.
  • Shutdown: Queue has reached it's waiting requests limit.
  • Closed: It is outside of the queue's business hours.

Get Queue Status Request Element

Element Name Value(s)/Limits Description Required
id id > 0 Unique identifier for a queue. Yes.


Get Queue Status request example:

 

?
1
  <get>     <type>queue</type>     <select>queue</select>     <id>nnn</id>   </get>



Get Queue Status Response Elements

Element Name Value(s)/Limits Description Required
result SUCCESS/FAILURE Returns the result of the request  
exceptionID Possible return codes:
100: Invalid queue ID.
102: Missing queue ID.
103: Wrong queue ID for a site.
112: Not a WebACD enabled site. 		In case of FAILURE returns appropriate exceptionID. Yes.
reason N/A Error message for associated error code if it is not 0. Yes, if the return code is not 0.
queueID Return same queue ID from the request. Queue ID from SOAP request. Yes.
name N/A Queue name. Yes.
status The possible queue statuses are:
Available: there are available agents monitoring the queues.
Unavailable: There is no agent monitoring the queue.
Shutdown: Queue has reached its waiting requests limit.
Closed: It is outside the queue's business hours. 		Status of queue. Yes.
URL N/A Entry form URL for a queue. Yes.
totalCSRs N/A Total number of CSRs assigned to a queue. Yes.
loginCSRs N/A Total number of CSRs logged in and monitoring a queue. Yes.
availableCSRs N/A Total number of CSRs available for a queue. Yes.
waitingRequest N/A Number of waiting requests for a queue. Yes.
averageWaitTime N/A Average wait time for a queue.
The average wait time for a request in a queue is the average wait time for the last 30 requests that were accepted by CSRs for the queue. 		Yes.
queueOpenTime N/A When the queue opens. Yes.

For a personal queue, this URL will return the following data:

  • name: Personal Queue.
  • URL: Empty string.
  • totalCSRs: Number of WebACD agents for a site.
  • loginCSRs: Number of agents logged in to WebACD Inbox for a site.
  • availableCSRs: Number of available CSRs.
  • waitingRequest: 0.
  • averageWaitTime: 0.
  • queueOpenTime: Empty.


Get Queue Status response example:

 

?
1
  <wbxapi>     <securityContext>       <cred>1804289383</cred>     </securityContext>     <response>       <result>SUCCESS</result>     </response>     <return>       <queueID>xx</queueID>       <name>xx</name>       <status>Available/UnavailableShutdown/Closed</status>       <URL>xx</URL>       <totalCSRs>xx</totalCSRs>       <loginCSRs>xx</loginCSRs>       <availableCSRs>xx</availableCSRs>       <waitingRequest>\xx</waitingRequest>       <averageWaitTime>xx</averageWaitTime>       <queueOpenTime>Sun,Mon,Tue,Wed,Thu,Fri,Sat; OpenTime:7:30-20:30;TimeZone:-8</queueOpenTime>     </return>   </wbxapi>




Routing Trigger Notification

Return to SOAP API Summary
This API allows a third-party routing system to route a pending request from a previous routing trigger call.

Routing Trigger Notification Request Elements

Element Name Value(s)/Limits Description Required
requestID requestID > 0 requestID sent by routing trigger. Yes.
queueID queueID > 0 queueID sent by routing trigger. Yes.
routingID N/A Unique identifier for routing a request for a third-party routing system. Yes.
CSRs N/A CSR elements that requests are routed to. Yes.
CSRID N/A Unique identifier for a qualified CSR returned by a third-party routing system.. Yes.
CSRName N/A Name of the CSR.  


Routing Trigger Notification request example:

 

?
1
  <execute>     <task>RoutingTriggerNotification</task>     <XML>       <requestID>request ID</requestID>       <queueID>queue ID</queueID>       <routingID>routing ID</routingID>       <CSRs >         <CSR>           <CSRID>nnn</CSRID>           <CSRName>xxx</CSRName>         </CSR>       </CSRs>     </XML>   </execute>



Routing Trigger Notification Response Elements

Element Name Value(s)/Limits Description Required
ReturnCode Possible return codes:
104: Invalid request ID.
105: Missing request ID.
106: Wrong requestID for a site.
112: Not a WebACD enabled site.
115: Missing Routing ID.
116: Missing CSR element.
108: Invalid CSR ID.
109: Missing CSR ID.
110: Wrong CSR ID for a site.
111: CSR is not a WebACD agent. 		Return code for a request. Yes.
ErrorMessage N/A Error message for associated error code if it is not 0.  
RequestID N/A Data from the request. Yes.
QueueID N/A Data from the request. Yes.
RoutingID N/A Data from the request. Yes.
CSRs N/A Data from the request. Yes.
CSRID N/A Data from the request. Yes.
CSRName N/A Data from the request. Yes.


Routing Trigger Notification response example:

 

?
1
  <wbxapi>       <securityContext>           <cred>1804289383</cred>       </securityContext>       <response>           <result>SUCCESS</result>       </response>       <return>           <requestID>xx</requestID>           <queueID>xx</queueID>           <routingID>xx</routingID>          <CSRs>           <CSR>               <CSRID>xxx</CSRID>               <CSRNAME>xxx</CSRNAME>           </CSR>          </CSRs>       </return>   </wbxapi>




Get Request Status

Return to SOAP API Summary
This API returns a request's status and the queue status that the request is in. The possible request statuses are:

  • Accepted: Request was accepted by a CSR.
  • Waiting: Request is waiting for a CSR to accept
  • Cancelled: Request is cancelled by the customer.
Element Name Value(s)/Limits Description Required
id id > 0 RequestID Yes.


Get Request Status request example:

 

?
1
  <get>    <type>request</type>     <select>request</select>    <id>nnn</id>   </get>



Get Request Status Response Elements

Element Name Value(s)/Limits Description Required
response SUCCESS/FAILURE Returns the response for the request  
exceptionID Possible return codes:
104: Invalid request ID.
105: Missing request ID.
106: Wrong requestID for a site.
112: Not a WebACD enabled site. 		In case of FAILURE returns appropriate exceptionID. Yes.
reason N/A   Yes.
requestID N/A Unique identifier for the request. Yes.
status The possible request statuses are:
Accepted: Request accepted by a CSR.
Waiting: Request is waiting for a CSR to accept.
Cancelled: Request is cancelled by the customer. 		Status of a request. Yes.
queueID N/A Unique identifier for the queue. Yes.
queueName N/A Name of the queue. Yes.
requestposition N/A Request's position in the queue. WebACD Queue is a FIFO service. Yes.
availableCSRs N/A Total number of available CSRs for a queue. Yes.
waitingRequest N/A Number of requests waiting for a queue. Yes.
averageWaitTime N/A Average wait time for a queue. Average wait time for a request in a queue is the average wait time for the last 30 requests that were accepted by CSRs for the queue. Yes.
estimatedWaitTime N/A Estimated wait time for a request. Yes.


Get Request Status response example:

?
1
  <wbxapi>     <securityContext>       <cred>1804289383</cred>     </securityContext>     <response>       <result>SUCCESS</result>     </response>     <return>       <request>         <requestID>xxx</requestID>         <status>Waiting;</status>         <queueID>xxx</queueID>         <queueName>Joe_everybody</queueName>         <requestPosition>0</requestPosition>         <availableCSRs>0</availableCSRs>         <waitingRequest>0</waitingRequest>         <averageWaitTime>0</averageWaitTime>         <estimatedWaitTime>0</estimatedWaitTime>       </request>     </return>   </wbxapi>


For a personal queue request, this SOAP call returns the following data:

  • queueID: Personal queue ID.
  • queueName: Personal queue name.
  • requestPosition: Request position for a given CSR's personal queue request.
  • totalCSRs: 1.
  • loginCSRs: 1 if CSR is logged in; 0 if it is not.
  • availableCSRs: 1 if CSR is available; 0 if he is not available.
  • waitingRequest: # of personal queue requests for the CSR.
  • averageWaitTime: 0.
  • estimatedWaitTime: 0.




Cancel Request

Return to SOAP API Summary
This API cancels a particular request made to the WebACD server API.

Cancel Request Request Element

Element Name Value(s)/Limits Description Required
requestID requestID > 0 Unique identifier for the request. Yes.


Cancel Request request example:

 

?
1
  <SOAP-ENV:Body>     <execute>       <task>cancelRequest</task>       <XML>         <requestID>nnn</requestID>       </XML>     </execute>   </SOAP-ENV:Body>



Cancel Request Response Elements

Element Name Value(s)/Limits Description Required
ReturnCode Possible return codes:
104: Invalid request ID.
105: Missing request ID.
106: Wrong requestID for a site.
107: Can not cancel this request. CSR already accepted it.
112: Not a WebACD enabled site. 		  Yes.
ErrorMessage N/A Error message for associated error code if it is not 0. Yes, if the return code is not 0.
RequestID N/A Unique identifier for a SOAP request. Yes.


Cancel Request response example:

?
1
  <wbxapi>     <securityContext>       <cred>1804289383</cred>     </securityContext>     <response>       <result>SUCCESS</result>     </response>     <return>       <request>         <requestID>xxx</requestID>       </request>     </return>   </wbxapi>




Get CSR Status

Return to SOAP API Summary
This API returns the status of a CSR in the WebACD system. The possible CSR statuses are:

  • Available: Can take more requests.
  • Busy: Has reached it's maximum capacity.
  • Unavailable: Cannot take any more requests.
  • Disconnected: Not logged in.
Element Name Value(s)/Limits Description Required
id id > 0 Unique identifier for a CSR. Yes.


Get CSR Status request example:

 

?
1
  <SOAP-ENV:Body>     <get>       <type>csr</type>       <select>csr</select>       <id>nnn</id>     </get>     </SOAP-ENV:Body>



Get CSR Status Response Elements

Element Name Value(s)/Limits Description Required
result SUCCESS/FAILURE Returns the response for the request.
exceptionID Possible return codes: 108: Invalid CSR ID.
109: Missing CSR ID.
110: Wrong CSR ID for a site.
111: CSR is not a WebACD agent.
112; Not a WebACD enabled site. 		In case of FAILURE returns appropriate exceptionID. Yes.
reason N/A    
maxSessions N/A    
currentSessions N/A    
status The possible CSR statuses are:
Available: can take more requests.
Busy: Has reach his maximum capacity.
Unavailable: Cannot take more requests.
Disconnected: Not logged in.s 		Current CSR status.  
csrID N/A   CSR ID from its SOAP request


Get CSR Status response example:

?
1
  <wbxapi>     <securityContext>       <cred>1804289383</cred>     </securityContext>     <response>       <result>SUCCESS</result>     </response>     <return>     <csr>       <csrID>xxx</csrID>       <name>xxx</name>       <status>Busy/Available/Unavailable/Disconnected</status>       <maxSessions>xx</maxSessions>       <currentSessions>xxx</currentSessions>       </csr>     </return>   </wbxapi>




Set CSR Status

Return to SOAP API Summary
This API sets a CSR's status in the WebACD system. The possible CSR statuses are:

  • Available: Can take more requests.
  • Busy: Has reached it's maximum capacity.
  • Unavailable: Cannot take any more requests.



Set CSR Status Request Elements

Element Name Value(s)/Limits Description Required
id id > 0 Unique identifier for a CSR. Yes.
status N/A The status that the CSR will be set to. Yes.


Set CSR Status request example:

 

?
1
  <set>     <type>csr</type>     <id>nnn</id>     <xml>       <csr>         <status>Busy/Available/Unavailable</status>       </csr>     </xml>   </set>



Set CSR Status Response Elements

Element Name Value(s)/Limits Description Required
result SUCCESS/FAILURE Returns result of the request.  
exceptionID Possible return codes:
108: Invalid CSR ID.
109: Missing CSR ID.
110: Wrong CSR ID for a site.
111: CSR is not a WebACD agent.
112: Not a WebACD enabled site.
113: Invalid CSR status.
114: Missing status. 		In case of FAILURE returns appropriate exceptionID.  
reason N/A Error message for associated error code if it is not 0. Yes, if the return code is not 0.
status N/A CSR status sets to this after SOAP request. CSR status sets to this after SOAP request. Yes, if the return code is not 0
id N/A Unique identifier for the CSR. ; Yes, if the return code is not 0


Set CSR Status response example:

?
1
  <wbxapi>     <securityContext>       <cred>1804289383</cred>     </securityContext>     <response>       <result>SUCCESS</result>     </response>     <return>       <csr>         <id>xxx</id>         <status>Busy/Available/Unavailable/Disconnected</status>       </csr>     </return>   </wbxapi>

The following shows the CSR status for each possible condition.



CSR Status Conditions

Element Name Value(s)/Limits Description Required
Available Available
Busy
Unavailable
Disconnected 		N/A
CSR has max sessions
CSR does not have max sessions
N/A 		Available
Busy
Busy
Available
Disconnected
Busy Available
Busy
Unavailable
Disconnected 		N/A
N/A
N/A
N/A 		Busy
Unavailable
Busy
Disconnected
Unavailable Available
Busy
Unavailable
Disconnected 		N/A
N/A
N/A
N/A 		Unavailable
Unavailable
Unavailable
Disconnected




Show Leave Message Form

Return to SOAP API Summary
This API is used by third-party applications to tell the WebACD server to show a leave-message for a request.



Show Leave Message Form Request Elements

Element Name Value(s)/Limits Description Required
requestID requestID > 0   Yes.
message length limitation: 1k Message for ¿show leave message'.
WebACD needs to send this message to SC (or other integrated services).
SC / Services decides how to use this message. 		 


Show Leave Message Form request example:

 

?
1
  <execute>     <task>showLeaveMessageForm</task>     <XML>       <requestID>nnn<requestID>       <message>message text</message>     </XML>



Show Leave Message Form Response Elements

Element Name Value(s)/Limits Description Required
result SUCCESS/FAILURE Returns result of the request.  
exceptionID Possible return codes:

104: Invalid request ID.
105: Missing request ID.
106: Wrong requestID for a site.
112: Not a WebACD enabled site. 		In case of FAILURE returns appropriate exceptionID.  
reason N/A Error message for associated error code if it is not 0. Yes, if the return code is not 0.
requestID N/A Unique identifier for the request. Yes.


Set CSR Status response example:

?
1
  <wbxapi>     <securityContext>       <cred>1804289383</cred>     </securityContext>     <response>       <result>SUCCESS</result>     </response>     <return>       <csr>         <id>xxx</id>         <status>Busy/Available/Unavailable/Disconnected</status>       </csr>     </return>   </wbxapi>


Show Leave Message Form response example:

 

?
1
  <wbxapi>     <securityContext>       <cred>1804289383<cred>     <securityContext>     <response>       <result>SUCCESS<result>     <response>     <return>      <request>       <requestID>xxx<requestID>      <request>     <return>   <wbxapi>