Alliance for Open ChatBot - Specifications V1.0

This specification is the official v1.0 release of OpenChatBot format.

Table of Contents

• Introduction
• GET query
  • Example of GET query to Open ChatBot compatible service
  • Fields Description
• POST query
  • Example of POST query to Open ChatBot compatible service
• GET and POST responses
  • Example of response
  • Fields Description
• Swagger demo
• Known implementations
• Other reading

Introduction

Open ChatBot is an Alliance For Open ChatBot initiative to define a common standard specification for communication with and between any conversational agent (text and/or voice).

Current document is the official release (v1.0) of this open standard specification.

GET query

Example of GET query to Open ChatBot compatible service

CURL

curl -X GET "https://bot-domain/api/v0.1/ask?userid=1234567890&lang=fr&query=je%20cherche%20la%20doc%20du%20fauteuil%20strandmon%20Ikea&location=Paris"

Fields Description

Field Name	Type	Description	Required
userId	String	String that describe user ID. There is no constraint on length as this ID should be compliant with any bots and services ID. From Facebook type of ID through web cookie token passing by mobile number in international format, or even concatenation of all of those type of ID.	REQUIRED.
query	String	URL encoded query to chatbot.	REQUIRED
lang	String	Language tag, e.g., en, es etc.	OPTIONAL
echo	Object	Some information from previous bot answer to give back without any process.	OPTIONAL
location	Object	Latitude / longitude and/or address. Example: {"geoPoint": {"latitude": 39.500859,"longitude": -82.080317},"address": "44 Av de la Republique, Chatillon"}	OPTIONAL

POST query

Example of POST query to Open ChatBot compatible service

CURL

curl -X "POST" "https://bot-domain/api/v0.1" \
     -H 'authorization: CLIENT_ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d $'{
  "query": "je cherche la doc du fauteuil strandmon Ikea",
  "userId": "1234567890",
  "echo": {
      "session": "XXXXXXXX"
  },
  "location": {
    "address": "44 Av de la Republique, Chatillon",
    "geoPoint": {
      "longitude": "-82.080317",
      "latitude": "39.500859"
    }
  }
}'

HTTP

POST /api/v0.1 HTTP/1.1
authorization: CLIENT_ACCESS_TOKEN
Content-Type: application/json
Host: bot-domain

POST body:
{
    "query": "je cherche la doc du fauteuil strandmon Ikea",
    "userId": "1234567890",
    "lang": "fr",
    "echo": {
        "session": "XXXXXXXX"
    },
    "location": {
        "geoPoint": {
            "latitude":"39.500859",
            "longitude":"-82.080317"
        },
        "address": "44 Av de la Republique, Chatillon"
    }
}

GET and POST responses

Both GET and POST methods return the same JSON response.

Example of response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "response": {
        "query": "je cherche la doc du fauteuil strandmon Ikea",
        "userId": "1234567890",
        "timestamp": 1485358532524,
        "text": "Vous trouverez plus d'infos là: https://www.ikea.com/fr/fr/catalog/products/70392542/",
        "infoURL": "https://www.ikea.com/fr/fr/catalog/products/70392542/",
        "echo": {
            "session": "XXXXXXXX"
        },
        "score": {
            "value": 0.75
        },
        "channel": {
            "markup": {
                "type": "html",
                "payload": "<ul><li>bullet 1</li><li>bullet 2</li></ul>"
            },
            "messaging": {
                "type": "plainText",
                "payload": "Je vous envoie plus d'information sur le Strandmon de chez Ikea"
            },
            "sms": {
                "type": "plainText",
                "payload": "Je vous envoie plus d'information sur le Strandmon de chez Ikea"
            },
            "tts": {
                "type": "plainText",
                "payload": "Je vous envoie plus d'information sur le Strandmon de chez Ikea"
            }
        },
        "media": [{
            "shortDesc": "Fauteuil enfant, Vissle gris",
            "longDesc": "Quand ils peuvent imiter les adultes, les enfants se sentent spéciaux et importants. C'est pourquoi nous avons créé une version miniature du fauteuil STRANDMON, l'un de nos produits favoris.",
            "title": "STRANDMON",
            "mimeType": "image/jpeg",
            "src": "https://www.ikea.com/fr/fr/images/products/strandmon-fauteuil-enfant-gris__0574584_PE668407_S4.JPG",
            "default_action": {
                "type": "web_url",
                "label": "Go",
                "payload": "https://www.ikea.com/fr/fr/catalog/products/70392542/"
            },
            "buttons": [{
                    "type": "web_url",
                    "label": "Acheter en ligne",
                    "payload": "https://serv-api.target2sell.com/1.1/R/cookie/OFCBMN5RRHSG5L/1200/OFCBMN5RRHSG5L-1200-5/20343224/1/viewTogether-%7BtypeOfContextList%3A%5B%22current%22%2C%22view%22%5D%7D/f082e51f-561d-47f7-c0cb-13735e58bfc1"
                },
                {
                    "type": "natural_language",
                    "label": "Tous les fauteuils",
                    "payload": "Je veux voir tous les fauteuils du magazin Ikea le plus proche"
                },
                {
                    "type": "custom",
                    "client": "specific_custom_client_name",
                    "label": "Ajouter au panier",
                    "payload": "DEVELOPER_DEFINED_PAYLOAD"
                }
            ]
        }],
        "suggestions": [{
                "type": "web_url",
                "label": "Les magasins Ikea",
                "payload": "https://www.ikea.com/ms/fr_FR/ikny_splash.html"
            },
            {
                "type": "natural_language",
                "label": "Politique de confidentialité",
                "payload": "Je voudrais voir la politique de confidentialité de la société Ikea en France"
            }
        ],
        "context": []
    },
    "status": {
        "code": 200,
        "message": "success"
    },
    "meta": {
        "botName": "Ikea",
        "botIcon": "https://is4-ssl.mzstatic.com/image/thumb/Purple118/v4/4a/23/cb/4a23cb34-1039-af8d-32f0-c3e3bf313da3/source/256x256bb.jpg",
        "version": "0.1",
        "copyright": "Copyright 2018 Ikea.",
        "authors": [
            "Jane Doe",
            "John Doe"
        ]
    }
}

Fields Description

❗	Top level document MUST contain response object, status object objects and meta objectzz.

• response object: that define document’s “primary content”. This top level member is REQUIRED

• status object: This object provide information on request success or failure. This top level member is REQUIRED

• meta object: a meta object that contains non-standard meta-information. This top level member is REQUIRED

response object

This object define a single resource object or an empty object ({}).

Field Name	Type	Description	Required
query	String	Natural language query	OPTIONAL
userId	String	User ID given with the query	REQUIRED
timestamp	String	Date and time of the request in UTC timezone using Unix Timestamp	REQUIRED
text	String	Most simple universal text answer	REQUIRED
infoURL	String	This field is an URL that could provide more info on the particular response. This field is optional. It may be used for instance to provide with additional rich response through an URL for channels that does not support rich contents (like SMS)	OPTIONAL
echo	echo object	Some information from previous bot answer to give back without any process.	OPTIONAL
score	score object	Score value given by answering bot on response confidence.	OPTIONAL
channel	channel object	Give different answers by targeted channel	OPTIONAL
media	Array of media object	A media object is made of an image or a video, a title, a long or a short description and zero or up to 3 buttons	OPTIONAL
suggestions	Array of suggestion object	A suggestions object is a single button action that is usually presented within a horizontally carousel bellow bot response. After selection of one of the button, all other buttons from carousel should be removed from client presentation	OPTIONAL
context	Array of context object. [TBD].	Optional item to be used to share any specific bot context.	OPTIONAL

echo object

score object provide with information on current conversaion like session info.

Field Name	Type	Description	Required
session	String	A session value as string.	OPTIONAL

score object

score object provide with information on bot confidence for response.

Field Name	Type	Description	Required
value	Float	Float value for actual bot score confidence based on min/max values.	OPTIONAL

channel object

This object define a single resource object. As OpenChatBot format is out of the box multi-channel, all listed keys are required keys.

Field Name	Type	Description	Required
markup	channel-markup object	WARNING: Unsing key might be very risky while allowing HTML entry is a possible security thread for host reading HTML content including javascript injection (see Wikipedia article on this topic).	OPTIONAL
messenging	channel-messenging object	This field will provide with the most simple text response type to messaging clients possibly different than the form of response made for SMS.	OPTIONAL
sms	channel-sms object	This field is required and will provide a response dedicated to SMS channel (that might not support rich encoding for instance).	OPTIONAL
tts	channel-tts object	This object describe what should be used as answer for a voice channel. Either using a standard text different than the display text message or either using a specific Speech Synthesis Markup Language (SSML) format as described by W3C. This object is not mandatory, but if this field is not present, a voice compatible assistant or bot will use the default previous text string to be spoken.	OPTIONAL

channel-markup object

Field Name	Type	Description	Required
type	String	So far the only possible type is HTML.	REQUIRED
playload	String	html content to allow formated rendering. BE AWARE OF SECURITY WARNING.	REQUIRED

channel-messenging object

Field Name	Type	Description	Required
type	String	The type could so far only be plainText.	REQUIRED
playload	String	It is the content of a simple text response.	REQUIRED

channel-sms object

Field Name	Type	Description	Required
type	String	This field is required. The type could be either plainText.	REQUIRED
playload	String	It is the content of sms text either describe as simple text	REQUIRED

channel-tts object

Field Name	Type	Description	Required
type	String	The type could be either plainText or ssml. If type is plainText clients will use the string given in payload to be spoken. If type is ssml clients will use SSML specification for rich voice rendering	REQUIRED
payload	String	It is the content of spoken text either describe as simple text or as SSML tags	REQUIRED

media object

A media object is made of an image or a video, a title, a long or a short description and zero or up to 3 buttons.
This object is usually used as an elementary part of a media object carousel.

Field Name	Type	Description	Required
shortDesc	String	Describe media content with a short text (mostly like a sub-title) [Number max of characters to be suggested]	OPTIONAL
longDesc	String	Describe media content with a long description [Number max of characters to be suggested]	OPTIONAL
title	String	Describe the content with couple or words max [Number max of characters to be suggested]	OPTIONAL
mimeType	String	Describe type of media (ex: image/jpeg, video/mp4, etc.). This might be useful for clients to anticipate what type of media will be displayed (in particular if it’s different than a simple image)	OPTIONAL
src	String	Provide with the URL for a media content (image for instance)	OPTIONAL
buttons	Array of buttons object	Buttons are associated to each media content. Maximum number of buttons for a media content is 3.	OPTIONAL
default_action	default action	Action to be taken when selecting the media object. This is a single button object resource.	OPTIONAL

default_action object

default_action object have the same properties as a button object.

buttons

buttons object is an array of button object.

button object

button object

Field Name	Type	Description	Required
type	String	Type of action to be done when clicked on media object area, in a media button or a suggestions button. Button type could be either web_url, natural_language or custom. When button type is custom a client key must be set in addition to label key and payload keys.	REQUIRED
label	String	Label to be displayed for the button (this does not make much sense when in default_action situation unless label is shown on overlay to a media resource for instance). Most of the time this might need to be shorter than the full sentence or long URLs	REQUIRED
client	String	This key should only exist if type is custom. It should provide a custom identification of clients that will support a custom payload (ex: client key could be "app-xxx" to perform a specific action that only app-xxx can perform).	OPTIONAL
payload	String	Text to be use for a new bot query if type is natural_language. URL to be launched if type is web_url. Custom payload if type is custom.	REQUIRED

suggestions

suggestions key is an array of button object.
Suggestions buttons are usually displayed as a collection of labeled buttons with horizontal scroll.

❗	This type of buttons are contextual and all buttons should disappear if one of them are clicked or imediatly after any action.

status object

status object provide with information on request success or failure.

Field Name	Type	Description	Required
code	Integer	Standard HTTP status code (ex: success=200, etc.)	REQUIRED
message	String	Human readable status code description	REQUIRED

meta object

meta object provide bot related information such as icon, name, version, copyright, authors and bot score.
Any custom item could by added there.

Table 1. Predifined meta keys

Field Name	Type	Description	Required
botName	String	Used to name which service/bot is answering the question. This name should be unique within a specific metabot instance. This name will have to be registred and approved by OpenChatBot Alliance as part of the certification process (official "Compatible OpenChatBot" stamp).	REQUIRED
botIcon	String	Used to reference bot icon (image) url. No strong constraints given so far, but current recommendation is to keep it small (ex: 300x300 pixels) with alpha.	OPTIONAL
version	String	Describing version number format with major.minor as per latest OpenAPI specifications.	OPTIONAL
copyright	String	Copyright	OPTIONAL

Swagger demo

Test your client with current version of Open ChatBot specification.

You can test current draft API specification from Swagger here. Use "@debug suggestions" in the chat box for a full set of keys within response.

Known implementations

There are a number of open source packages which you may leverage with this standard:

You can interact in python with standard compliant bots using the open-chatbot-py-client package.

You can easily add a Web Chat widget to your web page, connected to a compliant bot, using the openchatbot-webclient package.

Other reading

We recommend also checking the bot registration, per domain, at https://openchatbot.io/domainbots