> 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" %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.aisera.com/apis/apis/conversation-api-and-websocket/api-overview.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.