API Overview and Developer s Guide

Transcription

1 API Overview and Developer s Guide 08/27/2012 Americas Headquarters OAISYS 7965 South Priest Drive, Suite 105 Tempe, AZ USA

2 CONTENTS Overview... 4 Questions to Consider When Choosing an API... 5 Standards Compliance... 5 Development Platforms... 6 API Permissions... 7 ASCII Stream API... 8 Tracer Web Services... 8 Web Services API... 8 Stored Procedures... 9 Playback API... 9 Desktop Client API... 9 DtAPI Supported Versions and Supported Recording Options Starter Account ASCII Stream API (Real-Time) Commands Command References General Purpose Predictive Dialer Commands MS Lync Commands Real-Time Recording Commands Older Dialer Legacy Support Search and Update Commands ASCII Stream API (Historical) Commands Playback API URL Structure Commands Desktop Client API Backwards Compatibility The Third-Party Application Libraries OAISYS API Overview and Developer s Guide 1

3 .NET Constructors General Events Properties General Methods Request Methods and Response Events Objects COM Side-By-Side COM Example Events Properties Methods Objects Desktop Client API (Deprecated) Methods Properties Tracer Web Services Backward Compatibility Security Location Supported Web Services Session Identifier Object-Oriented API TWS Discovery and Code Generation Tracer Networking The API Session.asmx HistoricalCalls.asmx LiveCalls.asmx Playback.ASHX Objects OAISYS API Overview and Developer s Guide 2

4 Web Services API (Deprecated) PVDtoWAV Service RecordingControl Service Stored Procedures Backwards Compatibility Stored Procedures Escaping the Single Quote in the Call Scripts Call Scripting Tokens Call Scripts Supported Search Fields and Operators Search Value Grammar Sample Searches Call-Sort Script Call-Select Script Basic Search The Find String Escape Sequences Executing the Search Call-Data Fields Extra-Call Info Fields Differences Between Call-Data Fields and Extra-Call Info Fields Sample Code About OAISYS OAISYS API Overview and Developer s Guide 3

5 OVERVIEW An application programming interface (API) is used to facilitate interaction between software applications. APIs allow applications to work together to solve a common problem. The OAISYS APIs allow external applications to send to and receive data from OAISYS products. OAISYS offers both server and client level APIs. The server includes three APIs: 1. ASCII stream API 2. A set of Microsoft SQL Server stored procedures 3. Web services AP Our clients include two APIs: 1. Real-time API 2. Playback API There is some overlap in the OAISYS APIs to allow maximum flexibility for our customers. Depending on the desired outcome, there may be benefits to using one API over the other. Example: A customer may have an IT person on staff that is comfortable and familiar with web services. This customer may be able to accomplish their goal with the ASCII Stream or the web services API. To use this document, you should be familiar with software development and the OAISYS call recording solution. OAISYS API Overview and Developer s Guide 4

6 QUESTIONS TO CONSIDER WHEN CHOOSING AN API What are you trying to achieve? Would you like to retrieve information from the OAISYS application? Do you want to attach information to a recording for future access restrictions or searching? Do you want to stop and start recordings from another application? What is your technology environment like? Is COM or.net technology viable at the desktop? What database technology do you use? Will you be performing an action during a live call or after the call has ended? Standards Compliance OAISYS APIs comply with the following specifications. STANDARD Web service description language (WSDL) 1.1 WEB SITE OAISYS API Overview and Developer s Guide 5

7 DEVELOPMENT PLATFORMS OAISYS software is built on Microsoft s.net framework v3.5. Any development platforms supporting.net 3.5 interoperability or COM interoperability can be used to develop desktop integration applications. Server-based applications can be developed using any development environment with which ASCII streams can be managed, SQL server commands can be issued or web services can be used. NOTE: In this document samples will be given in C# (.NET) unless otherwise stated. OAISYS API Overview and Developer s Guide 6

8 API Permissions This section reviews the procedures for configuration of the SQL API; each section is discussed in further detail on the following pages. For additional information on permissions configuration in OAISYS Management Studio Admin, refer to: API Member Required Permissions ASCII Stream API Application Resource Permission TWS HistoricalCalls.asmx CountCalls() Historical Calls Call Filter View documents in the listing and in the visualization. FindCalls() Historical Calls Call Filter View documents in the listing and in the visualization. Web Services API Stored Procedures Playback API Desktop API Web Services API DtApi2 RecordStartActiveCall() Live Calls Call Filter Start and Stop Recording OAISYS API Overview and Developer s Guide 7

9 ASCII Stream API The ASCII Stream API requires a socket layer; the programmer will develop this piece of the application. The ASCII Stream API can be used to control recording in real-time, attach information to recordings in progress, retrieve information from recordings in process, parse a single audio connection to a media server (e.g., a predictive dialer) into individual recordings with discrete call data and search for recordings using call information. Common Uses: Receive start and stop recording commands from a predictive dialing application Request information about the call such as the unique identifier of the call in progress Tracer Web Services Tracer Web Services allows integration between the OAISYS solution and a third-party application over a network. This open architecture natively supports SOAP and WSDL. Web Services API Web services are automated information services over IP networks that use standardized technologies and protocols that simplify the exchange and integration of large amounts of data over the internet. The fundamental protocol for web services is XML. Web services enable computers to talk to one another over the internet, allowing computer programs to exchange information by eliminating barriers such as different hardware platforms, software languages, and operating systems that usually make different programs incompatible. Common Uses: Search the database of online recordings for call identification information and other descriptive data OAISYS API Overview and Developer s Guide 8

10 Convert a recorded call into a standard audio compression and play it on my mobile device Stored Procedures A set of stored procedures are available that require authentication and provide account-restricted access to search for recordings, retrieve information about a recording and add new information to recordings. OAISYS products utilize Microsoft SQL Server as its backend platform. Common Uses: Query the OAISYS database for descriptive data about a set of recordings Use recording data in another reporting package such as Crystal Reports or Microsoft Excel Playback API The playback API is used to play back a recorded call from an application. This API is for use with historical calls, it is URL based and virtually any application that can open a URL can utilize this API. The playback API is used to search for recordings and load the list of matches into the OAISYS PVD Player. Common Uses: Search for recordings based on an outside party number match from a CRM application Provide links to playback recordings within a contact management application Desktop Client API This API is used to control recording on calls in progress, attach information to a call and retrieve information from the recording system in real-time. This is a real-time application to be used during calls in progress. OAISYS API Overview and Developer s Guide 9

11 Common Uses: Attach transactional information to a recording such as an invoice number Retrieve information about a live call such as the extension number or a reference to the recording DtAPI2 The Desktop Client API (DtAPI2) is an updated version of the Desktop Client API; these libraries are based on.net Framework 3.5. This API allows thirdparty applications interfacing with the Desktop Client to interact with the OAISYS recording solution. Common Uses: To start/stop recording through a third-party application Attach information to a call from a third-party application OAISYS API Overview and Developer s Guide 10

12 Supported Versions and Supported Recording Options Tracer and Talkument systems versions 6.2 and above support the APIs described in this document. Connection Type ASCII Stream Playback Desktop Client/COM Web Services Stored Procedures CTI Yes Yes Yes Yes Yes SMDR Yes (historical calls only) Yes No Yes Yes Station-side VOX Yes Yes Yes Yes Yes RTP Yes Yes Yes Yes Yes Trunk-side / No PBX data Yes (historical calls only) Yes No Yes Yes OAISYS API Overview and Developer s Guide 11

13 STARTER ACCOUNT To get a single user up and running in SQL API, perform the following steps. 1. From SQL mgmt.studio connect with oaisysguest/oaisys 2. This is the SQL API starter account 3. Create a SQL user account for a particular Tracer user Example: exec sp_tracer_login 'fred', 'Oaisys2011' 4. From SQL mgmt.studio connect with fred/oaisys2011 NOTE: Fred s view is restricted to a set of stored procedures that limit the scope of calls Fred may view and modify. 5. Get the 1 st page of 50 calls for Fred using default select/search/sort exec = = 0 6. Get the 1 st page of 50 calls for Fred for calls involved with outside number, , default select/sort exec = 'outside_number = = = 0 7. Get the 1 st page of 50 calls for Fred for calls since May 1, default select/sort exec = 'start_date_time >= = = 0 These stored procedures are helpful to discover the supported select, search, and sort fields: oaisysguest.sp_get_select_fields oaisysguest.sp_get_search_fields oaisysguest.sp_get_sort_fields OAISYS API Overview and Developer s Guide 12

14 ASCII STREAM API (REAL-TIME) COMMANDS The ASCII Stream API requires a socket layer; the programmer will develop this piece of the application. The ASCII Stream API can be used to control recording in real-time, attach information to recordings in progress, retrieve information from recordings in process, parse a single audio connection to a media server into individual recordings with discrete call data and search for recordings using call information. Common Uses: Receive start and stop recording commands from a predictive dialing application Request information about the call such as the unique identifier of the call in progress COMMAND REFERENCES Login GENERAL PURPOSE This command is sent to login and authenticate the user as well as check the operation of the interface and get version information. This must be the first command sent whenever an application first connects to the IP port because, until the user is authenticated, no subsequent commands will be processed. The recording system may require licensing to be enabled for use of the IP port, in which case the Login could fail if appropriate licensing is not available on the recording system. If the IP connection is dropped and reconnected, you must reissue a valid Login command. NOTE: Even if you re already logged in, it is okay to periodically send this Login request to (1) check to see if the connection is working and/or (2) check the local date/time, etc. COMMAND SYNTAX: G~LOGIN~<Req_ID>~<App_Name>~<User>~<Pass>~<Enable_Keep_Alive>~ crlf OAISYS API Overview and Developer s Guide 13

15 COMMAND : <Req_ID> <App_Name> <User> <Pass> <Enable_Keep_alive> A reference for the command to be used on the reply Name of client application that is connecting A valid username in the OAISYS database The correct password for the OAISYS username supplied in <User> Use this feature to receive periodic keep-alive messages from the OAISYS software as a method to validate connectivity. Send Y to enable this feature or any other character to disable it. Keep alive messages are sent in the form of the Login command response shown below. RESPONSE SYNTAX: RG~LOGIN~<Req_ID>~<Success/Fail>~<Reason>~<System>~<Version>~ <Local_DateTime>~crLf RESPONSE FIELDS: <Req_ID> <Success/Fail> <Reason> <System> <Version> <Local_DateTime> The value supplied in the command An S for success or F for failure. If F the <Reason> field will be populated If a failure occurred, this will include a text description of the failure reason Indicates whether the system includes a license for the Tracer Contact Center Management applications or not. The response will be Tracer if yes; otherwise it will return Talkument. The version number of the software in operation The date and time as programmed in the Windows OS of the OAISYS software host server. The value is returned in the format MM-DD-YYYY HH:MM:SS. Logout This command is sent to initiate logout and discontinue use of the IP port and OAISYS API Overview and Developer s Guide 14

16 associated licensing. NOTE: When the IP connection is dropped it has the same effect as issuing this command. COMMAND SYNTAX: G~LOGOUT~<Req_ID >~crlf COMMAND : <Req_ID> A reference for the command to be used on the reply RESPONSE SYNTAX: RG~LOGOUT~<Req_ID>~<Success/Fail>~<Reason>~crLf RESPONSE FIELDS: <Req_ID> <Success/Fail> <Reason> The value supplied in the command An S for success or F for failure. If S the <Reason> field may be omitted. If F the <Reason> field will be populated If a failure occurred, this will include a text description of the failure reason OAISYS API Overview and Developer s Guide 15

17 PREDICTIVE DIALER COMMANDS Predictive dialers and other media server applications typically require a telephone user to connect to the media server via a call that will last throughout an entire login session. The application server will then patch various external party calls into this user session based on available contact activity. This allows the media server full control over the user s telephone and results in highly efficient call processing. This can be problematic for recording systems that monitor the connection between the user s telephone and the media server as the signaling at this juncture of the communications network indicates a single, long call with no information about the external parties. This set of predictive dialer commands provides a mechanism for such an application to control the OAISYS recording solution, dictating whether to record or not, as well as to parse this long session (described as a master call ) into the various external calls (described as sub calls ) while also providing the external party information. Once engaged, it is the responsibility of the controlling application to send start and end commands for each sub call as well as the external party data as the OAISYS server acts as a slave under this condition. Start Master Call This command is sent to start a Master call. COMMAND SYNTAX: M~START~<Req_ID>~<M_Cnx_ID>~<trunkID>~<Stn_extension>~<agentID>~ crlf COMMAND : <Req_ID> <M_Cnx_ID> <trunkid> <Stn_extension> A reference to this command A unique reference for the master call The trunk and channel carrying the master call as programmed in the OAISYS VAT port settings The PBX extension ID that is logged into this master call OAISYS API Overview and Developer s Guide 16

18 <agentid> The agent ID for the telephone user, it maps to the ACDAGT field in the OAISYS database which allows it to be searched alongside ACD information from other contact center applications. Can be blank, in which case the ACDAGT field for the sub calls handled by this master call will be blank. RESPONSE SYNTAX: RM~START~<Req_ID>~<Success/Fail>~<Reason>crLf RESPONSE FIELDS: <Rec_ID> <Success/Fail> <Reason> The reference ID sent with the command An S for success or F for failure. If S the field may be omitted. If F the <Reason> field will be populated If a failure occurred, this will include a text description of the failure reason End Master Call This command is sent to end a Master call. COMMAND SYNTAX: M~END~<Req_ID>~<M_Cnx_ID>~crLf COMMAND : <Req_ID> <M_Cnx_ID> A reference to this command The master call reference ID RESPONSE SYNTAX: RM~END~<Req_ID>~<Success/Fail>~<Reason>~crLf OAISYS API Overview and Developer s Guide 17

19 RESPONSE FIELDS: <Rec_ID> <Success/Fail> <Reason> The reference ID sent with the command An S for success or F for failure. If S the <Reason> field may be omitted. If F the <Reason> field will be populated If a failure occurred, this will include a text description of the failure reason Start Sub Call This command is sent to start a Sub Call. COMMAND SYNTAX: S~START~<Req_ID>~<M_Cnx_ID>~<Call_Instance>~<Call_Type>~<Phone#>~<Recor dstart>~<requesting_ext>~crlf COMMAND : <Req_ID> <M_Cnx_ID> <Call_Instance> <Call_Type> <Phone#> <RecordStart> <Requesting_Ext> A reference to this command The master call reference ID A unique reference to the sub call Indicates the direction of the call. Send I for inbound calls and O for outbound calls. This is especially useful in blended contact centers where knowledge of the direction affects access privileges, recording retention rules and searchability. The external party telephone number with area code. Should be sent in pure numerical format (e.g ). Used to engage or override the recording rules in the OAISYS server. Send Y to start recording, N to not record or T to use the recording triggers programmed in the OAISYS server. Identifies the OAISYS user account to determine if permissions are enabled to override the OAISYS server s recording rules in the <RecordStart> parameter. If no extension ID is provided then the extension ID associated with the master call will be used. OAISYS API Overview and Developer s Guide 18

20 RESPONSE SYNTAX: RS~START~<Req_ID>~<Success/Fail>~<Reason>~crLf RESPONSE FIELDS: <Rec_ID> <Success/Fail> <Reason> The reference ID sent with the command An S for success or F for failure. If S the field may be omitted. If F the <Reason> field will be populated If a failure occurred, this will include a text description of the failure reason End Sub Call This command is sent to end a Sub call. COMMAND SYNTAX: S~END~<Req_ID>~<M_Cnx_ID>~<Call_Instance>~<KeepRecording>~<Requesting_Ex t>~crlf COMMAND : <Req_ID> <M_Cnx_ID> <Call_Instance> <KeepRecording> <Requesting_Ext> A reference to this command The master call reference ID A unique reference to the sub call Used to engage or override the recording rules in the OAISYS server. Send Y to start recording, N to stop recording or T to use the recording triggers programmed in the OAISYS server. Identifies the OAISYS user account to determine if permissions are enabled to override the OAISYS server s recording rules in the <KeepRecording> parameter. If no extension ID is provided then the extension ID associated with the master call will be used. RESPONSE SYNTAX: RS~END~<Req_ID>~<Success/Fail>~<Reason>~crLf OAISYS API Overview and Developer s Guide 19

21 RESPONSE FIELDS: <Rec_ID> <Success/Fail> <Reason> The reference ID sent with the command An S for success or F for failure. If S the <Reason> field may be omitted. If F the <Reason> field will be populated If a failure occurred, this will include a text description of the failure reason MS LYNC COMMANDS MS Lync applications can use these commands to control the call start and end - as well as the external party data as the OAISYS server acts as a slave under this condition. Start Call This command is sent to start a Call. COMMAND SYNTAX: SC~START~<Req_ID>~<Call_Instance>~<TrunkID>~<Call_Type>~<Phone#>~<Stn_ex tension>~<agentid>~<acdgrp>~<recordstart>~<requesting_ext>~<conferenceuri>~ <User>~<Pass>~crLf COMMAND : <Req_ID> <Call_Instance> <TrunkID> <Call_Type> <Phone#> A reference to this command A unique reference to the sub call [Optional] The trunk and channel carrying the master call as programmed in the OAISYS VAT port settings [Optional] Indicates the direction of the call. Send I for inbound calls and O for outbound calls. This is especially useful in blended contact centers where knowledge of the direction affects access privileges, recording retention rules and searchability. [Optional] The external party telephone number with area code. Should be sent in pure numerical format (e.g ). OAISYS API Overview and Developer s Guide 20

22 <Stn_extension> [Optional] A PBX extension ID. NOTE: this may not result in a unique call as one multi-line extension may handle multiple calls at one time. <AgentID> <ACDGrp> <RecordStart> <Requesting_Ext> <conferenceuri> <User> <Pass> [Optional] A contact center agent ID. [Optional] A contact center ACD group ID Used to engage or override the recording rules in the OAISYS server. Send Y to start recording, N to not record or T to use the recording triggers programmed in the OAISYS server. Identifies the OAISYS user account to determine if permissions are enabled to override the OAISYS server s recording rules in the <RecordStart> parameter. If no extension ID is provided then the extension ID associated with the master call will be used. Conference URI for OAISYS endpoint to connect and record [Optional] [Optional] RESPONSE SYNTAX: RSC~START~<Req_ID>~<Success/Fail>~<Reason>~crLf RESPONSE FIELDS: <Rec_ID> <Success/Fail> <Reason> The reference ID sent with the command An S for success or F for failure. If S the field may be omitted. If F the <Reason> field will be populated If a failure occurred, this will include a text description of the failure reason Endpoints Exceeded Total Endpoints = X where X is the total number of endpoints available in OAISYS End Call This command is sent to end a call. OAISYS API Overview and Developer s Guide 21

23 COMMAND SYNTAX: SC~END~<Req_ID>~<Call_Instance>~<KeepRecording>~<Requesting_Ext>~<User>~ <Pass>~crLf COMMAND : <Req_ID> <Call_Instance> <KeepRecording> <Requesting_Ext> <User> <Pass> A reference to this command A unique reference to the call Used to engage or override the recording rules in the OAISYS server. Send Y to start recording, N to stop recording or T to use the recording triggers programmed in the OAISYS server. Identifies the OAISYS user account to determine if permissions are enabled to override the OAISYS server s recording rules in the <KeepRecording> parameter. If no extension ID is provided then the extension ID associated with the master call will be used. [Optional] [Optional] RESPONSE SYNTAX: RSC~END~<Req_ID>~<Success/Fail>~<Reason>~crLf RESPONSE FIELDS: <Rec_ID> <Success/Fail> <Reason> The reference ID sent with the command An S for success or F for failure. If S the <Reason> field may be omitted. If F the <Reason> field will be populated If a failure occurred, this will include a text description of the failure reason Query Call This command is sent to get a list of existing (active) <ConferenceURI>, <Call_Instance>, and recording state. OAISYS API Overview and Developer s Guide 22

24 COMMAND SYNTAX: SC~QUERY~<Req_ID>~<ConferenceURI>~<Call_Instance>~crLf COMMAND : <Req_ID> <ConferenceURI> <Call_Instance> A reference to this command [Optional] [Optional] NOTE: If both <ConferenceURI> and <Call_Instance> are blank, then the query will return the entire list of all existing (active) <ConferenceURI>, <Call_Instance>, and recording state. If <ConferenceURI> or/and <Call_Instance> is/are specified, the value(s) will be used to find the corresponding call and return its recording state. RESPONSE SYNTAX: RSC~END~<Req_ID>~<ConferenceURI[1]>~<Call_Instance[1]>~<Rec_State[1]>~<Conf erenceuri[2]>~<call_instance[2]>~<rec_state[2]>~ ~ <ConferenceURI[N]>~<Call_Instance[N]>~<Rec_State[N]>~crLf RESPONSE FIELDS: <Rec_ID> <ConferenceURI> <Call_Instance> <Rec_State> The reference ID sent with the command ConferenceURI Call_Instance 0 Pause 1 Recording OAISYS API Overview and Developer s Guide 23

25 REAL-TIME RECORDING COMMANDS These commands are used to affect the OAISYS system s behavior toward calls in progress. These can be used to control recording, add information and retrieve information as well as to request an with a link to the recording once completed. Each of these commands uses five fields to help uniquely identify the call: 1. <Stn_extension> 2. <CTI_CID> 3. <CTI_CNX> 4. <TrunkID> 5. <AgentID> Any of these parameters may be sent as empty. The OAISYS software will use those that are not empty in an attempt to identify a unique call. If a unique call cannot be identified the command will return a failure code. STANDARD REAL-TIME : <Stn_extension> A PBX extension ID. <CTI_CID> <CTI_CNX> <TrunkID> <AgentID> NOTE: this may not result in a unique call as one multi-line extension may handle multiple calls at one time. The unique call identifier supplied by the PBX CTI link. NOTE: certain CTI formats do not provide unique call identifiers. NOTE: when used with the Predictive Dialing master call commands described earlier in this document, this field should be populated with the master call ID using the format M:<M_Cnx_ID>. For example, M:15. NOTE: when used with the MS Lync application call commands described earlier in this document, this field should be populated with the master call ID using the format SC:<Call_Instance>. For example, SC:15. Some PBX CTI links include this field, which when used in combination with a non-unique CTI_CID can produce a unique call. The trunk identification as programmed in the OAISYS database. When supplied this will almost always produce a unique call match as only one call can be carried by a given trunk channel at any given time. A contact center agent ID. OAISYS API Overview and Developer s Guide 24

26 Attach Info to Call This command is sent to request information to be attached to a call. COMMAND SYNTAX: C~ATTACH_INFO~<Req_ID>~<Stn_extension>~<CTI_CID>~<CTI_CNX>~<TrunkID>~ <AgentID>~< FieldName >~< Value >~<User>~<Pass>~crLf COMMAND (SEE STANDARD REAL-TIME ABOVE FOR THOSE NOT LISTED HERE): <Req_ID> < FieldName > A reference to this command The name of the data field into which the value will be placed. NOTE: Quotation marks should surround the field name parameter as the tilde character ( ~ ), the delimiter for parameters, is used as part of the name of certain standard fields. For example: CALLEDIDNUM - Set the DNIS number if the call direction is Inbound. Otherwise, it sets the outside number of the call. CALLERIDNUM - Set the outside number of the call. CALLERID - Set the outside name of the call. EXT - Add an extension to the call. ACCOUNT - Add an account code to the call. ACDGRP - Add an ACD group ID to the call. If a different ACD Groups is added previously to the call, then the previous ACD Group will be cleared from the call. ACDGRPN - Add/Update the ACD Group name of an ACD Group ID in the call. ACDAGT - Add an ACD agent ID to the call. If a different agent added previously to the call, then the previous agent will be cleared from the call. ACDATN - Add/Update the ACD agent name of an ACD Agent ID in the call. NOTE: See Extra-Call Info Fields for supported fields. OAISYS API Overview and Developer s Guide 25

27 < Value > The text data to place into the field. NOTE: Quotation marks should surround the value parameter as the tilde character ( ~ ), the delimiter for parameters, can be included in the value text. For example, 12~A266. <User> <Pass> [Optional] [Optional] RESPONSE SYNTAX: RC~ATTACH_INFO~<Req_ID>~<Success/Fail>~<Reason>~crLf RESPONSE FIELDS: <Rec_ID> <Success/Fail> <Reason> The reference ID sent with the command An S for success or F for failure. If S the field may be omitted. If F the <Reason> field will be populated If a failure occurred, this will include a text description of the failure reason OAISYS API Overview and Developer s Guide 26

28 Request Call Info This command is sent to request a field of information about the call. COMMAND SYNTAX: C~REQ_INFO~<Req_ID>~<Stn_extension>~<CTI_CID>~<CTI_CNX>~<TrunkID>~<Ag entid>~< FieldName >~<User>~<Pass>~crLf COMMAND (SEE STANDARD REAL-TIME ABOVE FOR THOSE NOT LISTED HERE): <Req_ID> < FieldName > A reference to this command The name of the data field into which the value will be placed. NOTE: Quotation marks should surround the field name parameter as the tilde character ( ~ ), the delimiter for parameters, is used as part of the name of certain standard fields. For example: ~CHdbGUID - is the field that holds the globally unique ID for the recording in progress. This can be used to execute additional commands in real-time as well as to retrieve the recording in a historical command. CALLEDIDNUM - Get the last DNIS number of the call. CALLERIDNUM - Get the last outside number of the call. CALLERID - Get the last outside name of the call. EXT - Get the last extension of the call. ACCOUNT - Get the last account code. ACDGRP - Get the last ACD Group ID. ACDGRPN - Get the name of the last ACD Group. ACDAGT - Get the last ACD Agent ID. ACDATN - Get the name of the last ACD Agent ID. NOTE: See Extra-Call Info Fields for supported fields. ~PLAY_URL - Get the playback URL e.g. Guid>&.AutoPlay=1 <User> [Optional] OAISYS API Overview and Developer s Guide 27

29 <Pass> [Optional] RESPONSE SYNTAX: RC~REQ_INFO~<Req_ID>~<Success/Fail>~<Field Name/Reason>~<FieldValue>~crLf RESPONSE FIELDS: <Rec_ID> <Success/Fail> <Field Value/Reason> The reference ID sent with the command An S for success or F for failure. If S the <FieldValue/Reason> field will be populated. If F the <Reason> field will be populated In the case of a success, this field will contain the value of the requested field for the matched call. If a failure occurred, this will include a text description of the failure reason. NOTE: In the case of success, the value will be contained in quotation marks as the value may include a tilde ( ~ ) character, which is the response delimiter. Set Call Info This command is sent to request information to be set to a call. COMMAND SYNTAX: C~SET_INFO~<Req_ID>~<Stn_extension>~<CTI_CID>~<CTI_CNX>~<TrunkID>~<Age ntid>~< FieldName >~< Value >~<User>~<Pass>~crLf COMMAND (SEE STANDARD REAL-TIME ABOVE FOR THOSE NOT LISTED HERE): <Req_ID> A reference to this command OAISYS API Overview and Developer s Guide 28

30 < FieldName > The name of the data field into which the value will be placed. NOTE: Quotation marks should surround the field name parameter as the tilde character ( ~ ), the delimiter for parameters, is used as part of the name of certain standard fields. For example: CALLEDIDNUM - Set the DNIS number if the call direction is Inbound. Otherwise, it sets the outside number of the call. CALLERIDNUM - Set the outside number of the call. CALLERID - Set the outside name of the call. EXT - Add an extension to the call. If a different extension added previously to the call, then the previous extension will be cleared from the call. For two or more extensions the extensions have to be comma separated. ACCOUNT - Add an account code to the call. ACDGRP - Add an ACD group ID to the call. If a different ACD Groups is added previously to the call, then the previous ACD Group will be cleared from the call. ACDGRPN - Add/Update the ACD Group name of an ACD Group ID in the call. ACDAGT - Add an ACD agent ID to the call. If a different agent added previously to the call, then the previous agent will be cleared from the call. For two or more ACD agent IDs the ACD agent IDs have to be comma separated. ACDATN - Add/Update the ACD agent name of an ACD Agent ID in the call. NOTE: See Extra-Call Info Fields for supported fields. < Value > The text data to place into the field. NOTE: Quotation marks should surround the value parameter as the tilde character ( ~ ), the delimiter for parameters, can be included in the value text. For example, 12~A266. <User> <Pass> [Optional] [Optional] OAISYS API Overview and Developer s Guide 29

31 RESPONSE SYNTAX: RC~SET_INFO~<Req_ID>~<Success/Fail>~<Reason>~crLf RESPONSE FIELDS: <Rec_ID> <Success/Fail> <Reason> The reference ID sent with the command An S for success or F for failure. If S the <Reason> field may be omitted. If F the <Reason> field will be populated If a failure occurred, this will include a text description of the failure reason Get Call Info This command is sent to get a field of information about the call. COMMAND SYNTAX: C~GET_INFO~<Req_ID>~<Stn_extension>~<CTI_CID>~<CTI_CNX>~<TrunkID>~<Age ntid>~< FieldName >~<User>~<Pass>~crLf COMMAND (SEE STANDARD REAL-TIME ABOVE FOR THOSE NOT LISTED HERE): <Req_ID> A reference to this command OAISYS API Overview and Developer s Guide 30

32 < FieldName > The name of the data field into which the value will be placed. NOTE: Quotation marks should surround the field name parameter as the tilde character ( ~ ), the delimiter for parameters, is used as part of the name of certain standard fields. For example: ~CHdbGUID - is the field that holds the globally unique ID for the recording in progress. This can be used to execute additional commands in real-time as well as to retrieve the recording in a historical command. CALLEDIDNUM - Get the last DNIS number of the call. CALLERIDNUM - Get the last outside number of the call. CALLERID - Get the last outside name of the call. EXT - Get all the extensions (comma separated list) of the call. ACCOUNT - Get the last account code. ACDGRP - Get the last ACD Group ID. ACDGRPN - Get the name of the last ACD Group. ACDAGT - Get all the ACD Agent IDs (comma separated list). ACDATN - Get the name of the last ACD Agent ID. NOTE: See Extra-Call Info Fields for supported fields. ~PLAY_URL - Get the playback URL e.g. Guid>&.AutoPlay=1 <User> <Pass> [Optional] [Optional] RESPONSE SYNTAX: RC~GET_INFO~<Req_ID>~<Success/Fail>~<Field Value/Reason>~crLf RESPONSE FIELDS: <Rec_ID> <Success/Fail> The reference ID sent with the command An S for success or F for failure. If F the <Reason> field will be populated OAISYS API Overview and Developer s Guide 31

33 <Field Value/Reason> In the case of a success, this field will contain the value of the requested field for the matched call. If a failure occurred, this will include a text description of the failure reason. NOTE: In the case of success, the value will be contained in quotation marks as the value may include a tilde ( ~ ) character, which is the response delimiter. Start Recording This command is sent to request recording to be started on a call. COMMAND SYNTAX: C~RECDSTART~<Req_ID>~<Stn_extension>~<CTI_CID>~<CTI_CNX>~ <TrunkID>~<AgentID>~<Requesting_Ext>~<User>~<Pass>~crLf COMMAND (SEE STANDARD REAL-TIME ABOVE FOR THOSE NOT LISTED HERE): <Req_ID> <Requesting_Ext> <User> <Pass> A reference to this command Identifies the OAISYS user account to determine what permissions are enabled. If no extension ID is provided then the user account associated with the <User> parameter will be used. If both are empty then the extension ID associated with the call will be used. The username of a valid OAISYS user account. If provided and <Requesting_Ext> is empty then this user s permissions will be assumed when attempting to execute this command. The password associated with the <User> account in the OAISYS database. RESPONSE SYNTAX: RC~RECDSTART~<Req_ID>~<Success/Fail>~<Reason>~crLf RESPONSE FIELDS: <Rec_ID> The reference ID sent with the command OAISYS API Overview and Developer s Guide 32

34 <Success/Fail> <Reason> An S for success or F for failure. If S the <Reason> field may be omitted. If F the <Reason> field will be populated If a failure occurred, this will include a text description of the failure reason. Stop Recording This command is sent to request recording be stopped on a call. COMMAND SYNTAX: C~RECDSTOP~<Req_ID>~<Stn_extension>~<CTI_CID>~<CTI_CNX>~<TrunkID>~<Ag entid>~<requesting_ext>~<user>~<pass>~crlf COMMAND (SEE STANDARD REAL-TIME ABOVE FOR THOSE NOT LISTED HERE): <Req_ID> <Requesting_Ext> <User> <Pass> A reference to this command Identifies the OAISYS user account to determine what permissions are enabled. If no extension ID is provided then the user account associated with the <User> parameter will be used. If both are empty then the extension ID associated with the call will be used. The username of a valid OAISYS user account. If provided and <Requesting_Ext> is empty then this user s permissions will be assumed when attempting to execute this command. The password associated with the <User> account in the OAISYS database. RESPONSE SYNTAX: RC~RECDSTOP~<Req_ID>~<Success/Fail>~<Reason>~crLf RESPONSE FIELDS: <Rec_ID> <Success/Fail> The reference ID sent with the command An S for success or F for failure. If F the <Reason> field will be populated OAISYS API Overview and Developer s Guide 33

35 <Reason> If a failure occurred, this will include a text description of the failure reason. Request Recording Bookmark This command is sent to add a bookmark to a recording of a call. COMMAND SYNTAX: C~RECDBKMRK~<Req_ID>~<Stn_extension>~<CTI_CID>~<CTI_CNX>~ <TrunkID>~<AgentID>~<Requesting_Ext>~<User>~<Pass>~ < Bookmark_Text >~crlf COMMAND (SEE STANDARD REAL-TIME ABOVE FOR THOSE NOT LISTED HERE): <Req_ID> <Requesting_Ext> <User> <Pass> < Bookmark_Text > A reference to this command Identifies the OAISYS user account to determine what permissions are enabled. If no extension ID is provided then the user account associated with the <User> parameter will be used. If both are empty then the extension ID associated with the call will be used. The username of a valid OAISYS user account. If provided and <Requesting_Ext> is empty then this user s permissions will be assumed when attempting to execute this command. The password associated with the <User> account in the OAISYS database. The text to be inserted as a bookmark. NOTE: This text should be surrounded by quotation marks as it could include a tilde ( ~ ) character, which is the parameter delimiter. RESPONSE SYNTAX: RC~RECDBKMRK~<Req_ID>~<Success/Fail>~<Reason>~crLf RESPONSE FIELDS: <Rec_ID> The reference ID sent with the command OAISYS API Overview and Developer s Guide 34

36 <Success/Fail> <Reason> An S for success or F for failure. If S the <Reason> field may be omitted. If F the <Reason> field will be populated If a failure occurred, this will include a text description of the failure reason. Request Copy of Recording This command is sent to request a copy of a recording of a call to be ed. NOTE: On some recording systems it may not be allowed to send an actual copy of a recording, in which case it may instead a message that includes a URL link back to the recording. COMMAND SYNTAX: C~RECDECOPY~<Req_ID>~<Stn_extension>~<CTI_CID>~<CTI_CNX>~ <TrunkID>~<AgentID>~<Requesting_Ext>~<User>~<Pass>~ < _Address >~< Subject >~crlf COMMAND (SEE STANDARD REAL-TIME ABOVE FOR THOSE NOT LISTED HERE): <Req_ID> <Requesting_Ext> <User> <Pass> < _Address > A reference to this command Identifies the OAISYS user account to determine what permissions are enabled. If no extension ID is provided then the user account associated with the <User> parameter will be used. If both are empty then the extension ID associated with the call will be used. The username of a valid OAISYS user account. If provided and <Requesting_Ext> is empty then this user s permissions will be assumed when attempting to execute this command. The password associated with the <User> account in the OAISYS database. The address to receive the . NOTE: This text should be surrounded by quotation marks as it could include a tilde ( ~ ) character, which is the parameter delimiter. OAISYS API Overview and Developer s Guide 35

37 < Subject > The text to be used in the subject line of the message. NOTE: This text should be surrounded by quotation marks as it could include a tilde ( ~ ) character, which is the parameter delimiter. RESPONSE SYNTAX: RC~RECDECOPY~<Req_ID>~<Success/Fail>~<Reason>~crLf RESPONSE FIELDS: <Rec_ID> <Success/Fail> <Reason> The reference ID sent with the command An S for success or F for failure. If F the <Reason> field will be populated If a failure occurred, this will include a text description of the failure reason. Enable digit capture This command is sent to start capturing digits for the call. COMMAND SYNTAX: C~ENABLE_DIGITCAPTURE~<Req_ID>~<Stn_extension>~<CTI_CID>~<CTI_CNX>~ <TrunkID>~<AgentID>~<Requesting_Ext>~<User>~<Pass> crlf COMMAND (SEE STANDARD REAL-TIME ABOVE FOR THOSE NOT LISTED HERE): <Req_ID> <Requesting_Ext> A reference to this command Identifies the OAISYS user account to determine what permissions are enabled. If no extension ID is provided then the user account associated with the <User> parameter will be used. If both are empty then the extension ID associated with the call will be used. OAISYS API Overview and Developer s Guide 36

38 <User> <Pass> The username of a valid OAISYS user account. If provided and <Requesting_Ext> is empty then this user s permissions will be assumed when attempting to execute this command. The password associated with the <User> account in the OAISYS database. RESPONSE SYNTAX: RC~ ENABLE_DIGITCAPTURE~<Req_ID>~<Success/Fail>~<Reason>~crLf RESPONSE FIELDS: <Rec_ID> <Success/Fail> <Reason> The reference ID sent with the command An S for success or F for failure. If F the <Reason> field will be populated If a failure occurred, this will include a text description of the failure reason. Disable digit capture This command is sent to stop capturing digits for the call. COMMAND SYNTAX: C~DISABLE_DIGITCAPTURE~<Req_ID>~<Stn_extension>~<CTI_CID>~<CTI_CNX>~ <TrunkID>~<AgentID>~<Requesting_Ext>~<User>~<Pass> crlf COMMAND (SEE STANDARD REAL-TIME ABOVE FOR THOSE NOT LISTED HERE): <Req_ID> <Requesting_Ext> A reference to this command Identifies the OAISYS user account to determine what permissions are enabled. If no extension ID is provided then the user account associated with the <User> parameter will be used. If both are empty then the extension ID associated with the call will be used. OAISYS API Overview and Developer s Guide 37

39 <User> <Pass> The username of a valid OAISYS user account. If provided and <Requesting_Ext> is empty then this user s permissions will be assumed when attempting to execute this command. The password associated with the <User> account in the OAISYS database. RESPONSE SYNTAX: RC~ DISABLE_DIGITCAPTURE~<Req_ID>~<Success/Fail>~<Reason>~crLf RESPONSE FIELDS: <Rec_ID> <Success/Fail> <Reason> The reference ID sent with the command An S for success or F for failure. If F the <Reason> field will be populated If a failure occurred, this will include a text description of the failure reason. OAISYS API Overview and Developer s Guide 38

40 OLDER DIALER LEGACY SUPPORT These commands are already in use in a number of existing installations, so we will continue to support them As Is. Start Recording This command is sent by applications when a call is starting. COMMAND SYNTAX: D~DLC~<extension>~<trunkID>~<agentID>~<campaignID>~<direction>~ <callerid>~<dnis>~<customerdefined1>~<customerdefined2>~ <customerdefined3>~<customerdefined4>~crlf COMMAND (SEE STANDARD REAL-TIME ABOVE FOR THOSE NOT LISTED HERE): <extension> <trunkid> <agentid> <campaignid> <direction> <callerid> <dnis> <customerdefined1> <customerdefined2> The PBX extension ID on the call. The trunk identifier in the OAISYS database for the call. The agent ID for the call. Can be blank. The campaign ID for the call. Can be blank. Use I for inbound and use O for outbound. The telephone number of the external party. Should be numeric only without formatting (e.g ). The dialed number identification service (DNIS) or direct inward dial (DID) identifier for an inbound call, if available. Can be blank. Up to four user-defined fields are available to attach extra information to the recording. If non-blank they should be made up of a name/value pair separated by = ( name1=value1 ) and when present it will be added to extra info for the call (e.g. CUSTOMER_ID=54782 ). Up to four user-defined fields are available to attach extra information to the recording. If non-blank they should be made up of a name/value pair separated by = ( name1=value1 ) and when present it will be added to extra info for the call (e.g. CUSTOMER_ID=54782 ). OAISYS API Overview and Developer s Guide 39

41 <customerdefined3> <customerdefined4> Up to four user-defined fields are available to attach extra information to the recording. If non-blank they should be made up of a name/value pair separated by = ( name1=value1 ) and when present it will be added to extra info for the call (e.g. CUSTOMER_ID=54782 ). Up to four user-defined fields are available to attach extra information to the recording. If non-blank they should be made up of a name/value pair separated by = ( name1=value1 ) and when present it will be added to extra info for the call (e.g. CUSTOMER_ID=54782 ). Stop Recording This command is sent by applications when a call is ending. It can include duplicate or new information about the call. COMMAND SYNTAX: D~IDL~<extension>~<trunkID>~<agentID>~<campaignID>~<direction>~ <callerid>~<dnis>~<customerdefined1>~<customerdefined2>~ <customerdefined3>~<customerdefined4>~crlf COMMAND (SEE STANDARD REAL-TIME ABOVE FOR THOSE NOT LISTED HERE): <extension> <trunkid> <agentid> <campaignid> <direction> <callerid> <dnis> The PBX extension ID on the call. The trunk identifier in the OAISYS database for the call. The agent ID for the call. Can be blank. The campaign ID for the call. Can be blank. Use I for inbound and use O for outbound. The telephone number of the external party. Should be numeric only without formatting (e.g ). The dialed number identification service (DNIS) or direct inward dial (DID) identifier for an inbound call, if available. Can be blank. OAISYS API Overview and Developer s Guide 40

42 <customerdefined1> <customerdefined2> <customerdefined3> <customerdefined4> Up to four user-defined fields are available to attach extra information to the recording. If non-blank they should be made up of a name/value pair separated by = ( name1=value1 ) and when present it will be added to extra info for the call (e.g. CUSTOMER_ID=54782 ). Up to four user-defined fields are available to attach extra information to the recording. If non-blank they should be made up of a name/value pair separated by = ( name1=value1 ) and when present it will be added to extra info for the call (e.g. CUSTOMER_ID=54782 ). Up to four user-defined fields are available to attach extra information to the recording. If non-blank they should be made up of a name/value pair separated by = ( name1=value1 ) and when present it will be added to extra info for the call (e.g. CUSTOMER_ID=54782 ). Up to four user-defined fields are available to attach extra information to the recording. If non-blank they should be made up of a name/value pair separated by = ( name1=value1 ) and when present it will be added to extra info for the call (e.g. CUSTOMER_ID=54782 ). OAISYS API Overview and Developer s Guide 41

43 SEARCH AND UPDATE COMMANDS The following commands should be used after the call has completed. ASCII Stream API (Historical) Commands Find a Call This command is sent to see if a call exists that matches the parameters provided. This command will only search through recordings of completed calls. COMMAND SYNTAX: C~LOOKUP_CALL~<Req_ID>~<StartDate>~<StartTime>~<TrunkID>~ <Call_Duration>~<Call_Direction>~<Called_Phone_Num>~ <Calling_Phone_Num>~crLf COMMAND : <Req_ID> <StartDate> <StartTime> <TrunkID> <Call_Duration> <Call_Direction> <Called_Phone_Num> <Calling_Phone_Num> A reference to this command The date on which the call being sought began. This parameter uses the format MM/DD/YYYY. The time at which the call being sought began. This parameter uses the format HH:MM:SS and will work using either 24-hour time values (e.g. 14:20:55 ) or AM/PM designation (e.g. 2:20:55pm ). The trunk identifier as programmed in the OAISYS VAT port settings. The entire duration of the call in seconds. This value is with respect to the trunk. Valid values include I for incoming, O for outgoing or for unknown. The dialed number on outgoing calls or the DNIS/DID value for inbound calls. DNIS (dialed number identification service) is typically a four or five digit identifier and not the actual number dialed. DID (direct inward dial) is typically the tendigit number dialed. The number of the outside party. OAISYS API Overview and Developer s Guide 42

44 RESPONSE SYNTAX: RC~LOOKUP_CALL~<Req_ID>~<Success/Fail>~<Unique_GUID>~<Reason>~ crlf RESPONSE FIELDS: <Rec_ID> <Success/Fail> <Reason> <Unique_GUID> The reference ID sent with the command An S for success or F for failure. If S the <Reason> field may be omitted. If F the <Reason> field will be populated If a failure occurred, this will include a text description of the failure reason. If a success occurred, this will represent the globally unique ID of the recording in the OAISYS database. Update a Call This command can be used to modify information on or add information to a call and also trigger whether a call recording should be kept. This command requires a Unique_GUID to identify the target call this Unique_GUID can be discovered using the C~LOOKUP_CALL command. This command only affects recordings of completed calls. COMMAND SYNTAX: C~UPDATE_CALL~<Req_ID>~<Unique_GUID>~< FieldName >~< Value >~ <KeepRecording>~<Requesting_Ext>~<User>~<Pass>~crLf COMMAND : <Req_ID> <Unique_GUID> A reference to this command The globally unique ID assigned to the target recording by the OAISYS software. OAISYS API Overview and Developer s Guide 43

45 < FieldName > The name of the field to modify or add. NOTE: The text in this parameter should be surrounded by quotation marks as the tilde ( ~ ) character, which is the parameter delimiter, is valid. NOTE: See Extra-Call Info Fields for supported fields. < Value > The text value of the field to be modified or added. NOTE: The text in this parameter should be surrounded by quotation marks as the tilde ( ~ ) character, which is the parameter delimiter, is valid. NOTE: If the field name is EXTS, multiple extensions can be added by using the format Ext1;Ext2;Ext3 within the value parameter. Any extensions added will be associated with the entire call, which means user accounts with permission to call segments including an added extension will have access permission to the entire recording. <KeepRecording> <Requesting_Ext> <User> <Pass> Used to engage or override the recording rules in the OAISYS server. Send Y to start recording, N to stop recording or T to use the recording triggers programmed in the OAISYS server. Used to determine the OAISYS users account whose permissions to assume if attempting to override the OAISYS server s recording rules in the <KeepRecording> parameter. If no extension ID is provided then the <User> field is used instead. The username of a valid OAISYS user account. If provided and <Requesting_Ext> is empty then this users permissions will be assumed when attempting to execute this command. The password associated with the <User> account in the OAISYS database. RESPONSE SYNTAX: RC~UPDATE_CALL~<Req_ID>~<Success/Fail>~<Reason>~crLf OAISYS API Overview and Developer s Guide 44

46 RESPONSE FIELDS: <Rec_ID> <Success/Fail> <Reason> The reference ID sent with the command An S for success or F for failure. If S the <Reason> field may be omitted. If F the <Reason> field will be populated If a failure occurred, this will include a text description of the failure reason. Find and Update a Call This command is sent to see if a call exists that matches the provided parameters. If a match is made then submitted data will be modified or added to the record and optionally used to decide whether to retain the recording or not. COMMAND SYNTAX: C~LOOKUP_UPDATE_CALL~<Req_ID>~<StartDate>~<StartTime>~<TrunkID>~ <Call_Duration>~<Call_Direction>~<Called_Phone_Num>~ <Calling_Phone_Num>~<KeepRecording>~<Requesting_Ext>~<User>~ <Pass>~<KeyN>=<ValueN>[[tab]<KeyN>=<ValueN>]~crLf COMMAND : <Req_ID> <StartDate> <StartTime> <TrunkID> <Call_Duration> <Call_Direction> A reference to this command The date on which the call being sought began. This parameter uses the format MM/DD/YYYY. The time at which the call being sought began. This parameter uses the format HH:MM:SS and will work using either 24-hour time values (e.g. 14:20:55 ) or AM/PM designation (e.g. 2:20:55pm ). The trunk identifier as programmed in the OAISYS VAT port settings. The entire duration of the call in seconds. This value is with respect to the trunk. Valid values include I for incoming, O for outgoing or for unknown. OAISYS API Overview and Developer s Guide 45

47 <Called_Phone_Num> <Calling_Phone_Num> <KeepRecording> <Requesting_Ext> <User> <Pass> <KeyN>=<ValueN>[tab] The dialed number on outgoing calls or the DNIS/DID value for inbound calls. DNIS (dialed number identification service) is typically a four or five digit identifier and not the actual number dialed. DID (direct inward dial) is typically the ten-digit number dialed. The number of the outside party. Used to engage or override the recording rules in the OAISYS server. Send Y to start recording, N to stop recording or T to use the recording triggers programmed in the OAISYS server. Identifies the OAISYS user account to determine if permissions are enabled to override the OAISYS server s recording rules in the <KeepRecording> parameter. If no extension ID is provided then the <User> field is used instead. The username of a valid OAISYS user account. If provided and <Requesting_Ext> is empty then this user s permissions will be assumed when attempting to execute this command. The password associated with the <User> account in the OAISYS database. A key/value pair representing the data field to be updated or added and the new value. Standard fields that can be updated include EXTS, AccountCodes and AgentIDs. In each case multiple values can be assigned via one key by using the format KeyN=Value1;Value2; ;ValueN. AccountCodes and AgentIDs both allow for the assignment of an offset position relative to the start of the recording. This is performed using the format KeyN=Value1,POS1; ;ValueN,POSN where POSx is a number representing the number of seconds after the recording began to associate the value. Use a tab character (ASCII code 9) to separate two or more key/value pairs in a single command. RESPONSE SYNTAX: RC~LOOKUP_UPDATE_CALL~<Req_ID>~<Success/Fail>~<Unique_GUID>~ <Reason>~crLf OAISYS API Overview and Developer s Guide 46

48 RESPONSE FIELDS: <Rec_ID> <Success/Fail> <Reason> <Unique_GUID> The reference ID sent with the command An S for success or F for failure. If F the <Reason> field will be populated If a failure occurred, this will include a text description of the failure reason. If a success occurred, this will represent the globally unique ID of the recording in the OAISYS database. OAISYS API Overview and Developer s Guide 47

49 PLAYBACK API The playback API is used to play back a recorded call from an application. This API is for use with historical calls, it is URL based and virtually any application that can open a URL can utilize this API. The playback API is used to search for recordings and load the list of matches into the OAISYS Management Studio. Common Uses: Search for recordings based on an outside party number match from a CRM application Provide links to playback recordings within a contact management application URL STRUCTURE This section assumes that the reader is familiar with URLs. The basic form of the playback URL is as follows: By default, the OAISYS application is installed as a web application under the root directory of the default website of the Tracer machine. Therefore, for an internal client, the URL looks like: For an external client, this URL most likely will change. Specifically, <hostname> will likely change from Tracer to some dotted-ip address or perhaps to some other defined name. Example: or n The form of <hostname> entirely depends on what the customer has defined at their firewall. Ultimately, requests at the firewall get forwarded to the internal Tracer machine. OAISYS API Overview and Developer s Guide 48

50 COMMANDS This section assumes that the reader is familiar with http query strings. For a definition of http, go to: For specifics on http query strings, go to: Every defined query-string key will have an example of what the key name/value pair looks like. These examples are shown in clear text. When included in a URL, however, the key value may not be able to be transmitted over http in clear text some of the characters may require escape sequences for transmission to succeed. For specifics on escape sequences, go to: Every query key that the playback API accepts begins with a period (. ) followed by the key name. The BNF for the playback API query string is as follows: <Query String> ::=. <KeyName> = <Value>{ &. <KeyName> = <Value>} The command to be invoked is determined by the query parameters included with the URL to the API. If a unique search parameter is included, it takes precedence and the unique search command will be honored and all other search parameters will be ignored. Playback control is available across both the Unique Search and Filter commands. For ease of navigation Playback control parameters are defined in their own section. Unique Search This command forces a search for a single, unique call record. Upon finding the first query parameter of the Unique Search function all other search and filter parameters will be ignored. The playback API will give precedence to the 1 st Unique Search parameter it identifies. Playback control parameters will be honored. OAISYS API Overview and Developer s Guide 49

51 .Pathname.RowGUID The full path name (physical or virtual if the path is shared) and file name of a given recording file. Example:.Pathname=//Tracer/Recordings/01/00/10CX70.wav The globally unique identifier assigned to a recording file by the OAISYS system Example:.RowGuid= BE04B5F9-AEC EFDD2EDA43D Filter This command takes one or more filter criteria and loads the set of matching recordings to which the user account has access in the OAISYS Management Studio. As stated earlier, any parameter for the Unique Search function will take precedence and cause the Filter command and its parameters to be ignored. Playback control parameters will be honored..extension.account.outsidename.outsidenumber.dnis_did.calldirection A PBX telephone extension. Example:.Extension=1000 An account code value entered through a PBX during a live conversation Example:.Account=1234 The text-based outside name captured by OAISYS during a live conversation Example:.OutsideName=John Doe The numeric outside number captured by OAISYS during a live conversation Example:.OutsideNumber= The numeric dialed number identification service (DNIS) or direct inward dial (DID) ID captured on inbound calls by OAISYS during a live conversation Example:.DNIS_DID=9040 An indication of the direction of the telephone call that was recorded. Valid criteria include In, Out and IC where IC is an internal call (e.g. ext calls ext. 1500). Example:.CallDirection=In OAISYS API Overview and Developer s Guide 50

52 .ExtraCallInfo User-defined information that is attached in key/value pairs. This is useful to add business process data such as OrderNumber = Searches are formatted as <key>=<value> combinations. Multiple key/value pairs can be included in one search using <tab> to separate each pair. Example:.ExtraCallInfo=ACDGRP=2000<tab>ACDAGT=200 Playback Control The playback control command is honored in combination with either a Unique Search or Filter command. At present, the only playback control parameter is to automate playback of the first (or only) record returned in the OAISYS Management Studio upon a successful Unique Search or Filter command..autoplay A value of 1 enables automatic playback so that the first or only record returned from a successful Unique Search or Filter command will automatically start playing in the OAISYS Management Studio. Example:.AutoPlay=1 OAISYS API Overview and Developer s Guide 51

53 DESKTOP CLIENT API 2 ***Available in Tracer 7.2+ Desktop Client API 2 (DtApi2) is a TCP/IP based communications protocol whereby a third-party application may interface with Desktop Client in a number of ways, including: Start and stop recording Enable and disable digit capture Retrieve and assign values to call-data fields Retrieve and assign values to Extra-Call Info Fields Attach bookmarks DtApi2 libraries are based on.net Framework 3.5 and it is intended to replace the original desktop client API, as it overcomes several limitations in that API as follows: DtApi2 is designed for backwards compatibility Extra-Call Info Fields names are now consistent between events and methods Call-data fields are supported Login is now required before engaging with desktop client, providing added security to the customer Status indicators are now strongly typed, well defined, and immutable Monitors allow the application to enable and disable events Errors are now reported back to the third-party application Resynch events occur when the third-party application turns on a monitor Desktop client is never blocked by an event as it is issued asynchronously There are no longer events or other members exposed that are intended for internal use only Code-side events are now registered through the standard means for the given platform Redundant methods have been removed OAISYS API Overview and Developer s Guide 52

54 BACKWARDS COMPATIBILITY OAISYS reserves the right to extend DtApi2 in future releases by doing any or all of the following: Adding new modules or communication protocols Adding new methods, objects, or functionality to an existing module Adding new parameters onto the end of an existing method or function o Such new parameters will support a default value so as to remain backwards compatible to older software Adding new fields to an existing object Altering the behavior of existing modules, methods, and functions to resolve bugs or to adjust in accordance with limitations or changes in newer releases of Tracer Removing or disabling a module, method, or function after a reasonable period of time where we have properly advertised that the method or function will be deprecated in a future release THE THIRD-PARTY APPLICATION While DtApi2 is TCP/IP based, desktop client currently listens only on localhost, so the intent is for the third-party application to be running on the same machine as desktop client. Currently, the lower-level binary stream at the TCP/IP level is not documented and is not intended to be implemented directly by the third-party application. Rather, the intent is for the third-party application to host a library that is supplied by OAISYS, and that abstracts away all of the details of the TCP/IP based communication, including the acquisition of the TCP/IP port. See the Libraries section for more details. OAISYS API Overview and Developer s Guide 53

55 LIBRARIES OAISYS currently provides two sets of libraries for third-party developers for two popular platforms:.net 3.5 COM. The setup file whereby the third-party developer may install the libraries can be located here: ftp://ftp.oaisys.com/pub/downloads/desktopclientapi2/. For each platform, the principal binary file is called OAISYS.Integration.DesktopClient2.dll.NET To use this library, the third-party application must reference the following.net assemblies: OAISYS.Integration.dll. o This assembly is not intended to be used directly by the third-party application OAISYS.Integration.DesktopClient2.dll. o This is the assembly intended for the third-party application All communication with Desktop Client occurs through a single instance of the following class: OAISYS.Integration.DesktopClient2.DesktopClient. This section documents the members of that class, in C# syntax. Note that custom types (enumerations, classes, etc.) referenced in the members are documented in the Objects section. CONSTRUCTORS Default Constructor The default constructor allows the third-party application to create the objects easily, but provides for no customization. OAISYS API Overview and Developer s Guide 54

56 SIGNATURE DesktopClient() RETURN VALUE A new DesktopClient instance. Constructor with log customization This constructor allows the third-party application to direct the library to automatically log all communication between desktop client and the application to an ILog object supplied by the third-party application. SIGNATURE DesktopClient(ILog log, string lineprefix) ILog log string lineprefix A logging object defined by the third-party application. See ILog for more details. Specifies what prefix, if any, should be prepended to each line written to the log. RETURN VALUE A new DesktopClient instance. GENERAL EVENTS Up() This event occurs when a connection has been established with Desktop Client, compatibility has been verified, and Desktop Client is ready to receive requests. OAISYS API Overview and Developer s Guide 55

57 EVENT SIGNATURE event VoidHandler Up; DELEGATE SIGNAURE delegate void VoidHandler(); Down() This event occurs when the connection to Desktop Client has been lost. EVENT SIGNATURE event VoidHandler Down; DELEGATE SIGNAURE delegate void VoidHandler(); CallStatusChange() This event occurs when a call s state has changed relative to the agent. EVENT SIGNATURE event CallStatusChangeHandler CallStatusChange; DELEGATE SIGNATURE delegate void CallStatusChangeHandler(string callid, CallStatusEnum callstatus); string callid CallStatusEnum callstatus Identifies the call Indicates the call status. See CallStatusEnum for more details. OAISYS API Overview and Developer s Guide 56

58 CallDataFieldChange() This event occurs when a call-data field s value has changed. SIGNATURE event CallDataFieldChangeHandler CallDataFieldChange; DELEGATE SIGNATURE delegate void CallDataFieldChangeHandler(string callid, string name, object value); string callid string name object value Identifies the call. The name of the call-data field. See the section entitled Call-Data Fields for more details. The value of the call-data field. Note that the value is presented in the native type of the call-data field. See the section entitled Call- Data Fields for more details. RecordStatusChange() This event occurs when a call s record status has changed. SIGNATURE event RecordStatusChangeHandler RecordStatusChange; DELEGATE SIGNATURE delegate void RecordStatusChangeHandler(string callid, bool recording); string callid bool recording Identifies the call. True if the call is recording; false otherwise. OAISYS API Overview and Developer s Guide 57

59 ClientStatusChange() This event occurs when the desktop client s overall status has changed. SIGNATURE event ClientStatusChangeHandler ClientStatusChange; DELEGATE SIGNATURE delegate void ClientStatusChangeHandler(ClientStatusEnum status); ClientStatusEnum status Indicates the client s overall status. See ClientStatusEnum for more details. ExtraCallInfoChange() This event occurs when the Extra-Call Info Fields for a particular call has changed. SIGNATURE event ExtraCallInfoChangeHandler ExtraCallInfoChange; DELEGATE SIGNATURE delegate void ExtraCallInfoChangeHandler(string callid, string name, string value); string callid string name string value Identifies the call. The name of the extra-call info field. See the section entitled Extra-Call Info Fields for more details. The value of the extra-call info field. See the section entitled Extra-Call Info Fields for more details. OAISYS API Overview and Developer s Guide 58

60 PROPERTIES IsUp The third-party app can call this property to determine if desktop client is ready to receive requests or not. This property reflects the same meaning as the Up/Down events. SIGNATURE bool IsUp { get; } RETURN VALUE bool True if desktop client is ready to receive requests. False otherwise. GENERAL METHODS StartConnect() The third-party app calls this method to asynchronously connect to desktop client. The Up event will occur when the connection has been established, and when desktop client is ready to receive requests. This method also enables the behavior where the library will automatically and periodically retry the connection to Desktop Client periodically once that connection has been lost. This retry behavior remains in force until Disconnect() is called. SIGNATURE void StartConnect(); RETURN VALUE void OAISYS API Overview and Developer s Guide 59

61 Disconnect() The third-party app calls this method to disconnect from desktop client. SIGNATURE void Disconnect(); RETURN VALUE void Dispose() The third-party app calls this method to dispose of the object, which will also inherently close the connection. This method is inherited from IDisposable. SIGNATURE void Dispose(); RETURN VALUE void REQUEST METHODS AND RESPONSE EVENTS A request method is a special class of method which, when invoked, sends a request to the desktop client, which in turn sends a response to the request. For each request, the library supports two methods: one for issuing the request synchronously and returning the response to the caller one for issuing the request asynchronously, where the result is presented in a subsequent event that contains the response In this section, we group the request methods and response events by request type. OAISYS API Overview and Developer s Guide 60

62 AddBookmarkToActiveCall The third-party app calls this method to attach a bookmark or annotation to the currently active call. SYNCHRONOUS METHOD SIGNATURE void AddBookMarkToActiveCall (string subject, string text); ASYNCHRONOUS METHOD SIGNATURE uint AddBookMarkToActiveCallAsynch (string subject, string text); string subject string text The subject of the bookmark/annotation. The text of the bookmark/annotation. SYNCHRONOUS RETURN VALUE void ASYNCHRONOUS RETURN VALUE uint The invoke ID of the request. Cache it and compare it to the invoke ID contained in the response event to synch up request with response. EXCEPTIONS FOR THE SYNCHRONOUS METHOD An exception will occur if the request fails for any reason. EXCEPTIONS FOR THE ASYNCHRONOUS METHOD An exception will occur only if a failure of some kind occurs; for example something is wrong with the socket connection. OAISYS API Overview and Developer s Guide 61

63 RESPONSE EVENT SIGNATURE event AddBookMarkToActiveCallCompletedHandler AddBookMarkToActiveCallCompleted; RESPONSE DELEGATE SIGNATURE delegate void AddBookMarkToActiveCallCompletedHandler(uint invokeid, Exception error); uint invokeid Exception error The invoke ID of the request. Null if the request succeeded. If not null, the request failed and this object contains the reason for the failure. AddBookmarkByCallID The third-party app calls this method to attach a bookmark or annotation to the call identified by a call ID. SYNCHRONOUS METHOD SIGNATURE void AddBookMarkByCallID (string callid, string subject, string text) ASYNCHRONOUS METHOD SIGNATURE uint AddBookMarkByCallIDAsynch (string callid, string subject, string text) string callid string subject string text Identifies the call. The subject of the bookmark/annotation. The text of the bookmark/annotation. OAISYS API Overview and Developer s Guide 62

64 SYNCHRONOUS RETURN VALUE void ASYNCHRONOUS RETURN VALUE uint The invoke ID of the request. Cache it and compare it to the invoke ID contained in the response event to synch up request with response. EXCEPTIONS FOR THE SYNCHRONOUS METHOD An exception will occur if the request fails for any reason. EXCEPTIONS FOR THE ASYNCHRONOUS METHOD An exception will occur only if a failure of some kind occurs; for example something is wrong with the socket connection. RESPONSE EVENT SIGNATURE event AddBookMarkByCallIDCompletedHandler AddBookMarkByCallIDCompleted; RESPONSE DELEGATE SIGNATURE delegate void AddBookMarkByCallIDCompletedHandler(uint invokeid, Exception error); uint invokeid Exception error The invoke ID of the request. Null if the request succeeded. If not null, the request failed and this object contains the reason for the failure. AddBookmarkByExtension The third-party app calls this method to attach a bookmark or annotation to the call involved on the specified extension. OAISYS API Overview and Developer s Guide 63

65 SYNCHRONOUS METHOD SIGNATURE void AddBookMarkByExtension (string extension, string subject, string text) ASYNCHRONOUS METHOD SIGNATURE uint AddBookMarkByExtensionAsynch (string extension, string subject, string text) string extension string subject string text The extension where the desired call resides. The subject of the bookmark/annotation. The text of the bookmark/annotation. SYNCHRONOUS RETURN VALUE void ASYNCHRONOUS RETURN VALUE uint The invoke ID of the request. Cache it and compare it to the invoke ID contained in the response event to synch up request with response. EXCEPTIONS FOR THE SYNCHRONOUS METHOD An exception will occur if the request fails for any reason. EXCEPTIONS FOR THE ASYNCHRONOUS METHOD An exception will occur only if a failure of some kind occurs; for example something is wrong with the socket connection. RESPONSE EVENT SIGNATURE event AddBookMarkByExtensionCompletedHandler AddBookMarkByExtensionCompleted; OAISYS API Overview and Developer s Guide 64

66 RESPONSE DELEGATE SIGNATURE delegate void AddBookMarkByExtensionCompletedHandler(uint invokeid, Exception error); uint invokeid Exception error The invoke ID of the request. Null if the request succeeded. If not null, the request failed and this object contains the reason for the failure. RecordStartActiveCall The third-party app calls this method to start recording the currently active call. SYNCHRONOUS METHOD SIGNATURE void RecordStartActiveCall (); ASYNCHRONOUS METHOD SIGNATURE uint RecordStartActiveCallAsynch (); SYNCHRONOUS RETURN VALUE void ASYNCHRONOUS RETURN VALUE uint The invoke ID of the request. Cache it and compare it to the invoke ID contained in the response event to synch up request with response. EXCEPTIONS FOR THE SYNCHRONOUS METHOD An exception will occur if the request fails for any reason. OAISYS API Overview and Developer s Guide 65

67 EXCEPTIONS FOR THE ASYNCHRONOUS METHOD An exception will occur only if a failure of some kind occurs; for example something is wrong with the socket connection. RESPONSE EVENT SIGNATURE event RecordStartActiveCallCompletedHandler RecordStartActiveCallCompleted; RESPONSE DELEGATE SIGNATURE delegate void RecordStartActiveCallCompletedHandler(uint invokeid, Exception error); uint invokeid Exception error The invoke ID of the request. Null if the request succeeded. If not null, the request failed and this object contains the reason for the failure. RecordStartByCallID The third-party app calls this method to start recording the call identified by the supplied call ID. SYNCHRONOUS METHOD SIGNATURE void RecordStartByCallID (string callid) ASYNCHRONOUS METHOD SIGNATURE uint RecordStartByCallIDAsynch (string callid) string callid Identifies the call. OAISYS API Overview and Developer s Guide 66

68 SYNCHRONOUS RETURN VALUE void ASYNCHRONOUS RETURN VALUE uint The invoke ID of the request. Cache it and compare it to the invoke ID contained in the response event to synch up request with response. EXCEPTIONS FOR THE SYNCHRONOUS METHOD An exception will occur if the request fails for any reason. EXCEPTIONS FOR THE ASYNCHRONOUS METHOD An exception will occur only if a failure of some kind occurs; for example something is wrong with the socket connection. RESPONSE EVENT SIGNATURE event RecordStartByCallIDCompletedHandler RecordStartByCallIDCompleted; RESPONSE DELEGATE SIGNATURE delegate void RecordStartByCallIDCompletedHandler(uint invokeid, Exception error); uint invokeid Exception error The invoke ID of the request. Null if the request succeeded. If not null, the request failed and this object contains the reason for the failure. RecordStartByExtension The third-party app calls this method to start recording the call that is involved on the specified extension. OAISYS API Overview and Developer s Guide 67

69 SYNCHRONOUS METHOD SIGNATURE void RecordStartByExtension (string extension) ASYNCHRONOUS METHOD SIGNATURE uint RecordStartByExtensionAsynch (string extension) string extension The extension that is involved with the call. SYNCHRONOUS RETURN VALUE void ASYNCHRONOUS RETURN VALUE uint The invoke ID of the request. Cache it and compare it to the invoke ID contained in the response event to synch up request with response. EXCEPTIONS FOR THE SYNCHRONOUS METHOD An exception will occur if the request fails for any reason. EXCEPTIONS FOR THE ASYNCHRONOUS METHOD An exception will occur only if a failure of some kind occurs; for example something is wrong with the socket connection. RESPONSE EVENT SIGNATURE event RecordStartByExtensionCompletedHandler RecordStartByExtensionCompleted; RESPONSE DELEGATE SIGNATURE delegate void RecordStartByExtensionCompletedHandler(uint invokeid, Exception error); OAISYS API Overview and Developer s Guide 68

70 uint invokeid Exception error The invoke ID of the request. Null if the request succeeded. If not null, the request failed and this object contains the reason for the failure. RecordStopActiveCall The third-party app calls this method to stop recording the currently active call. SYNCHRONOUS METHOD SIGNATURE void RecordStopActiveCall (); ASYNCHRONOUS METHOD SIGNATURE uint RecordStopActiveCallAsynch (); SYNCHRONOUS RETURN VALUE void ASYNCHRONOUS RETURN VALUE uint The invoke ID of the request. Cache it and compare it to the invoke ID contained in the response event to synch up request with response. EXCEPTIONS FOR THE SYNCHRONOUS METHOD An exception will occur if the request fails for any reason. EXCEPTIONS FOR THE ASYNCHRONOUS METHOD An exception will occur only if a failure of some kind occurs; for example something is wrong with the socket connection. OAISYS API Overview and Developer s Guide 69

71 RESPONSE EVENT SIGNATURE event RecordStopActiveCallCompletedHandler RecordStopActiveCallCompleted; RESPONSE DELEGATE SIGNATURE delegate void RecordStopActiveCallCompletedHandler(uint invokeid, Exception error); uint invokeid Exception error The invoke ID of the request. Null if the request succeeded. If not null, the request failed and this object contains the reason for the failure. RecordStopByCallID The third-party app calls this method to stop recording the call identified by the supplied call ID. SYNCHRONOUS METHOD SIGNATURE void RecordStopByCallID (string callid) ASYNCHRONOUS METHOD SIGNATURE uint RecordStopByCallIDAsynch (string callid) string callid Identifies the call. SYNCHRONOUS RETURN VALUE void OAISYS API Overview and Developer s Guide 70

72 ASYNCHRONOUS RETURN VALUE uint The invoke ID of the request. Cache it and compare it to the invoke ID contained in the response event to synch up request with response. EXCEPTIONS FOR THE SYNCHRONOUS METHOD An exception will occur if the request fails for any reason. EXCEPTIONS FOR THE ASYNCHRONOUS METHOD An exception will occur only if a failure of some kind occurs; for example something is wrong with the socket connection. RESPONSE EVENT SIGNATURE event RecordStopByCallIDCompletedHandler RecordStopByCallIDCompleted; RESPONSE DELEGATE SIGNATURE delegate void RecordStopByCallIDCompletedHandler(uint invokeid, Exception error); uint invokeid Exception error The invoke ID of the request. Null if the request succeeded. If not null, the request failed and this object contains the reason for the failure. RecordStopByExtension The third-party app calls this method to stop recording the call that is involved on the specified extension. SYNCHRONOUS METHOD SIGNATURE void RecordStopByExtension (string extension) OAISYS API Overview and Developer s Guide 71

73 ASYNCHRONOUS METHOD SIGNATURE uint RecordStopByExtensionAsynch (string extension) string extension The extension that is involved with the call. SYNCHRONOUS RETURN VALUE void ASYNCHRONOUS RETURN VALUE uint The invoke ID of the request. Cache it and compare it to the invoke ID contained in the response event to synch up request with response. EXCEPTIONS FOR THE SYNCHRONOUS METHOD An exception will occur if the request fails for any reason. EXCEPTIONS FOR THE ASYNCHRONOUS METHOD An exception will occur only if a failure of some kind occurs; for example something is wrong with the socket connection. RESPONSE EVENT SIGNATURE event RecordStopByExtensionCompletedHandler RecordStopByExtensionCompleted; RESPONSE DELEGATE SIGNATURE delegate void RecordStopByExtensionCompletedHandler(uint invokeid, Exception error); uint invokeid The invoke ID of the request. OAISYS API Overview and Developer s Guide 72

74 Exception error Null if the request succeeded. If not null, the request failed and this object contains the reason for the failure. Popup The third-party app calls this method to make Desktop Client visible and to bring it to the front of all active windows. SYNCHRONOUS METHOD SIGNATURE void Popup () ASYNCHRONOUS METHOD SIGNATURE uint PopupAsynch () SYNCHRONOUS RETURN VALUE void ASYNCHRONOUS RETURN VALUE uint The invoke ID of the request. Cache it and compare it to the invoke ID contained in the response event to synch up request with response. EXCEPTIONS FOR THE SYNCHRONOUS METHOD An exception will occur if the request fails for any reason. EXCEPTIONS FOR THE ASYNCHRONOUS METHOD An exception will occur only if a failure of some kind occurs; for example something is wrong with the socket connection. RESPONSE EVENT SIGNATURE event PopupCompletedHandler PopupCompleted; OAISYS API Overview and Developer s Guide 73

75 RESPONSE DELEGATE SIGNATURE delegate void PopupCompletedHandler(uint invokeid, Exception error); uint invokeid Exception error The invoke ID of the request. Null if the request succeeded. If not null, the request failed and this object contains the reason for the failure. GetCallDataFieldForActiveCall The third-party app calls this method to get the value for a particular call-data field for the active call. SYNCHRONOUS METHOD SIGNATURE object GetCallDataFieldForActiveCall (string name) ASYNCHRONOUS METHOD SIGNATURE uint GetCallDataFieldForActiveCallAsynch (string name) string name Identifies the call-data field. See the section entitled Call-Data Fields for more details. SYNCHRONOUS RETURN VALUE object The value of the call-data field, in its native type. See the section entitled Call-Data Fields for more details. ASYNCHRONOUS RETURN VALUE uint The invoke ID of the request. Cache it and compare it to the invoke ID contained in the response event to synch up request with response. OAISYS API Overview and Developer s Guide 74

76 EXCEPTIONS FOR THE SYNCHRONOUS METHOD An exception will occur if the request fails for any reason. EXCEPTIONS FOR THE ASYNCHRONOUS METHOD An exception will occur only if a failure of some kind occurs; for example something is wrong with the socket connection. RESPONSE EVENT SIGNATURE event GetCallDataFieldForActiveCallCompletedHandler GetCallDataFieldForActiveCallCompleted; RESPONSE DELEGATE SIGNATURE delegate void GetCallDataFieldForActiveCallCompletedHandler(uint invokeid, Exception error, object returnvalue); uint invokeid Exception error object returnvalue The invoke ID of the request. Null if the request succeeded. If not null, the request failed and this object contains the reason for the failure. If error is null, that means the request succeeded and this parameter contains the value of the call-data field, in its native type. If the request failed then this parameter is undefined. GetCallDataFieldByCallID The third-party app calls this method to get the value for a particular call-data field for the given call. SYNCHRONOUS METHOD SIGNATURE object GetCallDataFieldByCallID (string callid, string name) OAISYS API Overview and Developer s Guide 75

77 ASYNCHRONOUS METHOD SIGNATURE uint GetCallDataFieldByCallIDAsynch (string callid, string name) string callid string name Identifies the call. Identifies the call-data field. See the section entitled Call-Data Fields for more details. SYNCHRONOUS RETURN VALUE object The value of the call-data field, in its native type. See the section entitled Call-Data Fields for more details. ASYNCHRONOUS RETURN VALUE uint The invoke ID of the request. Cache it and compare it to the invoke ID contained in the response event to synch up request with response. EXCEPTIONS FOR THE SYNCHRONOUS METHOD An exception will occur if the request fails for any reason. EXCEPTIONS FOR THE ASYNCHRONOUS METHOD An exception will occur only if a failure of some kind occurs; for example something is wrong with the socket connection. RESPONSE EVENT SIGNATURE event GetCallDataFieldByCallIDCompletedHandler GetCallDataFieldByCallIDCompleted; RESPONSE DELEGATE SIGNATURE delegate void GetCallDataFieldByCallIDCompletedHandler(uint invokeid, Exception error, object returnvalue); OAISYS API Overview and Developer s Guide 76

78 uint invokeid Exception error object returnvalue The invoke ID of the request. Null if the request succeeded. If not null, the request failed and this object contains the reason for the failure. If error is null, that means the request succeeded and this parameter contains the value of the call-data field, in its native type. If the request failed then this parameter is undefined. GetCallDataFieldByExtension The third-party app calls this method to get the value for a particular call-data field for the call involved with the given extension. SYNCHRONOUS METHOD SIGNATURE object GetCallDataFieldByExtension (string extension, string name) ASYNCHRONOUS METHOD SIGNATURE uint GetCallDataFieldByExtensionAsynch (string extension, string name) string extension The extension that is involved with the desired call. string name Identifies the call-data field. See the section entitled Call-Data Fields for more details. SYNCHRONOUS RETURN VALUE object The value of the call-data field, in its native type. See the section entitled Call-Data Fields for more details. ASYNCHRONOUS RETURN VALUE uint The invoke ID of the request. Cache it and compare it to the invoke ID contained in the response event to synch up request with response. OAISYS API Overview and Developer s Guide 77

79 EXCEPTIONS FOR THE SYNCHRONOUS METHOD An exception will occur if the request fails for any reason. EXCEPTIONS FOR THE ASYNCHRONOUS METHOD An exception will occur only if a failure of some kind occurs; for example something is wrong with the socket connection. RESPONSE EVENT SIGNATURE event GetCallDataFieldByExtensionCompletedHandler GetCallDataFieldByExtensionCompleted; RESPONSE DELEGATE SIGNATURE delegate void GetCallDataFieldByExtensionCompletedHandler(uint invokeid, Exception error, object returnvalue); uint invokeid Exception error object returnvalue The invoke ID of the request. Null if the request succeeded. If not null, the request failed and this object contains the reason for the failure. If error is null, that means the request succeeded and this parameter contains the value of the call-data field, in its native type. If the request failed then this parameter is undefined. SetCallDataFieldForActiveCall The third-party app calls this method to set the value for a particular call-data field for the currently active call. SYNCHRONOUS METHOD SIGNATURE void SetCallDataFieldForActiveCall (string name, object value) OAISYS API Overview and Developer s Guide 78

80 ASYNCHRONOUS METHOD SIGNATURE uint SetCallDataFieldForActiveCallAsynch (string name, object value) string name object value Identifies the call-data field. See the section entitled Call-Data Fields for more details. The value of the call-data field, preferably in its native type. Note that Desktop Client will attempt type conversion if the supplied type does not match the native type of the call-data field; however, providing the value in the native type is recommended. See the section entitled Call-Data Fields for more details. SYNCHRONOUS RETURN VALUE void ASYNCHRONOUS RETURN VALUE uint The invoke ID of the request. Cache it and compare it to the invoke ID contained in the response event to synch up request with response. EXCEPTIONS FOR THE SYNCHRONOUS METHOD An exception will occur if the request fails for any reason. EXCEPTIONS FOR THE ASYNCHRONOUS METHOD An exception will occur only if a failure of some kind occurs; for example something is wrong with the socket connection. RESPONSE EVENT SIGNATURE event SetCallDataFieldForActiveCallCompletedHandler SetCallDataFieldForActiveCallCompleted; OAISYS API Overview and Developer s Guide 79

81 RESPONSE DELEGATE SIGNATURE delegate void SetCallDataFieldForActiveCallCompletedHandler(uint invokeid, Exception error); uint invokeid Exception error The invoke ID of the request. Null if the request succeeded. If not null, the request failed and this object contains the reason for the failure. SetCallDataFieldByCallID The third-party app calls this method to set the value for a particular call-data field for the specified call. SYNCHRONOUS METHOD SIGNATURE void SetCallDataFieldByCallID (string callid, string name, object value) ASYNCHRONOUS METHOD SIGNATURE uint SetCallDataFieldByCallIDAsynch (string callid, string name, object value) string callid Identifies the call. string name object value Identifies the call-data field. See the section entitled Call-Data Fields for more details. The value of the call-data field, preferably in its native type. Note that Desktop Client will attempt type conversion if the supplied type does not match the native type of the call-data field; however, providing the value in the native type is recommended. See the section entitled Call-Data Fields for more details. SYNCHRONOUS RETURN VALUE void OAISYS API Overview and Developer s Guide 80

82 ASYNCHRONOUS RETURN VALUE uint The invoke ID of the request. Cache it and compare it to the invoke ID contained in the response event to synch up request with response. EXCEPTIONS FOR THE SYNCHRONOUS METHOD An exception will occur if the request fails for any reason. EXCEPTIONS FOR THE ASYNCHRONOUS METHOD An exception will occur only if a failure of some kind occurs; for example something is wrong with the socket connection. RESPONSE EVENT SIGNATURE event SetCallDataFieldByCallIDCompletedHandler SetCallDataFieldByCallIDCompleted; RESPONSE DELEGATE SIGNATURE delegate void SetCallDataFieldByCallIDCompletedHandler(uint invokeid, Exception error); uint invokeid Exception error The invoke ID of the request. Null if the request succeeded. If not null, the request failed and this object contains the reason for the failure. SetCallDataFieldByExtension The third-party app calls this method to set the value for a particular call-data field for the call involved with the specified extension. SYNCHRONOUS METHOD SIGNATURE void SetCallDataFieldByExtension (string extension, string name, object value) OAISYS API Overview and Developer s Guide 81

83 ASYNCHRONOUS METHOD SIGNATURE uint SetCallDataFieldByExtensionAsynch (string extension, string name, object value) string extension The extension that is involved with the desired call. string name object value Identifies the call-data field. See the section entitled Call-Data Fields for more details. The value of the call-data field, preferably in its native type. Note that Desktop Client will attempt type conversion if the supplied type does not match the native type of the call-data field; however, providing the value in the native type is recommended. See the section entitled Call-Data Fields for more details. SYNCHRONOUS RETURN VALUE void ASYNCHRONOUS RETURN VALUE uint The invoke ID of the request. Cache it and compare it to the invoke ID contained in the response event to synch up request with response. EXCEPTIONS FOR THE SYNCHRONOUS METHOD An exception will occur if the request fails for any reason. EXCEPTIONS FOR THE ASYNCHRONOUS METHOD An exception will occur only if a failure of some kind occurs; for example something is wrong with the socket connection. RESPONSE EVENT SIGNATURE event SetCallDataFieldByExtensionCompletedHandler SetCallDataFieldByExtensionCompleted; OAISYS API Overview and Developer s Guide 82

84 RESPONSE DELEGATE SIGNATURE delegate void SetCallDataFieldByExtensionCompletedHandler(uint invokeid, Exception error); uint invokeid Exception error The invoke ID of the request. Null if the request succeeded. If not null, the request failed and this object contains the reason for the failure. GetCallDataFieldInfos This method allows the application to automatically discover all of the call-data fields that Tracer supports. SYNCHRONOUS METHOD SIGNATURE CallDataFieldInfo[] GetCallDataFieldInfos () ASYNCHRONOUS METHOD SIGNATURE uint GetCallDataFieldInfosAsynch () SYNCHRONOUS RETURN VALUE CallDataFieldInfo[] An array containing one CallDataFieldInfo for each call-data field that Tracer supports. See CallDataFieldInfo in the Objects section for more details. ASYNCHRONOUS RETURN VALUE uint The invoke ID of the request. Cache it and compare it to the invoke ID contained in the response event to synch up request with response. EXCEPTIONS FOR THE SYNCHRONOUS METHOD An exception will occur if the request fails for any reason. OAISYS API Overview and Developer s Guide 83

85 EXCEPTIONS FOR THE ASYNCHRONOUS METHOD An exception will occur only if a failure of some kind occurs; for example something is wrong with the socket connection. RESPONSE EVENT SIGNATURE event GetCallDataFieldInfosCompletedHandler GetCallDataFieldInfosCompleted; RESPONSE DELEGATE SIGNATURE delegate void GetCallDataFieldInfosCompletedHandler(uint invokeid, Exception error, CallDataFieldInfo[] returnvalue); uint invokeid Exception error CallDataFieldInfo[] returnvalue The invoke ID of the request. Null if the request succeeded. If not null, the request failed and this object contains the reason for the failure. Valid only if the request succeeded, in which case this is an array containing one CallDataFieldInfo for each call-data field that Tracer supports. See CallDataFieldInfo in the Objects section for more details. GetExtraCallInfoForActiveCall The third-party app calls this method to get the value for a particular extra-call info field for the currently active call. SYNCHRONOUS METHOD SIGNATURE string GetExtraCallInfoForActiveCall (string name) ASYNCHRONOUS METHOD SIGNATURE uint GetExtraCallInfoForActiveCallAsynch (string name) OAISYS API Overview and Developer s Guide 84

86 string name Identifies the extra-call info field. See the section entitled Extra-Call Info Fields for more details. SYNCHRONOUS RETURN VALUE string The value of the extra-call info field. ASYNCHRONOUS RETURN VALUE uint The invoke ID of the request. Cache it and compare it to the invoke ID contained in the response event to synch up request with response. EXCEPTIONS FOR THE SYNCHRONOUS METHOD An exception will occur if the request fails for any reason. EXCEPTIONS FOR THE ASYNCHRONOUS METHOD An exception will occur only if a failure of some kind occurs; for example something is wrong with the socket connection. RESPONSE EVENT SIGNATURE event GetExtraCallInfoForActiveCallCompletedHandler GetExtraCallInfoForActiveCallCompleted; RESPONSE DELEGATE SIGNATURE delegate void GetExtraCallInfoForActiveCallCompletedHandler(uint invokeid, Exception error, string returnvalue); uint invokeid Exception error The invoke ID of the request. Null if the request succeeded. If not null, the request failed and this object contains the reason for the failure. OAISYS API Overview and Developer s Guide 85

87 string returnvalue Valid only if the request succeeded, this is the value of the extra-call info field. GetExtraCallInfoByCallID The third-party app calls this method to get the value for a particular extra-call info field for the specified call. SYNCHRONOUS METHOD SIGNATURE string GetExtraCallInfoByCallID (string callid, string name) ASYNCHRONOUS METHOD SIGNATURE uint GetExtraCallInfoByCallIDAsynch (string callid, string name) string callid string name Identifies the call. Identifies the extra-call info field. See the section entitled Extra- Call Info Fields for more details. SYNCHRONOUS RETURN VALUE string The value of the extra-call info field. ASYNCHRONOUS RETURN VALUE uint The invoke ID of the request. Cache it and compare it to the invoke ID contained in the response event to synch up request with response. EXCEPTIONS FOR THE SYNCHRONOUS METHOD An exception will occur if the request fails for any reason. EXCEPTIONS FOR THE ASYNCHRONOUS METHOD An exception will occur only if a failure of some kind occurs; for example something is wrong with the socket connection. OAISYS API Overview and Developer s Guide 86

88 RESPONSE EVENT SIGNATURE event GetExtraCallInfoByCallIDCompletedHandler GetExtraCallInfoByCallIDCompleted; RESPONSE DELEGATE SIGNATURE delegate void GetExtraCallInfoByCallIDCompletedHandler(uint invokeid, Exception error, string returnvalue); uint invokeid Exception error string returnvalue The invoke ID of the request. Null if the request succeeded. If not null, the request failed and this object contains the reason for the failure. Valid only if the request succeeded, this is the value of the extra-call info field. GetExtraCallInfoByExtension The third-party app calls this method to get the value for a particular extra-call info field for the call involved with the specified extension. SYNCHRONOUS METHOD SIGNATURE string GetExtraCallInfoByExtension (string extension, string name) ASYNCHRONOUS METHOD SIGNATURE uint GetExtraCallInfoByExtensionAsynch (string extension, string name) string extension Identifies the extension. string name Identifies the extra-call info field. See the section entitled Extra- Call Info Fields for more details. OAISYS API Overview and Developer s Guide 87

89 SYNCHRONOUS RETURN VALUE string The value of the extra-call info field. ASYNCHRONOUS RETURN VALUE uint The invoke ID of the request. Cache it and compare it to the invoke ID contained in the response event to synch up request with response. EXCEPTIONS FOR THE SYNCHRONOUS METHOD An exception will occur if the request fails for any reason. EXCEPTIONS FOR THE ASYNCHRONOUS METHOD An exception will occur only if a failure of some kind occurs; for example something is wrong with the socket connection. RESPONSE EVENT SIGNATURE event GetExtraCallInfoByExtensionCompletedHandler GetExtraCallInfoByExtensionCompleted; RESPONSE DELEGATE SIGNATURE delegate void GetExtraCallInfoByExtensionCompletedHandler(uint invokeid, Exception error, string returnvalue); uint invokeid Exception error string returnvalue The invoke ID of the request. Null if the request succeeded. If not null, the request failed and this object contains the reason for the failure. Valid only if the request succeeded, this is the value of the extra-call info field. SetExtraCallInfoForActiveCall The third-party app calls this method to set the value for a particular extra-call OAISYS API Overview and Developer s Guide 88

90 info field for the currently active call. SYNCHRONOUS METHOD SIGNATURE void SetExtraCallInfoForActiveCall (string name, string value) ASYNCHRONOUS METHOD SIGNATURE uint SetExtraCallInfoForActiveCallAsynch (string name, string value) string name string value Identifies the extra-call info field. See the section entitled Extra- Call Info Fields for more details. The value to apply to the extra-call info field. SYNCHRONOUS RETURN VALUE void ASYNCHRONOUS RETURN VALUE uint The invoke ID of the request. Cache it and compare it to the invoke ID contained in the response event to synch up request with response. EXCEPTIONS FOR THE SYNCHRONOUS METHOD An exception will occur if the request fails for any reason. EXCEPTIONS FOR THE ASYNCHRONOUS METHOD An exception will occur only if a failure of some kind occurs; for example something is wrong with the socket connection. RESPONSE EVENT SIGNATURE event SetExtraCallInfoForActiveCallCompletedHandler SetExtraCallInfoForActiveCallCompleted; OAISYS API Overview and Developer s Guide 89

91 RESPONSE DELEGATE SIGNATURE delegate void SetExtraCallInfoForActiveCallCompletedHandler(uint invokeid, Exception error); uint invokeid Exception error The invoke ID of the request. Null if the request succeeded. If not null, the request failed and this object contains the reason for the failure. SetExtraCallInfoByCallID The third-party app calls this method to set the value for a particular extra-call info field for the specified call. SYNCHRONOUS METHOD SIGNATURE void SetExtraCallInfoByCallID (string callid, string name, string value) ASYNCHRONOUS METHOD SIGNATURE uint SetExtraCallInfoByCallIDAsynch (string callid, string name, string value) string callid string name string value Identifies the call. Identifies the extra-call info field. See the section entitled Extra- Call Info Fields for more details. The value to apply to the extra-call info field. SYNCHRONOUS RETURN VALUE void OAISYS API Overview and Developer s Guide 90

92 ASYNCHRONOUS RETURN VALUE uint The invoke ID of the request. Cache it and compare it to the invoke ID contained in the response event to synch up request with response. EXCEPTIONS FOR THE SYNCHRONOUS METHOD An exception will occur if the request fails for any reason. EXCEPTIONS FOR THE ASYNCHRONOUS METHOD An exception will occur only if a failure of some kind occurs; for example something is wrong with the socket connection. RESPONSE EVENT SIGNATURE event SetExtraCallInfoByCallIDCompletedHandler SetExtraCallInfoByCallIDCompleted; RESPONSE DELEGATE SIGNATURE delegate void SetExtraCallInfoByCallIDCompletedHandler(uint invokeid, Exception error); uint invokeid Exception error The invoke ID of the request. Null if the request succeeded. If not null, the request failed and this object contains the reason for the failure. SetExtraCallInfoByExtension The third-party app calls this method to set the value for a particular extra-call info field for the call involved with the specified extension. SYNCHRONOUS METHOD SIGNATURE void SetExtraCallInfoByExtension (string extension, string name, string value) OAISYS API Overview and Developer s Guide 91

93 ASYNCHRONOUS METHOD SIGNATURE uint SetExtraCallInfoByExtensionAsynch (string extension, string name, string value) string extension Identifies the extension. string name string value Identifies the extra-call info field. See the section entitled Extra- Call Info Fields for more details. The value to apply to the extra-call info field. SYNCHRONOUS RETURN VALUE void ASYNCHRONOUS RETURN VALUE uint The invoke ID of the request. Cache it and compare it to the invoke ID contained in the response event to synch up request with response. EXCEPTIONS FOR THE SYNCHRONOUS METHOD An exception will occur if the request fails for any reason. EXCEPTIONS FOR THE ASYNCHRONOUS METHOD An exception will occur only if a failure of some kind occurs; for example something is wrong with the socket connection. RESPONSE EVENT SIGNATURE event SetExtraCallInfoByExtensionCompletedHandler SetExtraCallInfoByExtensionCompleted; RESPONSE DELEGATE SIGNATURE delegate void SetExtraCallInfoByExtensionCompletedHandler(uint invokeid, Exception error); OAISYS API Overview and Developer s Guide 92

94 uint invokeid Exception error The invoke ID of the request. Null if the request succeeded. If not null, the request failed and this object contains the reason for the failure. EnableDigitCaptureForActiveCall The third-party app calls this method to enable digit capture for the currentlyactive call. SYNCHRONOUS METHOD SIGNATURE void EnableDigitCaptureForActiveCall () ASYNCHRONOUS METHOD SIGNATURE uint EnableDigitCaptureForActiveCallAsynch () SYNCHRONOUS RETURN VALUE void ASYNCHRONOUS RETURN VALUE uint The invoke ID of the request. Cache it and compare it to the invoke ID contained in the response event to synch up request with response. EXCEPTIONS FOR THE SYNCHRONOUS METHOD An exception will occur if the request fails for any reason. EXCEPTIONS FOR THE ASYNCHRONOUS METHOD An exception will occur only if a failure of some kind occurs; for example something is wrong with the socket connection. OAISYS API Overview and Developer s Guide 93

95 RESPONSE EVENT SIGNATURE event EnableDigitCaptureForActiveCallCompletedHandler EnableDigitCaptureForActiveCallCompleted; RESPONSE DELEGATE SIGNATURE delegate void EnableDigitCaptureForActiveCallCompletedHandler(uint invokeid, Exception error); uint invokeid Exception error The invoke ID of the request. Null if the request succeeded. If not null, the request failed and this object contains the reason for the failure. EnableDigitCaptureByCallID The third-party app calls this method to enable digit capture for the specified call. SYNCHRONOUS METHOD SIGNATURE void EnableDigitCaptureByCallID (string callid) ASYNCHRONOUS METHOD SIGNATURE uint EnableDigitCaptureByCallIDAsynch (string callid) string callid Identifies the call. SYNCHRONOUS RETURN VALUE void OAISYS API Overview and Developer s Guide 94

96 ASYNCHRONOUS RETURN VALUE uint The invoke ID of the request. Cache it and compare it to the invoke ID contained in the response event to synch up request with response. EXCEPTIONS FOR THE SYNCHRONOUS METHOD An exception will occur if the request fails for any reason. EXCEPTIONS FOR THE ASYNCHRONOUS METHOD An exception will occur only if a failure of some kind occurs; for example something is wrong with the socket connection. RESPONSE EVENT SIGNATURE event EnableDigitCaptureByCallIDCompletedHandler EnableDigitCaptureByCallIDCompleted; RESPONSE DELEGATE SIGNATURE delegate void EnableDigitCaptureByCallIDCompletedHandler(uint invokeid, Exception error); uint invokeid Exception error The invoke ID of the request. Null if the request succeeded. If not null, the request failed and this object contains the reason for the failure. EnableDigitCaptureByExtension The third-party app calls this method to enable digit capture for the call involved with the specified extension. SYNCHRONOUS METHOD SIGNATURE void EnableDigitCaptureByExtension (string extension) OAISYS API Overview and Developer s Guide 95

97 ASYNCHRONOUS METHOD SIGNATURE uint EnableDigitCaptureByExtensionAsynch (string extension) string extension Identifies the extension. SYNCHRONOUS RETURN VALUE void ASYNCHRONOUS RETURN VALUE uint The invoke ID of the request. Cache it and compare it to the invoke ID contained in the response event to synch up request with response. EXCEPTIONS FOR THE SYNCHRONOUS METHOD An exception will occur if the request fails for any reason. EXCEPTIONS FOR THE ASYNCHRONOUS METHOD An exception will occur only if a failure of some kind occurs; for example something is wrong with the socket connection. RESPONSE EVENT SIGNATURE event EnableDigitCaptureByExtensionCompletedHandler EnableDigitCaptureByExtensionCompleted; RESPONSE DELEGATE SIGNATURE delegate void EnableDigitCaptureByExtensionCompletedHandler(uint invokeid, Exception error); uint invokeid The invoke ID of the request. OAISYS API Overview and Developer s Guide 96

98 Exception error Null if the request succeeded. If not null, the request failed and this object contains the reason for the failure. DisableDigitCaptureForActiveCall The third-party app calls this method to disable digit capture for the currentlyactive call. SYNCHRONOUS METHOD SIGNATURE void DisableDigitCaptureForActiveCall () ASYNCHRONOUS METHOD SIGNATURE uint DisableDigitCaptureForActiveCallAsynch () SYNCHRONOUS RETURN VALUE void ASYNCHRONOUS RETURN VALUE uint The invoke ID of the request. Cache it and compare it to the invoke ID contained in the response event to synch up request with response. EXCEPTIONS FOR THE SYNCHRONOUS METHOD An exception will occur if the request fails for any reason. EXCEPTIONS FOR THE ASYNCHRONOUS METHOD An exception will occur only if a failure of some kind occurs; for example something is wrong with the socket connection. RESPONSE EVENT SIGNATURE event DisableDigitCaptureForActiveCallCompletedHandler DisableDigitCaptureForActiveCallCompleted; OAISYS API Overview and Developer s Guide 97

99 RESPONSE DELEGATE SIGNATURE delegate void DisableDigitCaptureForActiveCallCompletedHandler(uint invokeid, Exception error); uint invokeid Exception error The invoke ID of the request. Null if the request succeeded. If not null, the request failed and this object contains the reason for the failure. DisableDigitCaptureByCallID The third-party app calls this method to disable digit capture for the specified call. SYNCHRONOUS METHOD SIGNATURE void DisableDigitCaptureByCallID (string callid) ASYNCHRONOUS METHOD SIGNATURE uint DisableDigitCaptureByCallIDAsynch (string callid) string callid Identifies the call. SYNCHRONOUS RETURN VALUE void ASYNCHRONOUS RETURN VALUE uint The invoke ID of the request. Cache it and compare it to the invoke ID contained in the response event to synch up request with response. OAISYS API Overview and Developer s Guide 98

100 EXCEPTIONS FOR THE SYNCHRONOUS METHOD An exception will occur if the request fails for any reason. EXCEPTIONS FOR THE ASYNCHRONOUS METHOD An exception will occur only if a failure of some kind occurs; for example something is wrong with the socket connection. RESPONSE EVENT SIGNATURE event DisableDigitCaptureByCallIDCompletedHandler DisableDigitCaptureByCallIDCompleted; RESPONSE DELEGATE SIGNATURE delegate void DisableDigitCaptureByCallIDCompletedHandler(uint invokeid, Exception error); uint invokeid Exception error The invoke ID of the request. Null if the request succeeded. If not null, the request failed and this object contains the reason for the failure. DisableDigitCaptureByExtension The third-party app calls this method to disable digit capture for the call involved with the specified extension. SYNCHRONOUS METHOD SIGNATURE void DisableDigitCaptureByExtension (string extension) ASYNCHRONOUS METHOD SIGNATURE uint DisableDigitCaptureByExtensionAsynch (string extension) OAISYS API Overview and Developer s Guide 99

101 string extension Identifies the extension. SYNCHRONOUS RETURN VALUE void ASYNCHRONOUS RETURN VALUE uint The invoke ID of the request. Cache it and compare it to the invoke ID contained in the response event to synch up request with response. EXCEPTIONS FOR THE SYNCHRONOUS METHOD An exception will occur if the request fails for any reason. EXCEPTIONS FOR THE ASYNCHRONOUS METHOD An exception will occur only if a failure of some kind occurs; for example something is wrong with the socket connection. RESPONSE EVENT SIGNATURE event DisableDigitCaptureByExtensionCompletedHandler DisableDigitCaptureByExtensionCompleted; RESPONSE DELEGATE SIGNATURE delegate void DisableDigitCaptureByExtensionCompletedHandler(uint invokeid, Exception error); uint invokeid Exception error The invoke ID of the request. Null if the request succeeded. If not null, the request failed and this object contains the reason for the failure. OAISYS API Overview and Developer s Guide 100

102 Login The third-party app calls this method to authenticate with desktop client. This is the first request the third-party app sends to Desktop Client as all other requests will simply fail until Login has occurred successfully. This provides security to the customer, ensuring that the third-party app has been authorized to interact with Desktop Client. SYNCHRONOUS METHOD SIGNATURE void Login (string username, string password) ASYNCHRONOUS METHOD SIGNATURE uint LoginAsynch (string username, string password) string username string password The username of the user currently logged in to Desktop Client. The password of the user currently logged in to Desktop Client. SYNCHRONOUS RETURN VALUE void ASYNCHRONOUS RETURN VALUE uint The invoke ID of the request. Cache it and compare it to the invoke ID contained in the response event to synch up request with response. EXCEPTIONS FOR THE SYNCHRONOUS METHOD An exception will occur if the request fails for any reason. EXCEPTIONS FOR THE ASYNCHRONOUS METHOD An exception will occur only if a failure of some kind occurs; for example something is wrong with the socket connection. OAISYS API Overview and Developer s Guide 101

103 RESPONSE EVENT SIGNATURE event LoginCompletedHandler LoginCompleted; RESPONSE DELEGATE SIGNATURE delegate void LoginCompletedHandler(uint invokeid, Exception error); uint invokeid Exception error The invoke ID of the request. Null if the request succeeded. If not null, the request failed and this object contains the reason for the failure. MonitorStart The third-party app calls this method to turn on specific events. SYNCHRONOUS METHOD SIGNATURE void MonitorStart(EventFlagsEnum eventflags); ASYNCHRONOUS METHOD SIGNATURE uint MonitorStartAsynch (EventFlagsEnum eventflags) EventFlagsEnum eventflags A bit mask that identifies which events to turn on. See EventFlagsEnum in the Objects section for more details. SYNCHRONOUS RETURN VALUE void OAISYS API Overview and Developer s Guide 102

104 ASYNCHRONOUS RETURN VALUE uint The invoke ID of the request. Cache it and compare it to the invoke ID contained in the response event to synch up request with response. EXCEPTIONS FOR THE SYNCHRONOUS METHOD An exception will occur if the request fails for any reason. EXCEPTIONS FOR THE ASYNCHRONOUS METHOD An exception will occur only if a failure of some kind occurs; for example something is wrong with the socket connection. RESPONSE EVENT SIGNATURE event MonitorStartCompletedHandler MonitorStartCompleted; RESPONSE DELEGATE SIGNATURE delegate void MonitorStartCompletedHandler(uint invokeid, Exception error); uint invokeid Exception error The invoke ID of the request. Null if the request succeeded. If not null, the request failed and this object contains the reason for the failure. MonitorStop The third-party app calls this method to turn off specific events. SYNCHRONOUS METHOD SIGNATURE void MonitorStop (EventFlagsEnum eventflags); OAISYS API Overview and Developer s Guide 103

105 ASYNCHRONOUS METHOD SIGNATURE uint MonitorStopAsynch (EventFlagsEnum eventflags) EventFlagsEnum eventflags A bit mask that identifies which events to turn off. See EventFlagsEnum in the Objects section for more details. SYNCHRONOUS RETURN VALUE void ASYNCHRONOUS RETURN VALUE uint The invoke ID of the request. Cache it and compare it to the invoke ID contained in the response event to synch up request with response. EXCEPTIONS FOR THE SYNCHRONOUS METHOD An exception will occur if the request fails for any reason. EXCEPTIONS FOR THE ASYNCHRONOUS METHOD An exception will occur only if a failure of some kind occurs; for example something is wrong with the socket connection. RESPONSE EVENT SIGNATURE event MonitorStopCompletedHandler MonitorStopCompleted; RESPONSE DELEGATE SIGNATURE delegate void MonitorStopCompletedHandler(uint invokeid, Exception error); uint invokeid The invoke ID of the request. OAISYS API Overview and Developer s Guide 104

106 Exception error Null if the request succeeded. If not null, the request failed and this object contains the reason for the failure. OBJECTS This section defines the custom objects defined in the.net 3.5 libraries for DtApi2, which are referenced by the members of the principal class: OAISYS.Integration.DesktopClient2.DesktopClient. The objects are defined in C# syntax. CallDataFieldInfo This class provides information about a single call-data field. public class CallDataFieldInfo { public string Name { get; } public string Type { get; } public EditTypeEnum EditType { get; } public EnumMember[] PossibleValues { get; } } } PROPERTIES string Name string Type EditTypeEnum EditType EnumMember[] PossibleValues The name of the call-data field. See the Call-Data Fields section for more details. The type of the call-data field. See the Call-Data Fields section for more details. Specifies whether or not the call-data field may be changed, and if so, how. See EditTypeEnum for more details. Optional. If the call-data field supports an enumeration, then this array contains all supported values in the enumeration. See EnumMember for more details. EditTypeEnum Defines the edit behavior for the call-data field. OAISYS API Overview and Developer s Guide 105

107 public enum EditTypeEnum { NoEdit, EditOnce, EditAlways } MEMBERS NoEdit EditOnce EditAlways The call-data field may not be changed. The call-data field may be changed only if its value is currently null. The call-data field may always be changed. EnumMember Defines the name and value of a particular enumeration member. public class EnumMember { public string Name { get; } public object Value { get; } } PROPERTIES string Name object Value The member name; in general, this is what would get displayed to the customer. The member value. This is the actual value that may be stored in the call-data field. EventFlagsEnum Defines the bit masks used to turn on/off events. [Flags] public enum EventFlagsEnum { CallStatusChange = 0x01, CallDataFieldChange = 0x02, OAISYS API Overview and Developer s Guide 106

108 RecordStatusChange = 0x04, ClientStatusChange = 0x08, ExtraCallInfoChange = 0x10, All = -1 } MEMBERS CallStatusChange Specifies the CallStatusChange event. CallDataFieldChange Specifies the CallDataFieldChange event. RecordStatusChange ClientStatusChange Specifies the RecordStatusChange event. Specifies the ClientStatusChange event. ExtraCallInfoChange Specifies the ExtraCallInfoChange event. All Specifies all events. CallStatusEnum Defines the possible call states. public enum CallStatusEnum { Alerting, Connected, Holding, Cleared, Unknown, CallRemoved = } MEMBERS Alerting Connected Holding Cleared Unknown The call is alerting the agent, or the agent is receiving ringback. The agent is connected on the call. The call is on hold at the agent. The agent is no longer involved on the call. The call is in an unknown state. OAISYS API Overview and Developer s Guide 107

109 CallRemoved The call has been removed from Desktop Client and can no longer be interacted with. ClientStatusEnum Defines the possible client states. public enum ClientStatusEnum { Idle, Busy, Starting, NoServer } MEMBERS Idle Busy Starting NoServer The agent is not involved on any call. The agent is busy on a call. Unused. Unused. ILog When the third-party application supplies an instance of this interface to the constructor of the DesktopClient class, the DesktopClient instance will automatically log all communication between the third-party application and Desktop Client, making debugging problems quite a bit easier. public interface ILog { void Write(string line); } METHOD SIGNATURE void Write(string line); string line A line of text data to write to a log. OAISYS API Overview and Developer s Guide 108

110 COM To use this library, the third-party application must reference the following type library: OAISYS.Integration.DesktopClient2.tlb. The third-party application must also ensure the.net interop framework can find these.net assemblies at run time: OAISYS.Integration.dll. o This assembly is not intended to be used directly by the third-party application. OAISYS.Integration.DesktopClient2.dll. o This is the assembly intended for the third-party application. As this is a.net assembly that defines COM objects, the assembly can t be COM registered through normal means (e.g., regsvr32), but must be COM registered via RegAsm. Warning!! Consider that if another application registers a newer version of the COM library on the same machine, this may break your application. To avoid this situation, we highly encourage your application to enable side-by-side COM so that your application controls precisely what version of the COM library should be used. The following document provides more details in this regard: Side-By-Side COM Example Here is an example of how to use the.config file approach to force the.net framework to reference the correct version of the COM library. Suppose your application is named MyApplication. Simply create a file called MyApplication.exe.config, with the contents below, and install to the same directory as your.exe, where X.Y.Z is the version of the COM library. <configuration> <runtime> OAISYS API Overview and Developer s Guide 109