The eva-evg-connector is an IVR integration channel with Syntphony CAI.
In this guide we will see how to set up a project using the eva-evg-connector.
For more information on how to create flows in Syntphony CAI and what each of the IVR commands is that we will see below, please refer to the following our documentation.
Versions
Note that eva-evg-connector is a peer dependency of Syntphony CAI. This change allows greater flexibility of choosing the right version of the eva-evg-connector client version for Syntphony CAI version.
eva-evg-connector
Syntphony CAI
1.x.x
4.3.x - current
Requirements
For building and running the application you need:
To include the evg-connector in your project, use the @EnableEvgConnector annotation in your project's main class
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import com.everis.eva.evgconnector.annotation.EnableEvgConnector;
@EnableEvgConnector
@SpringBootApplication
public class EvgDemoApplication {
public static void main(String[] args) {
SpringApplication.run(EvgDemoApplication.class, args);
}
}
Quickstart
To give an example of the connector's usage, we will create a class called DemoService and have it extend the EvgConnectorBase class.
The ConversationRequest object is used when calling the Syntphony CAI. What parameters to pass and what will be sent to the eva will be further detailed down this article.
In this example we are making a call to Syntphony CAI in order to execute a Welcome Flow. To know how to configure the Syntphony CAI call see the documentation Conversation API and for more about the authentication of the Conversation API see item Client Credentials Authorization.
This results in the execution of a flow, getting the response from the Syntphony CAI, and generating commands in the IVR based on the Syntphony CAI's response.
Below is the endpoint documentation for the API request mentioned on the previous section:
Method
POST
URL
/conversations
Type
application/json
Request body and Response body
Name
Type
Required
Description
evgCallStatus
Yes
An enumeration that represents the status of the call.
telcoData
Yes
Contains call data such as the number making and receiving the call.
context
JSON Object
Yes
Helper object that can be used to keep the state of the call, in it we can store data that will be kept during the call, for example, the sessionCode of the Syntphony CAI.
commandList
Yes, unless when evgCallStatus is INIT
A list of commands that will be executed in IVR.
fetch
No
Defines IVR behavior when it needs to fetch a page, URL or JSON.
EvgCallStatus
Name
Description
INIT
Indicates the initial state of the call. The first request being made.
CONTINUE
Indicates a call in progress.
USER_DISCONNECTED
This status indicates that the user disconnected the call.
IVR_DISCONNECTED
This status indicates that the IVR disconnected the call.
TRANSFERRED
This status indicates that the IVR disconnected the call.
ERROR
Indicates a error state.
TelcoData
Name
Type
Description
ani
String
Calling number.
dnis
String
Incoming number.
sipCallId
String
It is a unique call id generated by the SBC.
originIp
String
Call source address (SBC address).
customerSipDomain
String
It is the domain that identifies the provider.
EvgCommand
Name
Type
Description
commandOrder
int
Orders the execution of commands.
commandType
It is an enumeration that represents the type of command that will be executed.
result
Result of commands executed.
EvgCommandEnum
Name
Description
PLAY_AUDIO
It is a type of audio media playback, the supported types are: WAV or FLAC.
PLAY_TTS
It is the type that indicates sanitization of a text.
PLAY_SILENCE
It is the reproduction of silence.
VOICE_MENU
Enables the user to interact in the call through voice.
DTMF_MENU
Enables the user to interact in the call through the cell phone keypad.
DTMF_VOICE_MENU
Enables the user to interact in the call through voice and the cell phone keypad.
TRANSFER
Indicates that the call will be transfer.
HANGUP
Indicates that the call will be terminate.
EvgCommandResult
Name
Type
Description
status
Enumeration that indicates the execution status of the requested command.
message
String
Contains the details of the execution.
digits
String
User input, the value is filled when the user uses the cell phone keyboard.
transcription
String
User input, the value is filled when the user speak.
EvgResultEnum
Name
Description
SUCCESS
Indicates a successful queuing of the audio file or a successful queuing of the TTS synthesizer request command.
ERROR
Informs that an error status occurred in the command. More details should be looked for in the error message.
FILLED
This enumeration indicates that the client's response to the menu (either voice or DTMF) successfully met the criteria configured therein. (e.g.: correct number of DTMF digits or successful transcription)
DISCONNECT
This status tells you that the customer disconnected the call while processing the call. Usually occurs during menus or transfer requests.
NO_INPUT
This enumeration indicates that the customer's response to the menu (either voice or DTMF) did not meet the criteria configured therein because he did not type any DTMF option or because he did not speak any words or phrases.
NO_MATCH
This enumeration indicates that the client's response to the menu (either voice or DTMF) did not meet the criteria set there because he did not type a valid DTMF length (but did type some DTMF) or because he did not speak any words or phrases that could be transcribed (But noise was detected).
Fetch
Name
Type
Description
fetchTimeout
Long
The default amount of time in milliseconds the IVR will wait for a page/json fetch.
fetchAudio
String
The path to the default audio file to be used during IVR platform fetch events.
fetchAudioDelay
Long
The default value for the fetch audio delay. This is the amount of time in milliseconds the IVR will wait while transitioning and fetching resources before it starts playing the fetch audio.
fetchAudioMinimum
Long
The minimum time in milliseconds to play a fetch audio source, once started, even if the fetch result arrives in the meantime. The idea is that once the user does begin to hear a fetch audio, it should not be stopped too quickly.
fetchAudioInterval
Long
Controls the time interval between fetch audio loops. The default value is 0. A value of -1 is valid and will prevent the audio loop.
