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](/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](/manage/bots) tab. 

![manage bots 2](//images.ctfassets.net/2vbtnveccz5s/Zrhf65hjxegR1jtkOTXpH/0ec544e454f5217521cfd21cb010ba3d/manage_bots_2.png)

You can also find the Teneo Web Chat URL in the publication endpoint of your solution.
![Deploy - Publish your bot ](//images.ctfassets.net/2vbtnveccz5s/3NYFv0cbMyoyaEmULaPnjR/9a2429df99092559734bc860017a262b/published-envtwc.png)

Engine URL

## 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:

|  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](/article/build/scripting/concepts/scripts#global-scripts_session_pre-processing).

## Response
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](#session-management). |

### Input object

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

### Output object

|  Key  |  Description  |
|  :-----          |  :-----          |
|  text |  String containing the [answer text](/studio/flows/concepts/outputs#answer-texts) of the output node. |
|  emotion |  String containing the value of the [emotion field](/studio/flows/concepts/outputs#urls-and-emotions) of the output node. |
|  link |  String containing the output [hyperlink field](/studio/flows/concepts/outputs#urls-and-emotions) of the output node. |
|  parameters |  Map containing the output node's [output parameters](/studio/flows/concepts/outputs#output-parameters). |

## Example

Example of a request that contains the following parameters:

|  Parameter  |  Value  |
|  :-----          |  :-----          |
|  userinput |  What time is it? |
|  usertimezone |  CEST |
|  viewtype |  tieapi |

### 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

```json
{
    "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

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


Requests and responses

## 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](#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](/article/build/scripting/concepts/engine-scripting-api#common-scripts_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](/article/deploy#sdks), 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](/article/deploy/sdks/nodejs), for example, this could be achieved as follows:

```javascript
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
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
```
curl -X POST \
  https://some.teneo/engine-url/endsession \
  -H 'Content-Type: application/x-www-form-urlencoded'
```

#### Example response

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

Session management

## 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](/studio/scripting/concepts/resources-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).

Engine API

Requests and responses

Request parameters

Response

Input object

Output object

Example

Request

Response

Error response

Next page

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

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.