EVG Connector

Voice Gateway

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:

Redis

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}

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:

<dependency>
    <groupId>com.everis.eva</groupId>
    <artifactId>eva-evg-connector</artifactId>
    <version>1.0.0</version>
</dependency>

It is a maven project with Spring Boot Web, to create a project using Spring see the website: https://start.spring.io/

To download the dependency, configure your settings.xml as follows:

<?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

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.

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

{
    "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:

EVG Connector

Versions

Requirements

Dependencies

Environment Variables

Redis

Getting Started

How to Include Evg Connector

Quickstart

Testing the Connector

Conversation service

EvgCallStatus

TelcoData

EvgCommand

EvgCommandEnum

EvgCommandResult

EvgResultEnum

Fetch