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

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

CoffeeHouse API v2 Documentation

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

Authentication Methods 🔒

There are two types of methods for authentication, the first method is the most common form of authentication which is the use of a API Key, the second method is the use of a certificate.

API Key 🔐

The API Key identifies your API Subscription (plan) on CoffeeHouse which is associated with your Intellivoid Account, it is a simple form of authentication which is used with the parameter api_key in either a POST or GET request, the examples given in this documentation will explain how to accomplish this

Certificate 🔏

A Certificate is represented as a .crt file, which is non-standard. this is sent to the server under the certificate parameter with the contents base64 encoded. This also works with a POST or GET request. The purpose of a certificate is designed for user-friendly clients which would simply prompt the user for a certificate file instead of a API Key.

Authentication used with a certificate is very similar to authentication used with a API Key, with the only difference is that the contents of the certificate is base64 encoded before it gets sent to the server.

Multiple Authentication Methods Notice

Although no errors will be raised when using both an API Key and Certificate during authentication, the certificate will simply be ignored even if the API Key is invalid.

🚩 It is recommended to only use one form of authentication

Authentication Examples 🔍

When this documentation talks about "Parameters", we are talking about the values within a GET request or a POST request (URL Parameters or multipart/form-data). The API Doesn't care where you place your values, for as long as it sent appropriately within the supported request method. This means you can include your API Key in the URL while the rest of your request parameters in a POST Request Body if that's your style.

API Key Example ⭐

Authentication using a API Key is simply done with the api_key parameter.

GET Request

GET /coffeehouse/v2/exampleMethod?api_key=123 HTTP/1.1
Host: api.intellivoid.info

POST Request

POST /coffeehouse/v2/exampleMethod HTTP/1.1
Content-Length: 80
Host: api.intellivoid.info
Content-Type: application/x-www-form-urlencoded

api_key=123

POST Request but with api_key as the GET parameter

POST /coffeehouse/v2/exampleMethod?api_key=123 HTTP/1.1
Content-Length: 7
Host: api.intellivoid.info
Content-Type: application/x-www-form-urlencoded

foo=bar

Certificate Example ⭐

Authentication using a Certificate is simply done with the certificate parameter but the contents of the certificate must be base64 encoded.

For this example the certificate we are using is gonna be

3e4fbdf5993a1b8db769c7498c3087957dba64a161b86de39fe687184884a091e40a95615d847fe0e08e9e20b750a6683af511e2c5c944e63e8a0eb4ed1aa38597def321a753fceb818eb1be7d3e7916a80c99504882fabffb104c39d7f5843f6a094f62a6bfc54147f874d874fb89915f7a83c7f0084795bef43a0290acbd83(8359f8080333b065243814f7ce6fc328fb6bd82caee4e410beb9351a94a97bfa0668d09faf528fc4408d37050125265103c2687602b5f7586aaf62002a3b21e018bd9b6c6aabf47f1297a8e9facb546b4bed6e96f82cd5a70885e4a21d42e72a0dbb8d5d320d8d67a2262cae0cba23d62427a5fb25edfa0cfe11b92e98b82768)^32568f2822a2b90a9cbe32a05280a913-099eab34/intellivoid

When converted to base64, the output is

M2U0ZmJkZjU5OTNhMWI4ZGI3NjljNzQ5OGMzMDg3OTU3ZGJhNjRhMTYxYjg2ZGUzOWZlNjg3MTg0ODg0YTA5MWU0MGE5NTYxNWQ4NDdmZTBlMDhlOWUyMGI3NTBhNjY4M2FmNTExZTJjNWM5NDRlNjNlOGEwZWI0ZWQxYWEzODU5N2RlZjMyMWE3NTNmY2ViODE4ZWIxYmU3ZDNlNzkxNmE4MGM5OTUwNDg4MmZhYmZmYjEwNGMzOWQ3ZjU4NDNmNmEwOTRmNjJhNmJmYzU0MTQ3Zjg3NGQ4NzRmYjg5OTE1ZjdhODNjN2YwMDg0Nzk1YmVmNDNhMDI5MGFjYmQ4Myg4MzU5ZjgwODAzMzNiMDY1MjQzODE0ZjdjZTZmYzMyOGZiNmJkODJjYWVlNGU0MTBiZWI5MzUxYTk0YTk3YmZhMDY2OGQwOWZhZjUyOGZjNDQwOGQzNzA1MDEyNTI2NTEwM2MyNjg3NjAyYjVmNzU4NmFhZjYyMDAyYTNiMjFlMDE4YmQ5YjZjNmFhYmY0N2YxMjk3YThlOWZhY2I1NDZiNGJlZDZlOTZmODJjZDVhNzA4ODVlNGEyMWQ0MmU3MmEwZGJiOGQ1ZDMyMGQ4ZDY3YTIyNjJjYWUwY2JhMjNkNjI0MjdhNWZiMjVlZGZhMGNmZTExYjkyZTk4YjgyNzY4KV4zMjU2OGYyODIyYTJiOTBhOWNiZTMyYTA1MjgwYTkxMy0wOTllYWIzNC9pbnRlbGxpdm9pZA==

GET Request

GET /coffeehouse/v2/exampleMethod?certificate=M2U0ZmJkZjU5OTNhMWI4ZGI3NjljNzQ5OGMzMDg3OTU3ZGJhNjRhMTYxYjg2ZGUzOWZlNjg3MTg0ODg0YTA5MWU0MGE5NTYxNWQ4NDdmZTBlMDhlOWUyMGI3NTBhNjY4M2FmNTExZTJjNWM5NDRlNjNlOGEwZWI0ZWQxYWEzODU5N2RlZjMyMWE3NTNmY2ViODE4ZWIxYmU3ZDNlNzkxNmE4MGM5OTUwNDg4MmZhYmZmYjEwNGMzOWQ3ZjU4NDNmNmEwOTRmNjJhNmJmYzU0MTQ3Zjg3NGQ4NzRmYjg5OTE1ZjdhODNjN2YwMDg0Nzk1YmVmNDNhMDI5MGFjYmQ4Myg4MzU5ZjgwODAzMzNiMDY1MjQzODE0ZjdjZTZmYzMyOGZiNmJkODJjYWVlNGU0MTBiZWI5MzUxYTk0YTk3YmZhMDY2OGQwOWZhZjUyOGZjNDQwOGQzNzA1MDEyNTI2NTEwM2MyNjg3NjAyYjVmNzU4NmFhZjYyMDAyYTNiMjFlMDE4YmQ5YjZjNmFhYmY0N2YxMjk3YThlOWZhY2I1NDZiNGJlZDZlOTZmODJjZDVhNzA4ODVlNGEyMWQ0MmU3MmEwZGJiOGQ1ZDMyMGQ4ZDY3YTIyNjJjYWUwY2JhMjNkNjI0MjdhNWZiMjVlZGZhMGNmZTExYjkyZTk4YjgyNzY4KV4zMjU2OGYyODIyYTJiOTBhOWNiZTMyYTA1MjgwYTkxMy0wOTllYWIzNC9pbnRlbGxpdm9pZA%3D%3D HTTP/1.1
Host: api.intellivoid.info

POST Request

POST /coffeehouse/v2/exampleMethod HTTP/1.1
Content-Length: 778
Host: api.intellivoid.info
Content-Type: application/x-www-form-urlencoded

certificate=M2U0ZmJkZjU5OTNhMWI4ZGI3NjljNzQ5OGMzMDg3OTU3ZGJhNjRhMTYxYjg2ZGUzOWZlNjg3MTg0ODg0YTA5MWU0MGE5NTYxNWQ4NDdmZTBlMDhlOWUyMGI3NTBhNjY4M2FmNTExZTJjNWM5NDRlNjNlOGEwZWI0ZWQxYWEzODU5N2RlZjMyMWE3NTNmY2ViODE4ZWIxYmU3ZDNlNzkxNmE4MGM5OTUwNDg4MmZhYmZmYjEwNGMzOWQ3ZjU4NDNmNmEwOTRmNjJhNmJmYzU0MTQ3Zjg3NGQ4NzRmYjg5OTE1ZjdhODNjN2YwMDg0Nzk1YmVmNDNhMDI5MGFjYmQ4Myg4MzU5ZjgwODAzMzNiMDY1MjQzODE0ZjdjZTZmYzMyOGZiNmJkODJjYWVlNGU0MTBiZWI5MzUxYTk0YTk3YmZhMDY2OGQwOWZhZjUyOGZjNDQwOGQzNzA1MDEyNTI2NTEwM2MyNjg3NjAyYjVmNzU4NmFhZjYyMDAyYTNiMjFlMDE4YmQ5YjZjNmFhYmY0N2YxMjk3YThlOWZhY2I1NDZiNGJlZDZlOTZmODJjZDVhNzA4ODVlNGEyMWQ0MmU3MmEwZGJiOGQ1ZDMyMGQ4ZDY3YTIyNjJjYWUwY2JhMjNkNjI0MjdhNWZiMjVlZGZhMGNmZTExYjkyZTk4YjgyNzY4KV4zMjU2OGYyODIyYTJiOTBhOWNiZTMyYTA1MjgwYTkxMy0wOTllYWIzNC9pbnRlbGxpdm9pZA%3D%3D

Authentication Errors

If you simply did not provide the correct parameters to authenticate or the authentication method fails you will be receive a JSON response explaining the error, alongside with the appropriate HTTP Error Codes. Below are a examples of possible responses for authentication failures

Authentication Required ❗

This is returned when the server expected an authentication method but none was given

{
    "status": false,
    "code": 401,
    "message": "Authentication is required"
}

Incorrect Authentication ⛔

This is returned when the given authentication data is incorrect/invalid

{
    "status": false,
    "code": 401,
    "message": "Incorrect Authentication"
}

Suspended 🔥

This is returned if your Access Key was suspended (Certificate or API Key)

{
    "status": false,
    "code": 403,
    "message": "Your access key has been suspended"
}

How it works

CoffeeHouse Chat AI 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

Module Name	Access URI	Request Methods	Description
CreateSession	https://api.intellivoid.info/coffeehouse/v2/createSession	`POST` `GET`	Creates a new session with the CoffeeHouse AI and returns the session details
GetSession	https://api.intellivoid.info/coffeehouse/v2/getSession	`POST` `GET`	Retrieves an existing session from the CoffeeHouse AI with the session details
ThinkThought	https://api.intellivoid.info/coffeehouse/v2/thinkThought	`POST` `GET`	Invokes the ThinkThought method of the CoffeeHouse AI using a valid Session ID and user input, this returns the output response aka the AI's conversation response

CreateSession

As explained above, at the beginning of each conversation with each user / 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 module will return a Session Object upon request

Paramerters

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

Example POST request

POST /coffeehouse/v2/createSession HTTP/1.1
Content-Length: ?
Host: api.intellivoid.info
Content-Type: application/x-www-form-urlencoded

api_key=<api_key>
language=en

Example Success Response

{
    "status": true,
    "code": 200,
    "payload": {
        "session_id": "644b58371242916938e2fdfa3bb6e0ea5cba783879f838e0561d1e647dc8b94a",
        "language": "en",
        "available": true,
        "expires": 1561714531
    },
    "ref_code": "<REFERENCE CODE>"
}

Session Object Structure

Name	Type	Description
session_id	`string`	The ID of the session
language	`string`	The language that this session is based on
available	`boolean`	Indicates if this session is still available
expires	`integer`	The Unix Timestamp of when this session expires

Invalid Language Error

This error can be returned if the given language parameter is not a valid ISO 639-1 Languaage code (en, zh, es, etc...)

{
    "status": false,
    "code": 400,
    "message": "The given language code is not a valid ISO 639-1 Language Code",
    "ref_code": "<REFERENCE CODE>"
}

Service Unavailable

This is a server error when a session cannot be created with the AI, if this happens often you should contact support

{
    "status": false,
    "code": 503,
    "message": "Session cannot be created, service unavailable",
    "ref_code": "<REFERENCE CODE>"
}

GetSession

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

Parameters

Parameter Name	Default Value	Required	Description
session_id	None	True	The Session ID given when creating a session with `CreateSession`

Example POST request

POST /coffeehouse/v2/getSession HTTP/1.1
Content-Length: ?
Host: api.intellivoid.info
Content-Type: application/x-www-form-urlencoded

api_key=<api_key>
session_id=644b58371242916938e2fdfa3bb6e0ea5cba783879f838e0561d1e647dc8b94a

Example Success Response

{
    "status": true,
    "code": 200,
    "payload": {
        "session_id": "644b58371242916938e2fdfa3bb6e0ea5cba783879f838e0561d1e647dc8b94a",
        "language": "en",
        "available": true,
        "expires": 1561714531
    },
    "ref_code": "<REFERENCE CODE>"
}

Session Object Structure

Name	Type	Description
session_id	`string`	The ID of the session
language	`string`	The language that this session is based on
available	`boolean`	Indicates if this session is still available
expires	`integer`	The Unix Timestamp of when this session expires

Session not found error

This error can be returned if the given session_id does not exist

{
    "status": false,
    "code": 404,
    "message": "The session ID does not exist",
    "ref_code": "<REFERENCE CODE>"
}

ThinkThought

This module 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 `CreateSession`
input	None	True	The user input (eg; "Hello")

Example POST request

POST /coffeehouse/v2/thinkThought HTTP/1.1
Content-Length: ?
Host: api.intellivoid.info
Content-Type: application/x-www-form-urlencoded

api_key=<api_key>
session_id=644b58371242916938e2fdfa3bb6e0ea5cba783879f838e0561d1e647dc8b94a
input=Hello

Example Success Response

{
    "status": true,
    "code": 200,
    "payload": {
        "output": "Hi! How are you?"
    },
    "ref_code": "<REFERENCE CODE>"
}

Service No Longer Unavailable Error

This is due to an AI Error which resulted in the termination of given session, to resolve this you would need to create a new session

{
    "status": false,
    "code": 503,
    "message": "Session no longer available",
    "ref_code": "<REFERENCE CODE>"
}

Service Expired Error

The session ID used has expired and is no longer available

{
    "status": false,
    "code": 400,
    "message": "Session expired",
    "ref_code": "<REFERENCE CODE>"
}

Service Not Found Error

The given Session ID does not exist

{
    "status": false,
    "code": 404,
    "message": "The session ID does not exist",
    "ref_code": "<REFERENCE CODE>"
}

This documentation was written with ❤️ by netkas

Netkas/coffeehouse_api_v2.md

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

CoffeeHouse API v2 Documentation

Authentication Methods 🔒

API Key 🔐

Certificate 🔏

Multiple Authentication Methods Notice

Authentication Examples 🔍

API Key Example ⭐

Certificate Example ⭐

Authentication Errors

Authentication Required ❗

Incorrect Authentication ⛔

Suspended 🔥

How it works

API Methods

CreateSession

Paramerters

Example POST request

Example Success Response

Session Object Structure

Invalid Language Error

Service Unavailable

GetSession

Parameters

Example POST request

Example Success Response

Session Object Structure

Session not found error

ThinkThought

Parameters

Example POST request

Example Success Response

Service No Longer Unavailable Error

Service Expired Error

Service Not Found Error