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, for example if no SDK is available for the platform you're working with. If that is the case, this is the page for you.
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 in the publication endpoint of your solution.
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
.
Requests to engine usually contain the following main url parameters:
Parameter | Description |
---|---|
userinput | Optional. The natural language utterance of the user. |
viewtype | Required. Tells engine which jsp template to use for the error response. Use value tieapi . |
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.
The engine response is returned in JSON and can consist of the following fields:
Key | Description |
---|---|
status | Always present. Status code. 0 = success, -1 = error, 1 = logout |
input | Optional. Map containing input details included in the request. |
output | Optional. Map containing engine output details. |
message | Optional. String containing message for responses with status other than 0. |
sessionId | Optional. String containing the engine sessionId. See Session Management. |
Key | Description |
---|---|
text | String containing the input of the user as processed by engine. |
parameters | Map containing the additional parameters that were included in the request. |
Key | Description |
---|---|
text | String containing the answer text of the output node. |
emotion | String containing the value of the emotion field of the output node. |
link | String containing the output hyperlink field of the output node. |
parameters | Map containing the output node's output parameters. |
Example of a request that contains the following parameters:
Parameter | Value |
---|---|
userinput | What time is it? |
usertimezone | CEST |
viewtype | tieapi |
curl -X POST \
https://some.teneo/engine-url/ \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'userinput=What%20time%20is%20it%3F&usertimezone=CEST&viewtype=tieapi'
{
"status": 0,
"input": {
"text": "What time is it?",
"parameters": {
"usertimezone": "CEST"
}
},
"output": {
"text": "Good afternoon! It's 15:26.",
"emotion": "happy",
"link": "https://example.com",
"parameters": {
"displayWidget" : "{\"type\":\"clock\",\"time\":\"15:26\"}"
}
},
"sessionId": "31992FA776A35DABA3291A4EE1031B5F"
}
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, the SDK's handle that for you.
{
"status": -1,
"input": {
"text": "What time is it?",
"parameters": {
"usertimezone": "CEST"
}
},
"message": "Teneo backend error",
"sessionId": "31992FA776A35DABA3291A4EE1031B5F"
}
To allow engine to remember details between requests, client applications should maintain a session with engine. The engine handles sessions as follows:
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 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:
https.get({
host: 'https://some.teneo',
path: 'engine-url/?viewtype=tieapi&userinput=What%20time%20is%20it%3F&usertimezone=CEST',
method: 'POST',
headers: {
'Cookie': 'JSESSIONID=31992FA776A35DABA3291A4EE1031B5F'
}
}, function(response) {
// handle response
});
Usually you don't have to explicitly end a session, engine will automatically expire a session after 10 minutes of inactivity (this timeout is configurable). However, you can force engine to end a session by appending 'endsession' to the engine url. Make sure the session cookie is included in the request, otherwise engine won't know which session to end.
curl -X POST \
https://some.teneo/engine-url/endsession \
-H 'Content-Type: application/x-www-form-urlencoded'
{
"status" : 1,
"message" : "logout"
}
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 let a web application running at one origin (domain) have 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).
Was this page helpful?