Gyst API Reference

The GystAPI is a simple, yet very powerful, web-based restful API. The API allows a voice application to use all of the CX and IVR efficiency optimization, and high-resolution analytics capabilities of Gyst by engaging in a series of simple http based request/responses with the Gyst Server (GS).

The requests are issued from the voice application to the GS via a simple http get/post format. The responses are received back from the GS in JSON format. These responses or "recommendations" instruct the voice application on how to adjust the voice experience for optimal communications with each individual user. The request/response messaging continues for each phone call or voice bot session supported via the voice application.

The GS runtime code uses simple connect, send data, receive data, and disconnect logic in order to minimize long-running http sessions. When load balancers are used between multiple IVR units and multiple separate GS units, it is essential that all API calls are routed to the appropriate GS for proper operation of the Gyst service.



Using the GystAPI
The GystAPI allows you to access the full functionality of Gyst via three powerful restful API calls:

1. GystServerInit (VoiceApplicationName) - called when the GS is first started.

2. GystPing () - called at anytime to check the status of the GS.

3. GystAPI (Parameters) - called repeatedly during an IVR phone call and/or voice bot session.



1. GystServerInit (VoiceApplicationName)
This request performs the GS initialization function. This will not however, perform a reset at the OS level. All GS related local variable, calibration, and analytics data are initialized via this request. Gyst Analytics reports already generated are not affected. This request must be called first, as soon as the GS is operational. However, it may be called again if the voice application has changed since the last GystServerInit() invocation, or if there is a need to reset the GS calibration or other GS data.

Request Format
https://GSIP/GystServerInit?AppName=App1

Request Parameters
GSIP - unique IP address for each GS
AppName - unique alphanumeric name of the voice application.

Expected Response
{"status": 0}



2. GystPing ()
This request can be called at anytime after the initial call to GystServerInit(). GystPing() is used to check that the status of the GS is fully operational.

Request Format
https://GSIP/GystPing

Request Parameters
GSIP - unique IP address for each GS

Expected Response
{"status": 0}



3. GystAPI(
Parameters)
A series of requests are made to the GS throughout the life of a phone call or voice bot session. The sequence is as described below.


3.1
First GystAPI() Request
The first GystAPI request is made at the very beginning of each Gyst Session (a phone call or voice bot session). This is typically when the voice application goes off-hook to answer an incoming phone call for an IVR System, or when the audio to elicit fulfilment of the first intent slot is just about to be played for a voice bot.

Request Format
https://GSIP/GystAPI?PortNumber=0&IPNumber=0&IPResponse=0&IPModality=0

Request Parameters
GSIP - unique IP address for each GS
PortNumber - must be 0
IPNumber - must be 0
IPResponse - must be 0
IPModality - must be 0

Expected Response
{"status": xxxx}

The returned value of xxxx is the PortNumber assigned by the GS for this particular session. This value must be used as the PortNumber parameter throughout the remainder of the current session.


3.2 Intermediate GystAPI() Requests
Intermediate GystAPI() Requests need to be implemented in the voice application at every point (Dialog Node) at which the caller responds, or when there is an application timeout.

Request Format
https://GSIP/GystAPI?PortNumber=xxxx&IPNumber=yyyy&IPResponse=a&IPModality=b

Request Parameters
GSIP - unique IP address for each GS
PortNumber - unique value between 1 - 1000 and as assigned in the first GystAPI() request above
IPNumber - unique value between 1 - 1000 assigned to each Dialog Node
IPResponse - 0 for a good response, 1 for a bad response or timeout
IPModality - 0 for DTMF, 1 for Speech

Expected Response
{"status": xxx}

The returned value of xxx is the Gyst Recommendation for this particular caller or voice bot user at this particular Dialog Node. In a minimal Gyst implementation, it represents the value of the SSML prosody tag. For more advanced implementations of Gyst, it can represent adaptive timeout values, proactive agent transfer alerts, or alternate audio message prompting, among other parameters.


3.3 Final GystAPI() Request
The final request is made at the end of each Gyst Session – typically when the voice application goes on-hook to terminate a call or when the voice bot fulfils the final slot for the final intent.

Request Format
https://GSIP/GystAPI?PortNumber=xxxx&IPNumber=1001&IPResponse=a&IPModality=b

Request Parameters
GSIP - unique IP address for each GS
PortNumber - unique value between 1 - 1000 and as assigned in the first GystAPI() request above
IPNumber - must be 1001 to signal the end of a session
IPResponse - must be 0
IPModality - must be 0

Expected Response
{"status": 0}