Conversation API

How to integrate own channels and custom interfaces in Syntphony CAI

What is the conversation API

Any developer can integrate their own channels to Syntphony CAI. 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 Syntphony CAI, 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.x 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

In distinction to the Integration API, the Conversation API authenticates with a pair of client credentials, persistent across all of your third party channels and services which might need a stable, consistent access.

Request Body

client_id: {{‘clientName’}}
client_secret: {{‘clientSecret’}}
grant_type: client_credentials

Content-Type is ‘x-www-form-urlencoded’. Client_id and client_secret are your provided client credentials for API usage; grant_type is a fixed value of 'client_credentials'.

Those credentials are delivered to you on environment creation, but should you lack said credentials, you may open a ticket requesting this information in this page.

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. Slightly different from the user credentials renewal, though, you must still provide your client credentials. Yuu may do this, by calling the same endpoint, but with the following request body:

Renewal Request Body

client_id: {{‘clientName’}}
client_secret: {{‘clientSecret’}}
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 services

The conversation service is where you implement your own Syntphony CAI web or custom channel. By using our methods, you can handle any conversation Syntphony CAI performs, besides being able to execute auxiliary methods, such as like and disliking replies and evaluation the conversation.

Input Type

When implementing the conversation API, you are able to handle both Text and Audio inputs. This means that this implementation allows you to use your Web, Web Mobile and Custom (Such as in proprietary apps through JSON implementation) channels with both text and audio inputs.

Both inputs use the same endpoints and their session codes are interchangeable, so your user may submit an input through audio and choose to type afterwards without breaking the conversation.

The body of the request will change when using Audio inputs, and this is detailed below.

(Text) Conversation Service API

Conversation service (Live)

The conversation service is used to execute a conversation from any given channel. Each call to this service is a message from a user that the virtual agent must process in order to understand and answer the user.

Authorization is required, organization specific and slightly configurable. The permissions from the user provided to request the token will be reflected on access, as specified on Authentication. Any calls will be refused whenever a token does not grant access to the provided Organization, Environment or Bot parameters, whenever it is revoked and whenever it expires.

This endpoint is interchangeable with it's Audio Input variant.

Deprecated Conversation service

This alternative URL is deprecated and will be removed in a future release. When using this deprecated version, the Header field 'CHANNEL' must be supplied.

This URL structure is NOT audio compliant. Please update from the deprecated structure if handling audio inputs.

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.

Request headers

If you lack your API KEY, you may request it through a ticket here.

Request body

Response body

User Input

Answer

Learn more about all Answer's features in Syntphony CAI

Button

Carousel card

Learn more about Carousel features in Syntphony CAI

NLP Response

Entity

Position

Possible Errors

The Conversation API is notable in Syntphony CAI's API's in which it has a long list of possible error codes you'll receive for very detailed response for what went wrong. Like all other Syntphony CAI public API, the error codes and objects can be found at the Integration API page. We encourage you to consult our Broker API's page while implementing so you have an easier time with our response codes.

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 Syntphony CAI):

{
	"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, Syntphony CAI offers a front-end pre-processing option that bypasses cognitive processing. The CODE practice ties a specific code to a specific answer and obliges Syntphony CAI to deliver this answer.

In Syntphony CAI, a call to the Conversation API with

 “code”:“%EVA_WELCOME_MSG”

loads the welcome flow. When this code appears, Syntphony CAI 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”, Syntphony CAI 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 Syntphony CAI 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, Syntphony CAI 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 Syntphony CAI

(Audio) Conversation API

As mentioned before, your implementation of the Conversation API for audio or text input remains uses the same endpoint and is interchangeable. Syntphony CAI distinguishes them according to the content-type submitted.

When your submitted content-type is a multipart/form-data structure, Syntphony CAI will discern this implies you are sending an audio file. At this point, the behaviour of the API remains mostly the same - the response, expected headers and parameter structure will not change.

The only part that differs from the text input Conversation API is the Body, as seen below:

Request body (Audio only)

Audio File Specifications

The supplied audio file must comply with some standards in order to be accepted.

The audio file must be no larger than 16 Mb, and it's file type must be one of the following:

• ogg

• wav

Another restriction is it's time limit. Any supplied audio file must be no longer than one minute in lenght. While this will not trigger any API error, any content past the first minute will be ignored.

Likable Service

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.

URL parameters

Request headers

Request body

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

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

Request headers

Request body

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 Syntphony CAI 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.