# EVG Connector 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. {% hint style="info" %} 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](https://docs.eva.bot/eva-4.2/using-eva/develop-your-bot/voice-agents). {% endhint %} ### 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: * [JDK 11](https://www.oracle.com/java/technologies/downloads/#java11) * [Maven 3.8.6](https://maven.apache.org) ### Dependencies The external dependencies of this project are: * [Redis](https://redis.io/docs/) ### Environment Variables To change the default value of some project settings just set the following environment variables: #### Redis ``` spring.cache.redis.time-to-live=1800000 spring.cache.type=${CACHETYPE} spring.redis.host=${REDIS_HOST} spring.redis.port=${REDIS_PORT} spring.redis.password=${REDIS_PWD} spring.redis.ssl=${REDIS_SSL} ``` {% hint style="info" %} The default value of the `spring.cache.redis.time-to-live` property is `1800000`, if you don't want to change the value, this property is not required. {% endhint %} ### Getting Started First, we’ll start by creating a Spring Boot web project and adding the eva-evg-connector dependency to our pom.xml file: ``` com.everis.eva eva-evg-connector 1.0.0 ``` {% hint style="warning" %} It is a maven project with Spring Boot Web, to create a project using Spring see the website: {% endhint %} To download the dependency, configure your settings.xml as follows: ```xml artifact-registry-evg true true http.protocol.expect-continue false _json_key_base64 ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb3VudCIsCiAgInByb2plY3RfaWQiOiAiY2FsbS1wcmVtaXNlLTE2ODQyMCIsCiAgInByaXZhdGVfa2V5X2lkIjogIjQ4NTYxY2MxYzViODdhMDgwZmYwODgwOTQ0ZDcwMTEzNmZmMDY1MTIiLAogICJwcml2YXRlX2tleSI6ICItLS0tLUJFR0lOIFBSSVZBVEUgS0VZLS0tLS1cbk1JSUV2QUlCQURBTkJna3Foa2lHOXcwQkFRRUZBQVNDQktZd2dnU2lBZ0VBQW9JQkFRRFV4OWJjaE9lYVJISzBcbmcxcVNXaXdWeVZ1dDVRdkpHaUhjdTdYUW1rdGxpbjVLVmx3VkpaYUptVU1sQVpaNnZsZTVMTDBWMmh1TlhFdFJcbmlvZTVZWWFYRVhjRU5vek16dGNsbWVUcHBmdFJEWjZMUWF2b2Q0cWtxUS9nQVlTNXVHY3Y0SmNQZWFYNG91ZHJcbjNTZ1g3Ymdhd2hyZHoyYnRUdDJvVFdzMXc4K2lBc1ErRUQreUpqSFFBdVRQMnNVUjV4Ty95WGxVV1lnaEJyQ1RcbnJ5VVVFZnpQbnJLSTdoUUZsclMrMXo4WGxZb0kza2Npc1JkcVN0RGhlY1dVV2lqd2pBTkxrQklOWlZKV3kwTzBcbmF5L1RhME1ReFR0dU9WU1J2ZnZRV2VYMWhFVCtIOGZiTE5KWXNXNUhsTEx0eE1vem5WWHlxb05MNUhGY0R2emhcblZaWW1RMStmQWdNQkFBRUNnZ0VBRHpSVWN4K0FHVExvNjJNemRwL0E1TEdsdm5CT2ZrbEN3QzRkbU5GZHI5ek1cbmwyMUNXVFI5WkVteVZaT2VlQmpmMWRpUGpsOHVkdFJ3Z1Z3ZnhLeG1YS2NmMVFvODEybTBUL2lHTmZmcFZHcGZcbnVOMnhkZ1FNd1NWZmdBYzd2N1dna2ZnL2N4aWpObmdWaDB5ZlQ4NXB5R2UwV2NNM1BKL1ZFUEN2UjRFOWRmc1JcblE1OVUxVW1LQkNyVmRPZjIxb0kvdXZjMk1wVTZ6UmZyeDJJVytmNkhvaDVjanFZTUdqTjRjT3JtN1hXVDFmMXBcblhRdFpOUURsWFVpOGJ5NkRjYklYUWxaSlN3L1ZvdmdCL0pSTjgyWU5uVHhiSmpubkx1SS9FQUc1bHNpZmpRMlFcbkF6Y2x3ak84Q2dnREluaEhqemRqOFZzZVZCT2dIeUI3SXJaUHI3d253UUtCZ1FEdTM0b1JPTnRldjZObDhOcjFcbmtVT3dmNkRLSiswektkWDdKN2tuTnIrYXdyTXFjd3ZUcE9GYWZCOFg4Z0F3THNKa2hXdUw1aFZtS2tvL0szdzRcbldtcGF2Vm9JSWJPakZ3bkJuQXVsYkhlcC9lSXdLQlExQksxTzhyc3BDL1YwelpqVDFBMHJjVzJGTkRYbWE4TnJcbnRERnN1bHhka3B6cnduYy80bENBdGppd1lRS0JnUURrQ1dCOTdJL256R0NBQ0lXemZOeU9HTTErSmtiNVlmZkFcbi9vYnlHMWIreSt3MGpqbVEvd3RBaStYcXFxckRpMjVwU1RZZGtISzdWbm53eXphdXorSk5uM1Ntdk9TbVMydE5cbmVYK1p1WTBuVEdXZW53ZGMxOU1SMzlGOWF1SzArOUszYW1OVVpNQkRFWUpFbFEraW80N3hid1c3ZjFZTldVWFZcbm85QVhQVFlQL3dLQmdGTnBvY2ZUeDk2MUlyVEZQMkNEQWxVT3JESUxjU3Z0anZndDdkekFwSFhCU1Zrb1pWZlpcbmVvdmpUZVJKc0VFakF1U2hKbVhxeVV3c3RsS0t0OHpoM2NPajNWMTdqMFFERm5nU0tvcndiblRnMyt3YkFydGtcbno3UUMxTkpIaDhYcXlWUW05eFpWZkg0SU5rNHBFVXQ1MTh4MDR5NFZ0VkFxVHdQeTNsT2p6ZlhoQW9HQWVjRkhcbjgvUkxJY2pOL1k2UFZMWm1UTGlSZjdtUVM3Y3pRYWlsQkwvMFF6YytkeEU1UzJIaDhDVENMZm5TRTNadkRXZzVcbnJLOWprd01wT0poSUtpNTA5bDBkTzZtL3E4cTVFRFMvSEtVbDZNV3h2Ry9NenBXdDdPMUVQV0xFaVQycjFLTEpcblJsWkZFWXBYczZhaklvT1IzdmNZYUhRa3podk1YYldKZGQ4STdxRUNnWUFQTW0xVFRmQVR5NmJ3RXVaUnhYVktcbjRkU2NteTF3VVo1bGNobGgxNTd4bUNML1A0UDR6VGRtVThkUkhpenVydjFtUk5HaGRTOTJZckxyS2c4ZDJDVS9cbnAwZi8vU296UlltWVk2MDZYSUZ0S3BzbVdHdmg1ZmpRNnB4YjZmdlJDMHArMmdaV0V0YWowWVIwaDVLVGNVR2FcbnJxU2FzbzQxaXZ3UXptVHpNcnRaeUE9PVxuLS0tLS1FTkQgUFJJVkFURSBLRVktLS0tLVxuIiwKICAiY2xpZW50X2VtYWlsIjogInNhLWV2Zy1hcnRpZmFjdC1yZWdpc3RyeS1yZEBjYWxtLXByZW1pc2UtMTY4NDIwLmlhbS5nc2VydmljZWFjY291bnQuY29tIiwKICAiY2xpZW50X2lkIjogIjExNzg0NzcwMDQ2MDQ4ODI0NTg1OCIsCiAgImF1dGhfdXJpIjogImh0dHBzOi8vYWNjb3VudHMuZ29vZ2xlLmNvbS9vL29hdXRoMi9hdXRoIiwKICAidG9rZW5fdXJpIjogImh0dHBzOi8vb2F1dGgyLmdvb2dsZWFwaXMuY29tL3Rva2VuIiwKICAiYXV0aF9wcm92aWRlcl94NTA5X2NlcnRfdXJsIjogImh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL29hdXRoMi92MS9jZXJ0cyIsCiAgImNsaWVudF94NTA5X2NlcnRfdXJsIjogImh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL3JvYm90L3YxL21ldGFkYXRhL3g1MDkvc2EtZXZnLWFydGlmYWN0LXJlZ2lzdHJ5LXJkJTQwY2FsbS1wcmVtaXNlLTE2ODQyMC5pYW0uZ3NlcnZpY2VhY2NvdW50LmNvbSIKfQ== artifact-eva artifact-registry-evg https://us-east1-maven.pkg.dev/calm-premise-168420/eva-evg true true repo1 https://repo1.maven.org/maven2/ true true Sonatype Repository https://oss.sonatype.org/content/repositories/releases/ true true Spring Plugins Repository https://repo.spring.io/plugins-release/ true true Spring Lib M Repository https://repo.spring.io/libs-milestone/ true true Hortonworks Repository https://repo.hortonworks.com/content/repositories/releases/ true true Atlassian Repository https://maven.atlassian.com/content/repositories/atlassian-public/ true true JCenter https://jcenter.bintray.com/ true true JBossEA Repository https://repository.jboss.org/nexus/content/repositories/ea/ true true Spring Lib Release Repository https://repo.spring.io/libs-release/ true true Apache Releases Repository https://repository.apache.org/content/repositories/releases/ true true repo1 repo1 https://repo1.maven.org/maven2/ true spring-snapshots Spring Snapshots https://repo.spring.io/snapshot true artifact-eva ``` #### How to Include Evg Connector 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](https://docs.eva.bot/user-guide/using-eva/develop-your-bot/build-your-first-bot#welcome-flow). To know how to configure the Syntphony CAI call see the documentation [Conversation API](https://docs.eva.bot/user-guide/for-technicians/api-guidelines/creating-channels-the-conversation-api) and for more about the authentication of the Conversation API see item [Client Credentials Authorization](https://docs.eva.bot/user-guide/for-technicians/api-guidelines/creating-channels-the-conversation-api#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. ``` import java.util.List; import org.springframework.http.HttpHeaders; import org.springframework.stereotype.Service; import com.everis.eva.evgconnector.properties.EvgSettings; import com.everis.eva.evgconnector.properties.conversation.ConversationAuthProperties; import com.everis.eva.evgconnector.properties.provider.MicrosoftProvider; import com.everis.eva.evgconnector.service.EvgConnectorBase; import com.everis.eva.evgconnector.service.commands.EvgCommand; import com.everis.eva.evgconnector.service.conversation.ConversationRequest; import com.everis.eva.evgconnector.service.conversation.ConversationResponse; import com.everis.eva.evgconnector.service.evg.Evg; @Service public class DemoService extends EvgConnectorBase { private final EvgSettings evgSettings; public DemoService(EvgSettings evgSettings) { this.evgSettings = evgSettings; } @Override public Evg start(Evg evg) { String evaConversationAPIURL = "https://api-.eva.bot/eva-broker/org//env//bot//channel//v1/conversations"; ConversationRequest conversationRequest = createConversationRequest(evg); conversationRequest.getContext().put("dnis", evg.getTelcoData().getDnis()); HttpHeaders headers = new HttpHeaders(); headers.add("LOCALE", ""); headers.add("OS", "evg"); headers.add("API-KEY", ""); headers.add("USER-REF", evg.getTelcoData().getAni()); headers.add("BUSINESS-KEY", evg.getTelcoData().getAni()); ConversationAuthProperties conversationAuthProperties = ConversationAuthProperties.builder() .keycloakUrl( "https://keycloak-.eva.bot/auth/realms//protocol/openid-connect/token") .clientId("") .secret("") .build(); ConversationResponse conversationResponse = callEva(evg, evaConversationAPIURL, conversationRequest, headers, conversationAuthProperties); MicrosoftProvider microsoftProvider = MicrosoftProvider.builder() .region("") .subscriptionKey("") .language("") .build(); evgSettings.setMicrosoftProvider(microsoftProvider); List commands = createCommands(evg, conversationResponse); return createResponse(evg, commands, evgSettings.getFetch()); } } ``` #### Testing the Connector The evg (IVR) to process a call will consume the endpoint that the evg connector provides. The following is a simple example of a request. **Sample JSON** ``` { "evgCallStatus": "INIT", "telcoData": { "ani": "", "dnis": "", "sipCallId": "sip-call-id", "originIp": "ip-example", "customerSipDomain": "@exemple.com.br" }, "context": { } } ``` {% hint style="info" %} Use this JSON to test your implementation. {% endhint %} ### **Conversation service** 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	EvgCallStatus	Yes	An enumeration that represents the status of the call.
telcoData	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	EvgCommand[]	Yes, unless when evgCallStatus is INIT	A list of commands that will be executed in IVR.
fetch	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	EvgCommandEnum	It is an enumeration that represents the type of command that will be executed.
result	EvgCommandResult	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	EvgResultEnum	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.

--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.conversational-ai.syntphony.com/user-guide/voice-gateway/evg-connector.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.