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.
Requirements
For building and running the application you need:
Dependencies
The external dependencies of this project are:
Environment Variables
To change the default value of some project settings just set the following environment variables:
Redis
Copy 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}
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.
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:
Copy <dependency>
<groupId>com.everis.eva</groupId>
<artifactId>eva-evg-connector</artifactId>
<version>1.0.0</version>
</dependency>
To download the dependency, configure your settings.xml as follows:
Copy <? xml version = "1.0" encoding = "UTF-8" ?>
< settings xmlns = "http://maven.apache.org/SETTINGS/1.0.0"
xmlns : xsi = "http://www.w3.org/2001/XMLSchema-instance"
xsi : schemaLocation = "http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd" >
< servers >
< server >
< id >artifact-registry-evg</ id >
< configuration >
< httpConfiguration >
< get >
< usePreemptive >true</ usePreemptive >
</ get >
< head >
< usePreemptive >true</ usePreemptive >
</ head >
< put >
< params >
< property >
< name >http.protocol.expect-continue</ name >
< value >false</ value >
</ property >
</ params >
</ put >
</ httpConfiguration >
</ configuration >
< username >_json_key_base64</ username >
<password>ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb3VudCIsCiAgInByb2plY3RfaWQiOiAiY2FsbS1wcmVtaXNlLTE2ODQyMCIsCiAgInByaXZhdGVfa2V5X2lkIjogIjQ4NTYxY2MxYzViODdhMDgwZmYwODgwOTQ0ZDcwMTEzNmZmMDY1MTIiLAogICJwcml2YXRlX2tleSI6ICItLS0tLUJFR0lOIFBSSVZBVEUgS0VZLS0tLS1cbk1JSUV2QUlCQURBTkJna3Foa2lHOXcwQkFRRUZBQVNDQktZd2dnU2lBZ0VBQW9JQkFRRFV4OWJjaE9lYVJISzBcbmcxcVNXaXdWeVZ1dDVRdkpHaUhjdTdYUW1rdGxpbjVLVmx3VkpaYUptVU1sQVpaNnZsZTVMTDBWMmh1TlhFdFJcbmlvZTVZWWFYRVhjRU5vek16dGNsbWVUcHBmdFJEWjZMUWF2b2Q0cWtxUS9nQVlTNXVHY3Y0SmNQZWFYNG91ZHJcbjNTZ1g3Ymdhd2hyZHoyYnRUdDJvVFdzMXc4K2lBc1ErRUQreUpqSFFBdVRQMnNVUjV4Ty95WGxVV1lnaEJyQ1RcbnJ5VVVFZnpQbnJLSTdoUUZsclMrMXo4WGxZb0kza2Npc1JkcVN0RGhlY1dVV2lqd2pBTkxrQklOWlZKV3kwTzBcbmF5L1RhME1ReFR0dU9WU1J2ZnZRV2VYMWhFVCtIOGZiTE5KWXNXNUhsTEx0eE1vem5WWHlxb05MNUhGY0R2emhcblZaWW1RMStmQWdNQkFBRUNnZ0VBRHpSVWN4K0FHVExvNjJNemRwL0E1TEdsdm5CT2ZrbEN3QzRkbU5GZHI5ek1cbmwyMUNXVFI5WkVteVZaT2VlQmpmMWRpUGpsOHVkdFJ3Z1Z3ZnhLeG1YS2NmMVFvODEybTBUL2lHTmZmcFZHcGZcbnVOMnhkZ1FNd1NWZmdBYzd2N1dna2ZnL2N4aWpObmdWaDB5ZlQ4NXB5R2UwV2NNM1BKL1ZFUEN2UjRFOWRmc1JcblE1OVUxVW1LQkNyVmRPZjIxb0kvdXZjMk1wVTZ6UmZyeDJJVytmNkhvaDVjanFZTUdqTjRjT3JtN1hXVDFmMXBcblhRdFpOUURsWFVpOGJ5NkRjYklYUWxaSlN3L1ZvdmdCL0pSTjgyWU5uVHhiSmpubkx1SS9FQUc1bHNpZmpRMlFcbkF6Y2x3ak84Q2dnREluaEhqemRqOFZzZVZCT2dIeUI3SXJaUHI3d253UUtCZ1FEdTM0b1JPTnRldjZObDhOcjFcbmtVT3dmNkRLSiswektkWDdKN2tuTnIrYXdyTXFjd3ZUcE9GYWZCOFg4Z0F3THNKa2hXdUw1aFZtS2tvL0szdzRcbldtcGF2Vm9JSWJPakZ3bkJuQXVsYkhlcC9lSXdLQlExQksxTzhyc3BDL1YwelpqVDFBMHJjVzJGTkRYbWE4TnJcbnRERnN1bHhka3B6cnduYy80bENBdGppd1lRS0JnUURrQ1dCOTdJL256R0NBQ0lXemZOeU9HTTErSmtiNVlmZkFcbi9vYnlHMWIreSt3MGpqbVEvd3RBaStYcXFxckRpMjVwU1RZZGtISzdWbm53eXphdXorSk5uM1Ntdk9TbVMydE5cbmVYK1p1WTBuVEdXZW53ZGMxOU1SMzlGOWF1SzArOUszYW1OVVpNQkRFWUpFbFEraW80N3hid1c3ZjFZTldVWFZcbm85QVhQVFlQL3dLQmdGTnBvY2ZUeDk2MUlyVEZQMkNEQWxVT3JESUxjU3Z0anZndDdkekFwSFhCU1Zrb1pWZlpcbmVvdmpUZVJKc0VFakF1U2hKbVhxeVV3c3RsS0t0OHpoM2NPajNWMTdqMFFERm5nU0tvcndiblRnMyt3YkFydGtcbno3UUMxTkpIaDhYcXlWUW05eFpWZkg0SU5rNHBFVXQ1MTh4MDR5NFZ0VkFxVHdQeTNsT2p6ZlhoQW9HQWVjRkhcbjgvUkxJY2pOL1k2UFZMWm1UTGlSZjdtUVM3Y3pRYWlsQkwvMFF6YytkeEU1UzJIaDhDVENMZm5TRTNadkRXZzVcbnJLOWprd01wT0poSUtpNTA5bDBkTzZtL3E4cTVFRFMvSEtVbDZNV3h2Ry9NenBXdDdPMUVQV0xFaVQycjFLTEpcblJsWkZFWXBYczZhaklvT1IzdmNZYUhRa3podk1YYldKZGQ4STdxRUNnWUFQTW0xVFRmQVR5NmJ3RXVaUnhYVktcbjRkU2NteTF3VVo1bGNobGgxNTd4bUNML1A0UDR6VGRtVThkUkhpenVydjFtUk5HaGRTOTJZckxyS2c4ZDJDVS9cbnAwZi8vU296UlltWVk2MDZYSUZ0S3BzbVdHdmg1ZmpRNnB4YjZmdlJDMHArMmdaV0V0YWowWVIwaDVLVGNVR2FcbnJxU2FzbzQxaXZ3UXptVHpNcnRaeUE9PVxuLS0tLS1FTkQgUFJJVkFURSBLRVktLS0tLVxuIiwKICAiY2xpZW50X2VtYWlsIjogInNhLWV2Zy1hcnRpZmFjdC1yZWdpc3RyeS1yZEBjYWxtLXByZW1pc2UtMTY4NDIwLmlhbS5nc2VydmljZWFjY291bnQuY29tIiwKICAiY2xpZW50X2lkIjogIjExNzg0NzcwMDQ2MDQ4ODI0NTg1OCIsCiAgImF1dGhfdXJpIjogImh0dHBzOi8vYWNjb3VudHMuZ29vZ2xlLmNvbS9vL29hdXRoMi9hdXRoIiwKICAidG9rZW5fdXJpIjogImh0dHBzOi8vb2F1dGgyLmdvb2dsZWFwaXMuY29tL3Rva2VuIiwKICAiYXV0aF9wcm92aWRlcl94NTA5X2NlcnRfdXJsIjogImh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL29hdXRoMi92MS9jZXJ0cyIsCiAgImNsaWVudF94NTA5X2NlcnRfdXJsIjogImh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL3JvYm90L3YxL21ldGFkYXRhL3g1MDkvc2EtZXZnLWFydGlmYWN0LXJlZ2lzdHJ5LXJkJTQwY2FsbS1wcmVtaXNlLTE2ODQyMC5pYW0uZ3NlcnZpY2VhY2NvdW50LmNvbSIKfQ==</password>
</ server >
</ servers >
< profiles >
< profile >
< id >artifact-eva</ id >
< repositories >
< repository >
< id >artifact-registry-evg</ id >
< url >https://us-east1-maven.pkg.dev/calm-premise-168420/eva-evg</ url >
< releases >
< enabled >true</ enabled >
</ releases >
< snapshots >
< enabled >true</ enabled >
</ snapshots >
</ repository >
< repository >
< id >repo1</ id >
< url >https://repo1.maven.org/maven2/</ url >
< releases >
< enabled >true</ enabled >
</ releases >
< snapshots >
< enabled >true</ enabled >
</ snapshots >
</ repository >
< repository >
< id >Sonatype Repository</ id >
< url >https://oss.sonatype.org/content/repositories/releases/</ url >
< releases >
< enabled >true</ enabled >
</ releases >
< snapshots >
< enabled >true</ enabled >
</ snapshots >
</ repository >
< repository >
< id >Spring Plugins Repository</ id >
< url >https://repo.spring.io/plugins-release/</ url >
< releases >
< enabled >true</ enabled >
</ releases >
< snapshots >
< enabled >true</ enabled >
</ snapshots >
</ repository >
< repository >
< id >Spring Lib M Repository</ id >
< url >https://repo.spring.io/libs-milestone/</ url >
< releases >
< enabled >true</ enabled >
</ releases >
< snapshots >
< enabled >true</ enabled >
</ snapshots >
</ repository >
< repository >
< id >Hortonworks Repository</ id >
< url >https://repo.hortonworks.com/content/repositories/releases/</ url >
< releases >
< enabled >true</ enabled >
</ releases >
< snapshots >
< enabled >true</ enabled >
</ snapshots >
</ repository >
< repository >
< id >Atlassian Repository</ id >
< url >https://maven.atlassian.com/content/repositories/atlassian-public/</ url >
< releases >
< enabled >true</ enabled >
</ releases >
< snapshots >
< enabled >true</ enabled >
</ snapshots >
</ repository >
< repository >
< id >JCenter</ id >
< url >https://jcenter.bintray.com/</ url >
< releases >
< enabled >true</ enabled >
</ releases >
< snapshots >
< enabled >true</ enabled >
</ snapshots >
</ repository >
< repository >
< id >JBossEA Repository</ id >
< url >https://repository.jboss.org/nexus/content/repositories/ea/</ url >
< releases >
< enabled >true</ enabled >
</ releases >
< snapshots >
< enabled >true</ enabled >
</ snapshots >
</ repository >
< repository >
< id >Spring Lib Release Repository</ id >
< url >https://repo.spring.io/libs-release/</ url >
< releases >
< enabled >true</ enabled >
</ releases >
< snapshots >
< enabled >true</ enabled >
</ snapshots >
</ repository >
< repository >
< id >Apache Releases Repository</ id >
< url >https://repository.apache.org/content/repositories/releases/</ url >
< releases >
< enabled >true</ enabled >
</ releases >
< snapshots >
< enabled >true</ enabled >
</ snapshots >
</ repository >
</ repositories >
< pluginRepositories >
< pluginRepository >
< id >repo1</ id >
< name >repo1</ name >
< url >https://repo1.maven.org/maven2/</ url >
< snapshots >
< enabled >true</ enabled >
</ snapshots >
</ pluginRepository >
< pluginRepository >
< id >spring-snapshots</ id >
< name >Spring Snapshots</ name >
< url >https://repo.spring.io/snapshot</ url >
< snapshots >
< enabled >true</ enabled >
</ snapshots >
</ pluginRepository >
</ pluginRepositories >
</ profile >
</ profiles >
< activeProfiles >
< activeProfile >artifact-eva</ activeProfile >
</ activeProfiles >
</ settings >
How to Include Evg Connector
To include the evg-connector in your project, use the @EnableEvgConnector
annotation in your project's main class
Copy 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.
Copy 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-<your_eva_instance_label>.eva.bot/eva-broker/org/<your_org_uuid>/env/<your_env_uuid>/bot/<your_bot_uuid>/channel/<your_channel_uuid>/v1/conversations";
ConversationRequest conversationRequest = createConversationRequest(evg);
conversationRequest.getContext().put("dnis", evg.getTelcoData().getDnis());
HttpHeaders headers = new HttpHeaders();
headers.add("LOCALE", "<your_bot_locale>");
headers.add("OS", "evg");
headers.add("API-KEY", "<your_api_key>");
headers.add("USER-REF", evg.getTelcoData().getAni());
headers.add("BUSINESS-KEY", evg.getTelcoData().getAni());
ConversationAuthProperties conversationAuthProperties = ConversationAuthProperties.builder()
.keycloakUrl(
"https://keycloak-<your_eva_admin_label>.eva.bot/auth/realms/<your_realm_name>/protocol/openid-connect/token")
.clientId("<your_client_id>")
.secret("<your_secret>")
.build();
ConversationResponse conversationResponse = callEva(evg, evaConversationAPIURL,
conversationRequest,
headers, conversationAuthProperties);
MicrosoftProvider microsoftProvider = MicrosoftProvider.builder()
.region("<your_region>")
.subscriptionKey("<your_subscription_key>")
.language("<your_bot_locale>")
.build();
evgSettings.setMicrosoftProvider(microsoftProvider);
List<EvgCommand> 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
Copy {
"evgCallStatus": "INIT",
"telcoData": {
"ani": "<your_ani>",
"dnis": "<your_dnis>",
"sipCallId": "sip-call-id",
"originIp": "ip-example",
"customerSipDomain": "@exemple.com.br"
},
"context": {
}
}
Use this JSON to test your implementation.
Conversation service
Below is the endpoint documentation for the API request mentioned on the previous section:
Request body and Response body
EvgCallStatus
TelcoData
EvgCommand
EvgCommandEnum
EvgCommandResult
EvgResultEnum
Fetch