> For the complete documentation index, see [llms.txt](https://docs.aisera.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aisera.com/apis/apis/conversation-api-and-websocket/api-overview.md).

# API Overview

## Setup

Complete the steps mentioned in the [Setup guide](/apis/apis/conversation-api-and-websocket/setup-and-authorization.md).

## Use

The end user request is sent via a query (text) or action feedback (such as button or dropdown) to the following endpoint:

**https\://\<your tenant id>.chatbot.aisera.cloud/api/receive**\
\
The response formats might include context and other conversational constructs.&#x20;

Examples of this API are available in the [**Postman collection**](#postman-collection).

### Handling Errors

Aisera uses standard HTTP response codes to indicate whether a method completed successfully. HTTP response codes in the 2xx range indicate success. A response in the 4xx range is some sort of failure, and a response in the 5xx range usually indicates an internal system error that cannot be resolved by the user.

#### **Error Response**

<table><thead><tr><th width="197">Name</th><th>Description</th></tr></thead><tbody><tr><td><strong>code</strong><br>integer</td><td>The HTTP response code.</td></tr><tr><td><strong>error</strong><br>string</td><td>General description of an error.</td></tr><tr><td><strong>errors</strong><br>ErrorDetail []</td><td>Collection of specific constraint violations associated with the error.</td></tr></tbody></table>

#### **Error Detail**

<table><thead><tr><th width="199">Name</th><th>Description</th></tr></thead><tbody><tr><td><strong>message</strong><br>string</td><td>Description of a specific constraint violation.</td></tr><tr><td><strong>path</strong><br>string</td><td>The location of the constraint violation.</td></tr></tbody></table>

#### **Exceptions**

<table><thead><tr><th width="264">Exception</th><th width="221">Error Logged</th><th>Possible Cause</th></tr></thead><tbody><tr><td>StatusRuntimeException</td><td>ERR-001: Failed Internal Service Request</td><td>Any gRPC based service calls exceeds deadline to respond</td></tr><tr><td>NullPointerException</td><td>ERR-002: Internal System Error</td><td>Any reference to Null</td></tr><tr><td>IllegalArgumentException</td><td>ERR-003: Internal System Error</td><td>Improper arguments sent to a method</td></tr><tr><td>NoSuchMethodException</td><td>ERR-004: Internal System Error</td><td>Usually occurs when deployment is not completed properly</td></tr><tr><td>ClassNotFoundException</td><td>ERR-005: Internal System Error</td><td>Usually occurs when deployment is not completed properly</td></tr><tr><td>IndexOutOfBoundsException</td><td>ERR-006: Internal System Error</td><td> </td></tr><tr><td>FulfillmentException</td><td>ERR-007: Failed Fulfillment Service</td><td>Any fulfillment exception, eg. Action node or KB node with content failed to be fetched within the flow</td></tr><tr><td>RuntimeException</td><td>ERR-008: Internal System Error</td><td>Any RuntimeExceptions</td></tr><tr><td>UnknownHostException</td><td>ERR-009 - Host Unavailable</td><td>Unable to identify host</td></tr><tr><td>IOException</td><td>ERR-010: Unavailable resource</td><td>Resource provided does not exists</td></tr><tr><td>InterruptedException</td><td>ERR-011: Process Interrupted</td><td> </td></tr><tr><td>Default</td><td>ERR-012: Aisera Unexpected Server Error</td><td>Any other exceptions are logged with this exception</td></tr><tr><td>ICM Exception</td><td>ERR-013:ICM Error: generic_icm_error</td><td>When BOT is not retrained we can see this</td></tr><tr><td>LiveAgentSystemException</td><td>ERR-014 : Live Agent System Error</td><td>When conversation server is unable to start a live agent session</td></tr><tr><td>LanguageServiceException</td><td>ERR-015: Language Service Error</td><td>Language service used to detect or translate failed to process Aisera request</td></tr><tr><td><p></p><pre class="language-markup"><code class="lang-markup">          {
            "followUpId": "F283672027", 
            "text": "followUpText" 
            }
</code></pre></td><td></td><td></td></tr></tbody></table>

### FAQs

1. **How do we pass data (like we do with sessionVars) and how is the data used?**

* Yes, add sessionVars as a body parameter with a json payload.
* The data can be accessed using the built-in sessionVars variable from the Workflows Editor.

2. **What is the expected Latency?**

* Current avg. latency is \~2 seconds.

3. **Are the APIs data streaming or request-response?**

* Request-response.

4. **Are the API requests async?**

* The requests-responses are synchronous.
* However, multiple requests can be sent at the same time.

5. **Does the API request ordering matter (i.e. if the user sends multiple prompts in a row)?**

* Yes, the message ordering matters.
* Messages will be processed in the order that they are received, so it may lead to unexpected results if not ordered correctly.

6. **What is "modeType": "FlowStarted"? What other modeTypes are there?**

* modeType is available in the response to indicate the current state of a conversation.
* modeTypes include:

<table><thead><tr><th width="297">Mode Type</th><th>Description</th></tr></thead><tbody><tr><td>Normal</td><td>KB and Casual.</td></tr><tr><td>FlowStarted</td><td>Workflow has been triggered.</td></tr><tr><td>FlowInProgress</td><td>Workflow is in progress.</td></tr><tr><td>FlowCompleted</td><td>Workflow has been completed.</td></tr><tr><td>LiveAgent</td><td>Live agent flow is being used.</td></tr><tr><td>LiveAgentWaiting</td><td>Live agent waiting for response from the user.</td></tr><tr><td>LiveAgentWaitingUpdate</td><td>User in queue to be assigned a live agent.</td></tr><tr><td>LiveAgentJoined</td><td>Live agent joins the conversation.</td></tr><tr><td>LiveAgentExited</td><td>Live agent left the conversation.</td></tr><tr><td>LiveAgentFileUpload</td><td>Live agent requesting file upload from user.</td></tr><tr><td>Error</td><td>Internal Error.</td></tr><tr><td>ExternalSystemError</td><td>Error from an external system.</td></tr><tr><td>EndSessionSurvey</td><td>Response is an end-of-session survey.</td></tr></tbody></table>

7. **How does hand-off work, for example when exiting the workflow?**

* Workflow completion is indicated by “modeType”:”FlowCompleted” in the response header.
* Live agent hand-off is trigged by a button click or an utterance matching (eg. I want to talk to an agent) in the user request.

8. **How does live chat work?**

* Live agent hand-off is trigged by a button click or an utterance matching (eg. I want to talk to an agent) in the user request.
* Aisera integrates with a live agent system (eg. ServiceNow).
* Live agent receives requests from Aisera on behalf of the user.

9. **Can we retrieve session history or get a specific session by id?**

* Yes, add needsSessionHistory as a body parameter with a value of true.
* Only history for the current session can be retrieved.

10. **Can we restart from a previous session?**

* No.

11. **Is there a hierarchy to the answers array?**

* No.

12. **What is the purpose of the&#x20;*****followupId*****&#x20;value?**

* Sent by the clint to keep state.

13. **What is the&#x20;*****score*****&#x20;field in the response?**

* This field will be deprecated, so it can be ignored.

### Postman Collection

{% file src="/files/ysxaegT9lR38xZi6Cty9" %}