API Overview

Setup

Complete the steps mentioned in the Setup guide.

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.

Examples of this API are available in the 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

Name	Description
code integer	The HTTP response code.
error string	General description of an error.
errors ErrorDetail []	Collection of specific constraint violations associated with the error.

Error Detail

Name	Description
message string	Description of a specific constraint violation.
path string	The location of the constraint violation.

Exceptions

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

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.

1. What is the expected Latency?

• Current avg. latency is ~2 seconds.

1. Are the APIs data streaming or request-response?

• Request-response.

1. Are the API requests async?

• The requests-responses are synchronous.

• However, multiple requests can be sent at the same time.

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

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

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

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

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

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

1. Can we restart from a previous session?

• No.

1. Is there a hierarchy to the answers array?

• No.

1. What is the purpose of the followupId value?

• Sent by the clint to keep state.

1. What is the score field in the response?

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

Postman Collection

26KB

Aisera Channel APIs.postman_collection.json