Conversation API

How to integrate own channels and custom interfaces in eva

What is the conversation API

Any developer can integrate their own channels to eva. A user could benefit from a chat in the company’s website using a custom interface or even custom templates for responses, such as graphs, masked inputs or interaction with other elements of the webpage.

Companies normally add chatbot platforms to their existing app, or use one of the internal channels to release a virtual agent for its employees. When using eva, this can be done by consuming the Conversation API described below.

Authentication

Authentication must be handled following the OAuth2 Bearer Token protocol, where one must authenticate with a valid, expirable token. Including the Bearer Token in your header is mandatory from the API version 4.0.0.0 and onwards.

Once obtained, the access token must be sent in your header ‘Authorization’ as the string: “Bearer {{access_token}}”

Obtaining your Authentication Token

To generate a token, make a request on the following endpoint:

POST

{{keycloak_url}}/auth/realms/{{org_name}}/protocol/openid-connect/token

Request Body

client_id: eva-api
username: {{‘[e-mail]’ }}
password: {{‘Password123’}}
grant_type: password

Content-Type is ‘x-www-form-urlencoded’. Username and password are your own credentials; client_id and grant_type are fixed texts. If you lack credentials, ask your administrator to issue a valid user to your environment.

Name	Type	Description
access_token	String	Your bearer token. Can be as long as 800 characters.
expires_in	Integer	Lifetime of your token, in seconds.
refresh_expires_in	Integer	Lifetime of your refresh token, in seconds.
refresh_token	String	Your refresh token, used to renew your token. (See below)

Sample Response Body

While there are several, default fields that you may map from the OAuth2 response body, we recommend you to map those, as they are the only ones you will need to use.

Sample response

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJjUkgxUkZSNkswejU1MmFxUTNmR2JOa0NteFg5dEVTelJRdjktclRMWkRVIn0.eyJleHAiOjE2MzE1NjE1MjAsImlhdCI6MTYzMTU2MTIyMCwianRpIjoiZDc4M2ZkYzQtYjEwNC00NmM2LWIxMGItY2JiNjRlYzk4MjIxIiwiaXNzIjoibmFuYW5pbmFuYW8iLCJzdWIiOiI5OTAxNGJiYS1hNDA3LTRjMDgtODExNi0xNzQ2MTVlZDU3OTIiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJldmEtY29ja3BpdCIsInNlc3Npb25fc3RhdGUiOiIwOWU0YmMxNi01ODhhLTQzNGItOTVjMy1jNmIyMmMxMzBiMGUiLCJhY3IiOiIxIiwic2NvcGUiOiIifQ.TdIj45LlKktpPpwiuiQEN4-Ri47H2BCHLlBbpMQH_7F6HOwQgJhtLDBRcOQEew14UUZESzK-fTyV0Hwe2aWaT_kkx_xZeM1GPmhACIbz7JlVHL6Y8xu43rMl5DsmlQgj8jiDW4Z9ZvYxNJ0fVG_tjK-5eiuIB-KJd7TSvGU0H8yZ3p8ciFcUAlNQH4ufiaxz_VZqwXI6WVj7DDU5dgdpu8rxkGuTUb4urLO0yfRza1QQCoDhRHODTlO0nJRJC0Dc6N_WLpbJIlXFNnaAEQbnMZ-b8CBcDNUwRJdtDbqLDO9Lrd2FaOU8L1CE3U11_t1uje0fKy9G2T6iqav1HAy5kg",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJmZmIyZGU1OC1iNDU3LTRmNmItODI3Yi1hMjUxNGY4YTQ1ZjAifQ.eyJleHAiOjE2MzE1NjMwMjAsImlhdCI6MTYzMTU2MTIyMCwianRpIjoiNGI3MWE4NjYtZjk1YS00MDAxLThjMDEtZDdjODdiOTNhYWNmIiwiaXNzIjoibmFuYW5pbmFuYW8iLCJhdWQiOiJuYW5hbmluYW5hbyIsInN1YiI6Ijk5MDE0YmJhLWE0MDctNGMwOC04MTE2LTE3NDYxNWVkNTc5MiIsInR5cCI6IlJlZnJlc2giLCJhenAiOiJldmEtY29ja3BpdCIsInNlc3Npb25fc3RhdGUiOiIwOWU0YmMxNi01ODhhLTQzNGItOTVjMy1jNmIyMmMxMzBiMGUiLCJzY29wZSI6IiJ9.fBMyJeLsT6JuE9kzQNUGl3FZWvrZ3teA5VgPptXAQlQ",
    "token_type": "Bearer",
    "not-before-policy": 1619470285,
    "session_state": "09e4bc16-588a-434b-95c3-c6b22c130b0e",
    "scope": ""
}

Authentication Token Renewal

Authentication tokens may expire, as indicated by the ‘expires_in’ field from the token generation response. When it does so, you may still renew it without reentering credentials, by calling the same endpoint, but with the following request body:

Renewal Request Body

client_id: eva-api
grant_type: refresh_token
refresh_token: {{The ‘refresh_token’ from the previous response body}}

Once again, Content-Type is ‘x-www-form-urlencoded’. If your refresh_token has also expired (indicated by the field ‘refresh_expires_in’), you are required to generate a new token by reentering the client credentials.

Conversation service

Unsafe Conversation service (Deprecated)

Method	POST
URL:	/conversations or /conversations/{sessionCode}
Type:	application/json

Authenticated conversation service

The conversation service is used to execute a conversation. Each call to this service is a message from the user that the virtual agent must process in order to understand and answer the user. This does not requires any authentication. This method is deprecated and is considered unsafe due to the newest method (see below) that does the same, enforcing a user authentication.

Method	POST
URL:	/v1.0/conversations or /v1.0/conversations/{sessionCode}
Type:	application/json

The conversation service is used to execute a conversation. Each call to this service is a message from the user that the virtual agent must process in order to understand and answer the user. Authorization is required and calls will be refused whenever a token is revoked or expired.

URL Parameters

By default, the session code will expire after 30 minutes. This value is set in eva-broker deployment settings. Contact your system administrator for details.

Name	Type	Required	Description
sessionCode	String	No	Conversation ID. The first call to eva’s conversation service must not have this parameter. After the first call, this parameter is required to keep the conversation. It is returned in the service’s response.

Request headers

Name	Type	Required	Description
PROJECT	String	Yes	The virtual agent name. Same name as the agent created in the Cockpit.
CHANNEL	String	Yes	The channel name. The channel must be created in the virtual agent above through the Cockpit.
API-KEY	String	Yes	API key for client identification. The environment administrator must provide this data.
OS	String	Yes	User operating system. Example: for web chat, might be Windows; and for a mobile app, iOS.
OS-VERSION	String	No	Version of the operating system above.
BROWSER	String	No	User’s browser, when using one.
BROWSER-VERSION	String	No	Version of the browser above
USER-REF	String	Yes	This field is used for identifying the user by a technical value, depending on the channel. Some examples: - For web chat: the user IP address - IVR: phone number - Messenger: Facebook’s user ID
BUSINESS-KEY	String	No	This field is used to identify the user in a business level if the channel has information about the user. Examples: - In a private section of a webpage that requires logging in, the business key might be the user login - User document number - Client #
LOCALE	String	Yes	Virtual agent’s language: <language>-<COUNTRY> This must be the same as configured in the Cockpit. Examples: en-US es-ES pt-BR
AUTHORIZATION	String	Yes	A Bearer Token. For more details, see the Authentication section. Required when calling the ‘Authenticated conversation service’ endpoint.

Request body

Name	Type	Required	Description
text	String	No	Text input by a user or transcription from audio. Either this value or a code (like the one below) must be provided.
code	String	No	On the first call, the code “%EVA_WELCOME_MSG” can be sent to execute the Welcome flow created in the Cockpit. This code might be used to locate a specific answer. Learn more here. Either this value or a text (like the one above) must be provided.
context	JSON Object	No	See Open context
intent	String	No	This parameter is only used with Intent Navigator behaviour (Intent Navigator). Name of the intent identified
confidence	Double	No	SeThis parameter is only used with Intent Navigator behaviour (Intent Navigator). Confidence score for the intent, from 0 to 1
entities	JSON Objec	No	This parameter is only used with Intent Navigator behaviour (Intent Navigator). Entities as Json object containing fields (string, string) with the different entities detected in as key (entity name) and value (entity value)

Response body

Name	Type	Description
text	String	The same text sent in the request or, if no text is provided, the code.
sessionCode	String	Conversation identifier, generated in the first request. This must be sent in the following calls in the URL as explained URL parameters in this chapter.
(Deprecated) intent	String	Name of the intent returned by the NLP for the user message. Only returned when calling the deprecated ‘Unsafe conversation service’.
(Deprecated) confidence	Double	Confidence score for the intent above, from 0 to 1. Only returned when calling the deprecated ‘Unsafe conversation service’.
userInput	UserInput	User input configuration as create through Cockpit’s workspace.
answers	Answer[]	List of responses to be given to the user. Each one might use different templates.
context	JSON Object	See Open context.
contextRead Only	JSON Object	See Visible context.
(New) nlpResponse	Nlp Response	The NLP response data for the user message, including the accuracy score, Intent, Entities, and if you have the AL service, the Questions and Documents, the content varies according to what the NLP processed.

User Input

Name	Type	Description
type	String	Same type as selected by the editor in the Cockpit through the input cell modal.
callToAction	String	For chatbots, text for the input field placeholder for the next message.
pattern	String	When the selected type is ‘Custom’, this field will have the pattern filled by the editor in the Cockpit.

Answer

Name	Type	Description
content	String or JSON Array	Depends on the type of the answer. If it is a Carousel, this field will contain a JSON Array with each card of the carousel. For a file answer, this field will contain an URL and a filename. For other types, this content will be String with the content filled by the editor in the Cockpit.
buttons	Button[]	Button list configured for the answer, showing those buttons inside the response card.
quickReply	Button[]	Button list configured for the answer, showing those buttons as a carousel above the user input.
description	String	Answer’s description. This information is inserted by the editor in the Cockpit and is for organization purposes. It isn`t mandatory.
type	String	Card template selected for the answer. Types include: TEXT_OPTIONS – when the channel is ALL (default response for any channel) - TEXT - IMAGE - AUDIO - VIDEO - FILE - CAROUSEL - CUSTOM
interactionId	String	UUID representing the current interaction. This value can be used for answers like/dislike (thumbs up and down).
evaluable	Boolean	true – if this answer must show a thumbs up / thumbs down (like / dislike) option for the user false – otherwise See Likable service
technicalText	JSON	It is recommended that this field is a Json Object, but the client is free to choose which data format to use. If the field is filled as JSON, a JSON object will be returned by the API. This field aims to provide the customer with a resource that complements the experience of its users.

Learn more about all Answer's features in eva

Button

Name	Type	Description
name	String	Text of the button to be shown and sent back as text on the next call, if the button is clicked (depends on the type)
type	String	Possible values: · URL – if these buttons opens a browser page · FLOW – if the button is an action in the conversation. In this case, when clicked, other API call must be made using the name of the button as text.
action	String	If the type is URL, this field will have the URL that the browser will open.

Carousel card

Name	Type	Description
imageUrl	String	URL for the image on the card
title	String	Title of the card
subTitle	String	Subtitle of the card
buttons	Button[]	Buttons for the card

Learn more about Carousel features in eva

Nlp Response

Name	Type	Description
type	String	Represents the response type, whether it is an intent, question or document.
name	String	Name of the response component (intent, question or document) returned by the NLP for the user message.
score	Double	Confidence score for the response component (intent, question or document) above, from 0 to 1.
entities	Entity[]	All the entities returned by the NLP for the user message.

Entity

Name	Type	Description
name	String	Name of the entity returned by the NLP for the user message.
value	String	Name of the entity value or value entered by the user.
position	Position	It is the location of the entity's value within the user's input.

Position

Name	Type	Description
start	Integer	It is the position of the first character that represents the entity within the user input.
end	Integer	It is the position of the last character that represents the entity within the user input.

Sample requests

The request below is an example of a first call to the conversation service, requesting the execution of the welcome flow. It also add a variable to the context, although it is not necessary.

{
	"code": "%EVA_WELCOME_MSG",
	"context": {
		"user": 25237
	}
}

Another possible request, for following user messages:

{
	"text": "How much do I have in my account?",
	"context":{
		"user": 25237,
		"foo": "bar"
	}
}

Another possible request as Intent Navigator (intent/entities are detected previously and prevented from running NLP on eva):

{
	"text": "How much do I have in my account?",
	"context":{
		"user": 25237,
		"foo": "bar"
	}
	"intent":"”BALANCE",
 	"confidence":0.88,
 	"entities":{
        	"entityName":"entityValue"
 	}
}

Sample response

The following JSON is an example for a response for the request above.

{JSON
   "text": "How much do I have in my account?",
   "sessionCode": "555c03b6-d22f-431d-b82e-2b33aff5719d",
   "intent": "BALANCE",
   "confidence": 0.88,
   "answers": [
      {
         "quickReply": [],
         "interactionId": "2f300826-629f-495c-b925-3d6131946934",
         "buttons": [],
         "description": "",
         "type": "TEXT_OPTIONS",
         "content": "You have 10 points in your wallet."
      }
   ],
   "context": {
      "user": 25237,
      "foo": "bar"
   }
}

Loading answers

When you want to avoid NLP calls, eva offers a front-end pre-processing option that bypasses cognitive processing. The CODE practice ties a specific code to a specific answer and obliges eva to deliver this answer.

In eva, a call to the Conversation API with

 “code”:“%EVA_WELCOME_MSG”

loads the welcome flow. When this code appears, eva is obliged to load the welcome flow. The extension of this behavior to any other answer is what is called the CODE practice.

When you register an answer name, it will also be its “code”, eva will deliver that specific answer when faced with that code. If the answer is transactional, the transaction is done before the answer is delivered. If the answer is not found, the “code” content is sent to the NLP so it can be interpreted.

When eva API encounters a “code” and a “text”, the code is and the text not (unless the text is used by a transactional component). If an answer with the same name of the “code” content is not found, the “text” content is sent to the NLP. This happens too in the middle of a flow. If a code is sent in the middle of a flow, the flow is stopped to run the code.

So, eva loading priority will be code -> answer -> NLP -> Fallback

Important:

Every code interaction is registered in the User Interactions table

This is useful when you want to build a clickable menu with preset options and each option is a code. For example, a simple menu with options such as “check balance”, “check opening times” and “ask for a refund”.

Learn more about all Answer's features in eva

Likable service

Method:	POST
URL:	/likable
Type:	application/json

The likable service is used when an answer is configured to be evaluable. When this option is enable, the answer should give the user a thumps up / thumbs down option (like / dislike) in the chat.

When the user likes or dislikes an answer, this service must be called.

Request headers

Name	Type	Required	Description
API-KEY	String	Yes	Api key for client identification. The environment administrator must provide this data.

Request body

Name	Type	Required	Description
evaluation	Boolean	Yes	true – user liked the answer (thumbs up) false – user disliked the answer (thumbs down)
interactionId	String	Yes	Answer interactionId must be the same received through the conversation service.

Response body

The likable service will return a HTTP Status 200 with a “Success” string.

Sample request

{
   "evaluation": true,
   "interactionId": "7cf85a1e-244b-4c75-bc8d-bb188911c724"
}

Sample Response

"Success"

Satisfaction service

Method:	POST
URL:	/conversations/{sessionCode}/satisfactions
Type:	application/json

When the conversation ends, a form might be given to the user to evaluate the virtual agent. This evaluation has 3 parts:

• A yes/no question asking the user if his doubt or if the problem was solved.

• A grade for the conversation. The range can vary, but it is recommended to use a 0 to 10 grade.

• Comments field for any details the user might want to add.

Important:

This service can be called only once for each sessionCode

URL parameters

Name	Type	Required	Description
sessionCode	String	No	ID of the conversation. Same as the conversation service.

Request headers

Name	Type	Required	Description
API-KEY	String	Yes	API key for client identification. The environment administrator must provide this data.
LOCAL	String	Yes	Virtual agent’s language: <language>-<COUNTRY> This must be the same as configured in the Cockpit. Examples: - en-US - es-ES - pt-BR

Request body

Name	Type	Required	Description
evaluation	Short number	Yes	This number represents how the user graded the virtual agent. It is recommended to be a number from 1 to 10, but can be changed to use other systems (i.e. 5 stars)
answered	Short number	Yes	Considering that a user interacts with a virtual agent to have a question/problem answered: 1 – the user had its problem solved 0 – his problem was not solved
userComments	String	No	User comments about the session.
expireSession	Boolean	Yes	· true – when the session should be expired · false – the session must not be expired because the conversation might still continue

Response body

The satisfaction service will return a HTTP Status 200 with a “Success” string.

Sample request

{
 "evaluation": 5, 
 "answered": "true",
 "userComments": "You answered where to find the information, but why didn’t you give the info in the chat?",
 "expireSession": true
}

Sample response

"Success"

Recommended Practices

Message Protection

Messages sent to the conversation API are sent with both the user’s message data, which may contain sensitive information and with your eva token.

While one attempt a straightforward implementation in their front-end website that immediately calls our API, we highly recommend against that as it can endanger your user's data, your token integrity, and breaches the GDPR.

Leaving this valuable information exposed may be exploited and also exposes your token to anyone who wants it in the console. Furthermore, your data is now spoofable by softwares such as sharks which may intercept your messages if they are transmitted with their data in a human language.

Sending your raw requests from the front-end is an understandable practice during your development phase, but we highly recommend you to add a custom security layer for this data, encrypting all messages sent by the front-end.

One adequate way to do this, is to have your back-end act as a security intermediate. A secure message flow would have the messages your user is sending though your chat, encrypted by a library such as CryptoJS, sent to your back-end server instead, which will then decrypt the message and send the request to the Conversation API itself, where the data is not spoofable or exploitable by users.