CoffeeHouse API Documentation for IVA2.0

coffeehouse_api_v1iva2.0.md

Notice! This documentation is outdated & will no longer be updated.

We've recently moved to https://docs.intellivoid.net/coffeehouse/v1/introduction

CoffeeHouse API V1-IVA2.0

This document contains information on how to authenticate and use methods, everything from example requests, object structures are displayed in this document.

Authenticate

CoffeeHouse API uses Intellivoid API, to learn how to authenticate each request see intellivoid_api_authentication.md which goes into details on how to authenticate.

Lydia

Lydia is a chat bot powered by CoffeeHouse, this allows users to have realistic conversations with a bot that can speak in mulitple languages. You can try the demo at CoffeeHouse

How does it work?

Lydia needs to keep track of converstaions to mantain a consistent conversation flow with the user. To accomplish this, sessions are used. At the beginning of every conversation you must create a session and when sending inputs you must provide the given session in order to get a proper output. This documentation will explain how to create sessions and how to use it.

API Methods

Method Name	Access URI	Request Methods	Description
create_lydia_session	https://api.intellivoid.net/coffeehouse/v1/lydia/session/create	GET POST	Creates a new chat session with Lydia
get_lydia_session	https://api.intellivoid.net/coffeehouse/v1/lydia/session/get	GET POST	Gets an existing chat session and it's details
lydia_think_thought	https://api.intellivoid.net/coffeehouse/v1/lydia/session/think	GET POST	Invokes the think method and allows Lydia to return a proper response from user input

Create Session

As explained above, at the beginning of each conversation with each user or group a session must be established, this session must not change throughout the conversation unless it has expired or is no longer available due to an AI Error.

If a new session ID gets established for each incoming message, this will result in weird converstations that will not make sense since the AI will not be able to recall the last few messages of the conversation with the user or group

This method will return a Session Object upon request

Paramerters

Parameter Name	Default Value	Required	Description
target_language	en	False	The default language that the AI will try to base the conversation in

Example Success Response

{ 
   "success": true,
   "response_code": 200,
   "payload": { 
      "session_id": "46db504f80a9eadd0fbec43ff4f75690962242b5c57fb23f6e4f2a23423bcab8",
      "language": "en",
      "available": true,
      "expires": 1581899765
   }
}

Session Object Structure

Name	Type	Description
session_id	string	The ID of the session that must be used for requests like "Think Thought"
language	string	The ISO 639-1 Language code that this session is based in
available	bool	Indicates if this session is available or not. A session can be unavailable if it has expired or a session error raises
expires	int	The Unix Timestamp for when this session will expire

Invalid Language Code Response

This response is given when the parameter target_language contains an invalid value

{
    "success": false,
    "response_code": 400,
    "error": {
        "error_code": 0,
        "type": "CLIENT",
        "message": "The given language code is not a valid ISO 639-1 Language Code"
    }
}

Get Session

This method simply allows you to get the session information given if you provide the correct session id

Paramerters

Parameter Name	Default Value	Required	Description
session_id	None	True	The Session ID given when creating a session with the Create Session method

Example Success Response

{ 
   "success": true,
   "response_code": 200,
   "payload": { 
      "session_id": "46db504f80a9eadd0fbec43ff4f75690962242b5c57fb23f6e4f2a23423bcab8",
      "language": "en",
      "available": true,
      "expires": 1581899765
   }
}

Session Object Structure

Name	Type	Description
session_id	string	The ID of the session that must be used for requests like "Think Thought"
language	string	The ISO 639-1 Language code that this session is based in
available	bool	Indicates if this session is available or not. A session can be unavailable if it has expired or a session error raises
expires	int	The Unix Timestamp for when this session will expire

Session not found response

This response is given when the given session id was not found

{
    "success": false,
    "response_code": 404,
    "error": {
        "error_code": 0,
        "type": "CLIENT",
        "message": "The session was not found"
    }
}

ThinkThought

This method allows you to get an AI output from a user input

Parameters

Parameter Name	Default Value	Required	Description
session_id	None	True	The Session ID given when creating a session with the Create Session module
input	None	True	The user input (eg; "Hello")

Example Success Response

{
    "success": true,
    "response_code": 200,
    "payload": {
        "output": "Hey how are you?"
    }
}

Response Structure

Name	Type	Description
output	string	The output of Lydia

Service No Longer Unavailable Error

This error is returned when the session fails due to an error or has expired

{
    "success": false,
    "response_code": 410,
    "error": {
        "error_code": 0,
        "type": "CLIENT",
        "message": "The session is no longer available"
    }
}

---

This documentation was written with ❤️ by netkas

There are a couple typos, will fix 'em asap

Hi

Hi

Ni