Skip to content
master
Switch branches/tags
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 

Alliance for Open ChatBot - Specifications V1.0

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

About

Alliance For Open Chatbot - Open standard format for text and voice communication with conversational agents

Resources

License

Releases

No releases published

Packages

No packages published