Alliance For Open Chatbot - Open standard format for text and voice communication with conversational agents
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
images
LICENSE
README.adoc

README.adoc

Alliance for Open ChatBot - DRAFT Specifications

Introduction

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

Current document is the very first DRAFT 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

location

Object

Latitude / longitude and/or address.
Example: {"geoPoint": {"latitude": 39.500859,"longitude": -82.080317},"address": "44 Av de la Republique, Chatillon"}

OPTIONAL

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

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",
  "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",
    "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": "Voilà !",
        "tts": {
            "type": "plainText",
            "payload": "Je vous envoie plus d\'information sur le Strandmon de chez Ikea"
        },
        "infoURL": "https://www.ikea.com/fr/fr/catalog/products/70392542/",
        "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,
        "errorType": "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 may contain the following top-level members:

  • 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 OPTIONAL

❗️
Top level document MUST contain at least response object and status object objects.

response object

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

Field Name Type Description Required

context

Array of context object. [TBD].

Optional item to be used to share any specific bot context.

OPTIONAL

question

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

Text given as the most simple bot answer. This is the only one mandatory text bot answer. It will be used by less rich channels like SMS for instance

REQUIRED

tts

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

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

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 suggestion 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

tts object
Field Name Type Description Required

payload

String

This field is required but only if tts object is used. It is the content of spoken text either describe as simple text or as SSML tags

REQUIRED

type

String

This field is required but only if tts object is used. 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

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

default_action

default_action

Action to be taken when selecting the media object. This is a single button object resource.

OPTIONAL

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 button object

Buttons are associated to each media content. Maximum number of buttons for a media content is 3.

OPTIONAL

default_action object

default_action object have the same properties as a button object.

buttons

buttons key is an array of button object.

button object

button object

Field Name Type Description Required

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

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

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

errorType

String

Human readable error description

REQUIRED

code

Integer

Standard HTTP status code (ex: success=200, etc.)

REQUIRED

meta object

meta object provide bot related information such as icon, name, etc.
Any custom item could by added there.

Table 1. Predifined meta keys
Field Name Type Description Required

copyright

String

Copyright

OPTIONAL

botName

String

Used to name which service/bot is answering the question

OPTIONAL

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

Swagger demo

Test your client with current version of Open ChatBot specification.

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