Overview
The Gyst API is a simple, powerful Web API for optimizing voice applications. It allows voice application developers to make voice assistants and interactive voice response (IVR) systems easier for callers to use. For more about how this patent pending technology works, and the business benefits it provides, you can view the product website here.
Terms relating to voice technologies, along with specific definitions used in the Gyst API are available here. This document assumes however, that the reader has at least moderate familiarity with web technologies and voice application design in general.
Implementation
The Gyst API is accessible to enterprise clients via the HTTP GET and POST Methods. The GET Method is used for retrieving short JSON responses via the API. The POST Method is used for more detailed and comprehensive JSON responses.
Requests are sent as either GET Parameters or a POST JSON Payload from the client voice application to the Gyst Server. Responses are received back from the Gyst Server via the API 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 and/or voice assistant session supported via the voice application. A typical implementation of the Gyst API in a voice application would look similar to...
GystStart, GystNode1, GystNode2, GystNode3......GystEnd
...where GystStart is called at the beginning of the voice session, GystNode is called repeatedly at various (if not all) conversation turns in the session, and GystEnd is called at the end of the session.
The Gyst API is available (with full documentation) on Postman. The best way to try out and use the Gyst API for yourself is via our GET and POST Collections, which are published on the site and publically available.
After you fork the Postman Collections and expand the Gyst API Collections, Folders, and the API Calls, the examples and complete API Documentation are viewable as below on the Gyst home page as shown below.
The API calls use the GystRequest parameter with the following values:
GystRequest = 21 - Start Gyst Session API call - returns GystSession if successful, 0 if not.
GystRequest = 1 - 20 - Gyst Node Transition API call - good speech = 1, bad speech = 11, good dtmf = 2 etc.
GystRequest = 22 - End Gyst Session API call. Returns the SSML tag for the ending dialog.
To start implementing the API in your voice application, follow the Developer Documentation on Postman and keep the following steps in mind.
Step 1 - Making the Start Gyst Session API Request
The first Gyst API 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 fulfillment of the first intent slot is just about to be played for a voice assistant.
Request Format
https://gyst-server-azure-vmXXX/api/values/?GystSession=1&GystNode=1&GystRequest=21
Response Format
"{\"gystServerResponse\": xxxx}"
The returned value of xxxx is the GystSession assigned by the Gyst Server for this particular session. This value must be used by the client application as the GystSession parameter throughout the remainder of this session.
Step 2 - Making Intermediate Gyst Node Transition Requests
Intermediate Gyst Node Transition API Requests need to be implemented in the voice application at every point (Gyst Node) at which the caller responds, or when there is an application timeout. THis is commonly known as a conversation turn.
Request Format
https://gyst-server-azure-vmXXX/api/values/?GystSession=XXXX&GystNode=YYYY&GystRequest=1
Response Format
{\"gystServerResponse\": 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.
Step 3 - Making the End Gyst Session API 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 fulfills the final slot for the final intent.
Request Format
https://gyst-server-azure-vmXXX/api/values/?GystSession=1&GystNode=1&GystRequest=22
Response Format
{\"gystServerResponse\": xxx}"
The Long Form Request uses a more comprehensive set of data variables on both the request and the response. Here the POST verb is used in the request and below is a sample of how the Long Form API request method looks. The same procedures for where and when to insert API calls into your voice application via the GET Method also apply here.
You can go here to see a flat text version of this request, one you can use as a template and to copy, paste and edit in your voice applications.
And here's an example of how the Long Form API response looks. You can go here to see a flat text version of this response, one you can for comparison to the responses in your own voice applications.
In addition to the foregoing, the Gyst API also supports a number of convenient utility functions. These functions allow the developer to assess the state of the Gyst Server and perform routine maintenance if needed. Note that this only applies to customer premise subscriptions and subscriptions that use customer hosted virtual machines. As the Gyst CX product further develops, we will be adding new capabilities here.
GystRequest = 23 - request the number of Gyst Sessions currently active
GystRequest = 24 - request a reset of any idle Gyst Ports
GystRequest = 25 - request the current Gyst Recommendation for the session specified in GystSession
GystRequest = 26 - request a reset of all Gyst Ports
GystRequest = 27 - request turning off the Gyst Analytics reporting feature
GystRequest = 28 - request a random number from the Gyst Server
GystRequest = 199 - request a Gyst Server All Data Reset
