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

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

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'

Response

{
    "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 as the SDK's handle that for you.

Error response

{
    "status": -1,
    "input": {
        "text": "What time is it?",
        "parameters": {
            "usertimezone": "CEST"
        }
    },
    "message": "Teneo backend error",
    "sessionId": "31992FA776A35DABA3291A4EE1031B5F"
}

Session Management

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

1. When a request comes in that does not contain session details, a new session will be created on the server. The session ID is 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 you received in 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 to be present.
3. After 10 minutes of inactivity, the engine will expire the session. All details stored in the session will be forgotten.
4. 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:

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',
          // If the response header X-Gateway-Session is set
          'X-Teneo-Session': 'JSESSIONID=31992FA776A35DABA3291A4EE1031B5F' // Followed by ';' and the value of X-Gateway-Session
      }
}, function(response) {
        // handle response
});

Ending a session

Usually you don't have to explicitly end a session; the engine will automatically expire a session after 10 minutes of inactivity (this timeout is configurable). However, you can force the engine to end a session by appending endsession to the engine URL. Make sure the session cookie and X-Teneo-Session header (when the X-Gateway-Session header was present in responses) is included in the request, as the engine won't know which session to end otherwise.

Example request

curl -X POST \
  https://some.teneo/engine-url/endsession \
  -H 'Content-Type: application/x-www-form-urlencoded'

Example response

{
    "status" : 1,
    "message" : "logout"
}

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).

What's next?

Now that you have completed this section, you can learn more about how to analyze your bot here.