Enterprise Chat and Email Develper s Guide t Web Service APIs fr Chat, Release 11.6(1) Fr Unified Cntact Center Enterprise August 2017 Americas Headquarters Cisc Systems, Inc. 170 West Tasman Drive San Jse, CA 95134-1706 USA http://www.cisc.cm Tel: 408 526-4000 800 553-NETS (6387) Fax: 408 527-0883
THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL STATEMENTS, INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY PRODUCTS. THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE INFORMATION PACKET THAT SHIPPED WITH THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE OR LIMITED WARRANTY, CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY. The Cisc implementatin f TCP header cmpressin is an adaptatin f a prgram develped by the University f Califrnia, Berkeley (UCB) as part f UCBs public dmain versin f the UNIX perating system. All rights reserved. Cpyright 1981, Regents f the University f Califrnia. NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE SUPPLIERS ARE PROVIDED "AS IS" WITH ALL FAULTS. CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THOSE OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE. IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGES, INCLUDING, WITHOUT LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Any Internet Prtcl (IP) addresses and phne numbers used in this dcument are nt intended t be actual addresses and phne numbers. Any examples, cmmand display utput, netwrk tplgy diagrams, and ther figures included in the dcument are shwn fr illustrative purpses nly. Any use f actual IP addresses r phne numbers in illustrative cntent is unintentinal and cincidental. Cisc and the Cisc lg are trademarks r registered trademarks f Cisc and/r its affiliates in the U.S. and ther cuntries. T view a list f Cisc trademarks, g t http://www.cisc.cm/g/trademarks. Third-party trademarks mentined are the prperty f their respective wners. The use f the wrd partner des nt imply a partnership relatinship between Cisc and any ther cmpany. (1110R) Enterprise Chat and Email Develper s Guide t Web Service APIs fr Chat: Fr Unified Cntact Center Enterprise. September 5, 2017 Cpyright 2006 2017, Cisc Systems, Inc. All rights reserved.
Cntents 1. Abut this Guide 6 2. Obtaining Dcumentatin and Submitting a Service Request 6 3. Dcumentatin Feedback 6 4. Field Alerts and Field Ntices 6 5. Dcument Cnventins 6 6. Other Learning Resurces 7 Online Help... 7 Dcument Set... 7 7. Intrductin 8 Supprted Versins... 8 8. Schema Definitins 9 9. Display chat ptin based n agent availability 9 Request... 9 URL Parameters... 9 Request Headers... 9 Request Bdy... 9 XSD fr Request Bdy... 9 Sample Request XML... 10 Respnse... 10 Status cdes... 10 Respnse Headers... 10 Respnse Bdy... 10 XSD fr Respnse Bdy... 10 10. Display chat ptin based n agent capacity fr chats 10 Enterprise Chat and Email Develper s Guide t Web Service APIs fr Chat Page 3
Request... 11 URL Parameters... 11 Request Headers... 11 Request Bdy... 11 XSD fr Request Bdy... 11 Sample Request XML... 11 Respnse... 11 Status cdes... 11 Respnse Headers... 12 Respnse Bdy... 12 XSD fr Respnse Bdy... 12 11. Display chat ptin based n queue depth and wait time 12 Request... 12 URL Parameters... 12 Request Headers... 13 Request Bdy... 13 XSD fr Request Bdy... 13 Sample Request XML... 13 Respnse... 13 Status cdes... 13 Respnse Headers... 13 Respnse Bdy... 13 XSD fr Respnse Bdy... 14 12. Display chat ptin based n queue depth and agent availability 14 Request... 14 URL Parameters... 14 Request Headers... 14 Request Bdy... 14 XSD fr Request Bdy... 15 Sample Request XML... 15 Respnse... 15 Status cdes... 15 Respnse Headers... 15 Respnse Bdy... 15 XSD fr Respnse Bdy... 15 13. Display chat ptin based n queue depth, agent availability, and entry pint status 16 Enterprise Chat and Email Develper s Guide t Web Service APIs fr Chat Page 4
Request... 16 URL Parameters... 16 Request Headers... 16 Request Bdy... 16 XSD fr Request Bdy... 16 Sample Request XML... 17 Respnse... 17 Status cdes... 17 Respnse Headers... 17 Respnse Bdy... 17 XSD fr Respnse Bdy... 18 14. Submit custm chat surveys 18 Request... 18 URL Parameters... 18 Request Headers... 18 Request Bdy... 18 XSD fr Request Bdy... 18 Sample Request XML... 19 Respnse... 19 Status cdes... 19 Respnse Headers... 19 Respnse Bdy... 19 XSD fr Respnse Bdy... 19 Enterprise Chat and Email Develper s Guide t Web Service APIs fr Chat Page 5
Welcme t the Enterprise Chat and Email (ECE) feature, which prvides multichannel interactin sftware used by businesses all ver the wrld as a cre cmpnent t the Unified Cntact Center Enterprise prduct line. ECE ffers a unified suite f the industry s best applicatins fr chat and email interactin management t enable a blended agent fr handling f web chat, email and vice interactins. 1. Abut this Guide The Develpers Guide t Web Service APIs fr Chat describes hw custmers can use the Chat Web Services APIs t shw the Chat link n their web sites based n queue depth and the availability f agents t handle new chats. 2. Obtaining Dcumentatin and Submitting a Service Request Fr infrmatin n btaining dcumentatin, using the Cisc Bug Search Tl (BST), submitting a service request, and gathering additinal infrmatin, see What's New in Cisc Prduct Dcumentatin, at: http://www.cisc.cm/c/en/us/td/dcs/general/whatsnew/whatsnew.html. Subscribe t What's New in Cisc Prduct Dcumentatin, which lists all new and revised Cisc technical dcumentatin as an RSS feed and delivers cntent directly t yur desktp using a reader applicatin. The RSS feeds are a free service. 3. Dcumentatin Feedback T prvide cmments abut this dcument, send an email message t the fllwing address: mailt:cntactcenterprducts_dcfeedback@cisc.cm We appreciate yur cmments. 4. Field Alerts and Field Ntices Cisc prducts may be mdified r key prcesses may be determined t be imprtant. These are annunced thrugh use f the Cisc Field Alerts and Cisc Field Ntices. Yu can register t receive Field Alerts and Field Ntices thrugh the Prduct Alert Tl n Cisc.cm. This tl enables yu t create a prfile t receive annuncements by selecting all prducts f interest. Lg int www.cisc.cm and then access the tl at http://www.cisc.cm/cisc/supprt/ntificatins.html 5. Dcument Cnventins This guide uses the fllwing typgraphical cnventins. Enterprise Chat and Email Develper s Guide t Web Service APIs fr Chat Page 6
Cnventin Italic Bld Mnspace Variable Indicates Emphasis. Or the title f a published dcument. Labels f items n the user interface, such as buttns, bxes, and lists. Or text that must be typed by the user. The name f a file r flder, a database table clumn r value, r a cmmand. User-specific text; varies frm ne user r installatin t anther. 6. Other Learning Resurces Varius learning tls are available within the prduct, as well as n the prduct CD and ur web site. Yu can als request frmal end-user r technical training. Online Help The prduct includes tpic-based as well as cntext-sensitive help. Use Help buttn F1 keypad buttn T View Tpics in Enterprise Chat and Email Help; the Help buttn appears in the cnsle tlbar n every screen. Cntext-sensitive infrmatin abut the item selected n the screen. Dcument Set The Enterprise Chat and Email dcumentatin is available in the Dcuments flder n the prduct CD. The latest versins f all Cisc dcumentatin can be fund nline at http://www.cisc.cm The dcument set cntains the fllwing guides: System Requirements fr Enterprise Chat and Email Enterprise Chat and Email Installatin Guide Enterprise Chat and Email Brwser Settings Guide User guides fr agents and supervisrs Enterprise Chat and Email Agent s Guide Enterprise Chat and Email Supervisr s Guide User guides fr administratrs Enterprise Chat and Email Develper s Guide t Web Service APIs fr Chat Page 7
Enterprise Chat and Email Administratr s Guide t Administratin Cnsle Enterprise Chat and Email Administratr s Guide t Ruting and Wrkflws Enterprise Chat and Email Administratr s Guide t Chat and Cllabratin Resurces Enterprise Chat and Email Administratr s Guide t Email Resurces Enterprise Chat and Email Administratr s Guide t Data Adapters Enterprise Chat and Email Administratr s Guide t Reprts Cnsle Enterprise Chat and Email Administratr s Guide t System Cnsle Enterprise Chat and Email Administratr s Guide t Tls Cnsle 7. Intrductin Enterprise Chat and Email custmers can use the Chat Web Services APIs t shw the Chat link n their web sites based n the availability f agents t handle new chats. The APIs can be used fr fllwing purpses: T enable r disable the Chat buttn n web sites depending n available agents. T get the amunt f time a custmer might have t wait befre an agent is available t chat. T find the psitin f custmer in a queue t estimate hw lng a custmer might have t wait befre an agent is available t chat. Write new custm surveys fr chat sessins t capture additinal data. The API implementatin fllws standards fr REST-based APIs and prvides annymus access. The API returns data in XML frmat. Supprted Versins ECE 11.6 Enterprise Chat and Email Develper s Guide t Web Service APIs fr Chat Page 8
8. Schema Definitins The schema definitins used in web services are available as XSD files in the distributin. Yu can use the PackIt tl t extract the schema definitins. They are lcated in the eservice.ear file at the lcatin lib/int/egpl_applicatin_server.jar/cm/egain/live/framewrk/bsh/xsd. 9. Display chat ptin based n agent availability Check if there are any available agents (defined as the Available fr chat check bx being selected in the Agent Cnsle) wh can handle chats that start frm a specific entry pint. Use this API t decide t shw r hide the chat link n the website based n agent availability. Request A request t check agent availability has the fllwing frm: Methd GET URL /egain/chat/entrypint/agentavailability/id URL PARAMETERS Name Descriptin Type Required Default value fr ptinal parameters ID The ID f the entry pint fr which yu want t check the agent availability. lng Yes REQUEST HEADERS REQUEST BODY Nne XSD FOR REQUEST BODY Enterprise Chat and Email Develper s Guide t Web Service APIs fr Chat Page 9
SAMPLE REQUEST XML Respnse The respnse includes HTTP status cde and a Respnse Bdy. STATUS CODES Success cdes: 200: The agent availability status is returned. A True respnse means an agent is available. A False respnse means n agent is available. Errr cdes: 500: Unable t retrieve agent availability infrmatin. RESPONSE HEADERS RESPONSE BODY HTTP/1.1 200 OK <?xml versin="1.0" encding="utf-8" standalne="yes"?> <agentavailability available="true" xmlns:ns2="http://bindings.egain.cm/chat" xmlns:ns4="urn:ietf:params:xml:ns:xmpp-stanzas" xmlns:ns3="jabber:client" xmlns:ns5="http://jabber.rg/prtcl/httpbind"/> XSD FOR RESPONSE BODY The XML schema is defined in the agentavailability nde in the egainbsh.xsd file. 10. Display chat ptin based n agent capacity fr chats Fetches the capacity f all agents t wrk n new chat activities in the queue mapped t the given entry pint. This API returns the difference between the maximum lad that all agents can take and the current lad f all agents in the queue f the entry pint. Use this API t decide t shw the Chat buttn r ffer new chats t custmers nly when there are agents available t receive mre wrk. Enterprise Chat and Email Develper s Guide t Web Service APIs fr Chat Page 10
Request A request t check agent capacity has the fllwing frm: Methd GET URL /egain/chat/entrypint/capacity/id URL PARAMETERS Name Descriptin Type Required Default value fr ptinal parameters ID The ID f the entry pint fr which yu want t check the agent capacity. lng Yes REQUEST HEADERS REQUEST BODY XSD FOR REQUEST BODY SAMPLE REQUEST XML Respnse The respnse includes HTTP status cde and a Respnse Bdy. STATUS CODES Success cdes: 200: The remaining capacity f agents fr the entry pint is returned. A psitive number reflects the remaining capacity. Zer means either there are n agents available in the system, r all agents are wrking t their maximum lad. Errr cdes: Enterprise Chat and Email Develper s Guide t Web Service APIs fr Chat Page 11
500: Unable t retrieve the infrmatin. RESPONSE HEADERS RESPONSE BODY Output is generated in an XML frmat. HTTP/1.1 200 OK <?xml versin="1.0" encding="utf-8" standalne="yes"?> <availableslts xmlns:ns2="http://bindings.egain.cm/chat" xmlns:ns4="urn:ietf:params:xml:ns:xmpp-stanzas" xmlns:ns3="jabber:client" xmlns:ns5="http://jabber.rg/prtcl/httpbind"> <ns2:cunt>4</ns2:cunt> </availableslts> XSD FOR RESPONSE BODY The XML schema is defined in the availableslts nde in the egainbsh.xsd file. 11. Display chat ptin based n queue depth and wait time Get details f the number f chats waiting in the queue fr assignment, and the estimated wait time in the queue. Use this API t decide t shw r hide the chat link n the website based n wait time and number f chats in the queue. Request A request t check queue wait time and number f chats in the queue has the fllwing frm: Methd GET URL /egain/chat/entrypint/livesessinstatus/id URL PARAMETERS Name Descriptin Type Required Default value fr ptinal parameters ID The ID f the entry pint fr which yu want t check the queue depth and the wait time. lng Yes Enterprise Chat and Email Develper s Guide t Web Service APIs fr Chat Page 12
REQUEST HEADERS REQUEST BODY XSD FOR REQUEST BODY SAMPLE REQUEST XML Respnse The respnse includes HTTP status cde and a Respnse Bdy. STATUS CODES Success cdes: 200: Queue depth and wait time are returned. Errr cdes: 500: Unable t retrieve the queue depth and wait time. RESPONSE HEADERS RESPONSE BODY Output is generated in an XML frmat. HTTP/1.1 200 OK <?xml versin="1.0" encding="utf-8" standalne="yes"?> <sessinstatus xmlns:ns2="http://bindings.egain.cm/chat" xmlns:ns4="urn:ietf:params:xml:ns:xmpp-stanzas" xmlns:ns3="jabber:client" xmlns:ns5="http://jabber.rg/prtcl/httpbind"> <ns2:waittime>3.0</ns2:waittime> <ns2:queuedepth>1</ns2:queuedepth> </sessinstatus> Enterprise Chat and Email Develper s Guide t Web Service APIs fr Chat Page 13
XSD FOR RESPONSE BODY The XML schema is defined in the sessinstatus nde in the egainbsh.xsd file. 12. Display chat ptin based n queue depth and agent availability Checks eligibility f a chat entry pint t handle new chat activities based n the fllwing cnditins: 1. If there are any agents available t wrk n new chat activities. 2. If the queue assciated with that entry pint has reached its cnfigured maximum depth i.e. ttal number f chats being prcessed by the queue is equal t the maximum number f chats that the queue can prcess at any given pint f time. Use this API t decide t shw r hide the chat link n the website based n agent availability and whether the queue assciated with the given entry pint can accept mre chats. Request A request t check eligibility f chat entry pint has the fllwing frm: Methd GET URL /egain/chat/entrypint/checkeligibility/id URL PARAMETERS Name Descriptin Type Required Default value fr ptinal parameters ID The ID f the entry pint fr which yu want t check. lng Yes REQUEST HEADERS REQUEST BODY Enterprise Chat and Email Develper s Guide t Web Service APIs fr Chat Page 14
XSD FOR REQUEST BODY SAMPLE REQUEST XML Respnse The respnse includes HTTP status cde and a Respnse Bdy. STATUS CODES Success cdes: 200: Entry pint eligibility is returned. This is identified by value f the attribute respnsetype. This attribute can have any ne f the fllwing values: 0: The queue assciated with this entry pint can handle new chats. 1: N agent is available t wrk n new chats. 2: Maximum queue depth has reached fr the queue assciated with the given entry pint and n new chats will be prcessed. Errr cdes: 500: Unable t retrieve the eligibility f chat entry pint. RESPONSE HEADERS RESPONSE BODY Output is generated in an XML frmat. HTTP/1.1 200 OK <?xml versin="1.0" encding="utf-8" standalne="yes"?> <checkeligibility xmlns:ns2="http://bindings.egain.cm/chat" xmlns:ns4="urn:ietf:params:xml:ns:xmpp-stanzas" xmlns:ns3="jabber:client" xmlns:ns5="http://jabber.rg/prtcl/httpbind" respnsetype=0 /> XSD FOR RESPONSE BODY The XML schema is defined in the checkeligibility nde in the egainbsh.xsd file. Enterprise Chat and Email Develper s Guide t Web Service APIs fr Chat Page 15
13. Display chat ptin based n queue depth, agent availability, and entry pint status Checks if new chats can be prcessed by a given chat entry pint based n the fllwing cnditins: 1. Chat entry pint is active. 2. If there are any agents available t wrk n new chat activities. 3. If the queue assciated with that entry pint has reached its cnfigured maximum depth i.e. ttal number f chats being prcessed by the queue is equal t the maximum number f chats that queue can prcess at any given pint f time. Use this API t decide t shw r hide the chat link n the website based n the state f the chat entry pint, agent availability, and whether the queue assciated with the given entry pint can accept mre chats. Request A request t check if new chats can be prcessed by chat entry pint has the fllwing frm: Methd GET URL /egain/chat/entrypint/chatallwed/id URL PARAMETERS Name Descriptin Type Required Default value fr ptinal parameters ID The ID f the entry pint fr which yu want t check. lng Yes REQUEST HEADERS REQUEST BODY XSD FOR REQUEST BODY Enterprise Chat and Email Develper s Guide t Web Service APIs fr Chat Page 16
SAMPLE REQUEST XML Respnse The respnse includes HTTP status cde and a Respnse Bdy. STATUS CODES Success cdes: 200: If new chats can be prcessed by entry pint is returned. This is identified by value f the attribute allwed. This attribute can have value either true r false. If it is true, that means this entry pint can handle new chats. If it is false, that means this entry pint cannt handle new chats. If the value is false, attribute reasn can have ne f the belw mentined values t identify the cause if unavailability: queue_depth_reached: Maximum queue depth has reached fr the queue assciated with the given entry pint and n new chat will be prcessed. agent_nt_available: N agent is available t wrk n new chat. service_nt_running: Agent assignment service is nt running. invalid_entry_pint: Entry pint passed in the request is nt valid. entry_pint_inactive: Entry pint passed in the request is nt active. Other: This entry pint cannt handle new chats due t ther reasns. Errr cdes: 500: Unable t retrieve whether this entry pint can handle new chats. RESPONSE HEADERS RESPONSE BODY Output is generated in an XML frmat. HTTP/1.1 200 OK <?xml versin="1.0" encding="utf-8" standalne="yes"?> <chatallwed xmlns:ns2="http://bindings.egain.cm/chat" xmlns:ns4="urn:ietf:params:xml:ns:xmpp-stanzas" xmlns:ns3="jabber:client" xmlns:ns5="http://jabber.rg/prtcl/httpbind" allwed="true"/> OR HTTP/1.1 200 OK <?xml versin="1.0" encding="utf-8" standalne="yes"?> Enterprise Chat and Email Develper s Guide t Web Service APIs fr Chat Page 17
<chatallwed xmlns:ns2="http://bindings.egain.cm/chat" xmlns:ns4="urn:ietf:params:xml:ns:xmpp-stanzas" xmlns:ns3="jabber:client" xmlns:ns5="http://jabber.rg/prtcl/httpbind" allwed="false" reasn="entry_pint_inactive"/> XSD FOR RESPONSE BODY The XML schema is defined in the chatallwed nde in the egainbsh.xsd file. 14. Submit custm chat surveys This API can be used t submit custm survey frms shwn at the end f chat sessin. Request Methd POST URL /egain/chat/entrypint/survey URL PARAMETERS REQUEST HEADERS REQUEST BODY The Request Bdy needs t be in XML frmat. The fllwing table describes the required and ptinal attributes that can be used t submit a survey. Name Descriptin Type Required Questin Questin which is part f the survey that is displayed t the custmer. String Yes Answer Answer t the crrespnding questin. String Yes XSD FOR REQUEST BODY The XML schema is defined in the egainsurvey nde in the egainsurvey.xsd file. Enterprise Chat and Email Develper s Guide t Web Service APIs fr Chat Page 18
SAMPLE REQUEST XML <egainsurvey sid="1000"> <survey> <questin>questin 1</questin> <answer>answer 1</answer></survey> <survey><questin>questin 2</questin> <answer>answer 2</answer></survey> <survey><questin>questin 3</questin> <answer>answer 3</answer></survey> <survey><questin>questin 4</questin> <answer>answer 4</answer></survey> </egainsurvey> Respnse The respnse includes HTTP status cde. STATUS CODES Success cdes: 204: Survey is submitted successfully. RESPONSE HEADERS RESPONSE BODY XSD FOR RESPONSE BODY Enterprise Chat and Email Develper s Guide t Web Service APIs fr Chat Page 19