Engine API

While most developers will use the available SDK's or connectors to develop applications that interact with the Teneo Engine (or 'engine' in short), there may be a need to interact directly using the engine API, e.g. if no SDK is available for the platform you're working with. If that is the case, this is the page for you.

Engine URL

Once a solution has been developed and tested in Teneo Studio, it can be published to an engine. Once published, the engine contains the solution data and has a unique URL that client applications can use to interact with it.

You can find the Engine URL together with Teneo Web Chat URL in the teams Bots tab.

You can also find the Teneo Web Chat URL in the publication endpoint of your solution.

Requests and responses

Requests to engine are sent over http(s). Both GET and POST requests are allowed, but POST requests are preferred. The Content-Type should be application/x-www-form-urlencoded

.

Request parameters

Requests to engine usually contain the following main URL parameters:

In addition to the URL parameters above, any other parameter can be included in the request. These can be used to provide additional information to your bot. A pre-processing script in your solution can be used to store them in a variable. More details on that here: Pre-processing.

Response

The engine response is returned in JSON and can consist of the following fields:

Input object

Output object

Example

Example of a request that contains the following parameters:

Request

Response

1{
2    "status": 0,
3    "input": {
4        "text": "What time is it?",
5        "parameters": {
6            "usertimezone": "CEST"
7        }
8    },
9    "output": {
10        "text": "Good afternoon! It's 15:26.",
11        "emotion": "happy",
12        "link": "https://example.com",
13        "parameters": {
14            "displayWidget" : "{\"type\":\"clock\",\"time\":\"15:26\"}"
15        }
16    },
17    "sessionId": "31992FA776A35DABA3291A4EE1031B5F"
18}
19
20

Input and output parameters are strings. If a parameter contains JSON, like the value of the output parameter 'displayWidget' above, the JSON is escaped. When interacting with the Teneo engine directly, you will need to unscape and parse the JSON manually. When using the SDK's, manually parsing the values is not needed as the SDK's handle that for you.

Error response

1{
2    "status": -1,
3    "input": {
4        "text": "What time is it?",
5        "parameters": {
6            "usertimezone": "CEST"
7        }
8    },
9    "message": "Teneo backend error",
10    "sessionId": "31992FA776A35DABA3291A4EE1031B5F"
11}
12

Session Management

The client applications maintain a session with the engine to allow the engine to remember details between requests by the users. The engine handles sessions as follows:

Please note that this is only available in SaaS.

1. When a request comes in that does not contain session details, a new session will be created on the server. The session ID will be included in the JSON response and as a cookie in the response header.

• If the response contains the header X-Gateway-Session
  then the next request must include the header X-Teneo-Session
  with the value 'JSESSIONID=session_ID' followed by ';' and the value received from the X-Gateway-Session header.

For example, if the session ID is '31992FA776A3XXXXX1031B5F' and the X-Gateway-Session header contained 'FOO=BAR', then the 'X-Teneo-Session' header should be set to JSESSIONID=31992FA776A3XXXXX1031B5F; FOO=BAR

.

2. To maintain a dialogue in the same session, the next request of the client should include the session ID received in the response, and in responses where the X-Gateway-Session header was present, the X-Teneo-Session header is required.

The X-Teneo-Gateway handling is to keep sessions working when cookies may be blocked. The prime example being in browsers.

4. The engine will expire the session, after 10 minutes of inactivity. All details stored in the session will be forgotten.

This value can be changed, please see Change session timeout for more information.

5. If a request comes in with a session ID that is expired or unknown, the engine will create a new empty session and include the new session ID in the response.

When using the SDK's, session maintenance is usually not something you have to worry about, as it is handled by the SDK. If you don't make use of the SDK's, you should make sure the session cookie received from the engine is included in the request header. The way to do this depends on the language used. In Node.js, for example, this could be achieved as follows:

1https.get({
2      host: 'https://some.teneo',
3      path: 'engine-url/?viewtype=tieapi&userinput=What%20time%20is%20it%3F&usertimezone=CEST',
4      method: 'POST',
5      headers: {
6          'Cookie': 'JSESSIONID=31992FA776A35DABA3291A4EE1031B5F',
7          // If the response header X-Gateway-Session is set
8          'X-Teneo-Session': 'JSESSIONID=31992FA776A35DABA3291A4EE1031B5F' // Followed by ';' and the value of X-Gateway-Session
9      }
10}, function(response) {
11        // handle response
12});
13

Ending a session

The best practice is to end sessions when possible, e.g. by closing the bot's window in Teneo Web Chat. If the session is not ended, the engine will automatically expire sessions after 10 minutes of inactivity by default.

You can end session by appending endsession

to the engine URL. Make sure the session cookie and X-Teneo-Session header (when the X-Gateway-Session header is present in responses) is included in the request, as the engine won't know which session to end otherwise.

Example request

Example response

1{
2    "status" : 1,
3    "message" : "logout"
4}
5

Cross-Origin Resource Sharing (CORS)

When interacting with the Teneo Engine using JavaScript in a browser, the domain that is making requests is often different from the domain used by the Teneo Engine. Cross-Origin Resource Sharing (CORS) is a mechanism that uses additional HTTP headers to tell a browser to give a web application running at one origin (domain) permission to access selected resources from a server at a different origin.

By default, the Teneo Engine includes CORS headers in the responses to browser requests coming from any domain. This means any site can interact with a Teneo Engine. If you want to restrict your solution to only include CORS headers for specific domains, you can add a file called tieapi_cors_origins.txt

to your solution. In Teneo Studio, use the Teneo Resource File Manager to add the file to the views folder. The file should contain the list of allowed origin domains (one domain per line, domains should include port numbers if applicable).