{"mock":"https://private-anon-33818b8c66-opendialog.apiary-mock.com","proxy":"https://private-anon-33818b8c66-opendialog.apiary-proxy.com"}
FORMAT: 1A
# Open Dialog Webchat API
This describes the various API methods available as part of the Open Dialog Webchat API.
There are 3 main sections to the API:
+ Webchat Configuration
+ Chat Init
+ Messaging endpoint
## Webchat Config [/webchat-config]
The Webchat config endpoint is used to get all the settings for configuring the webchat widget. Settings can be configured
through the admin backend.
### List Webchat Config [GET]
+ Response 200 (application/json; charset=utf-8)
+ Body
{
"url": "https://od.app",
"teamName": "OpenDialog",
"chatbotName": "OpenDialog",
"chatbotAvatarPath": "/img.png",
"messageDelay": 1000,
"colours": {
"headerBackground": ""
},
"comments": {
"commentsEnabled": true,
"commentsName": "",
"commentsEnabledPathPattern": "^\\\/home\\\/posts",
"commentsEntityName": "comments",
"commentsCreatedFieldName": "created-at",
"commentsTextFieldName": "comment",
"commentsAuthorEntityName": "users",
"commentsAuthorRelationshipName": "author",
"commentsAuthorIdFieldName": "id",
"commentsAuthorNameFieldName": "name",
"commentsSectionEntityName": "posts",
"commentsSectionRelationshipName": "post",
"commentsSectionIdFieldName": "id",
"commentsSectionNameFieldName": "name",
"commentsSectionFilterPathPattern": "home\\\/posts\\\/(\\d*)\\\/?",
"commentsSectionFilterQuery": "post",
"commentsSectionPathPattern": "home\\\/posts\\\/\\d*$",
"commentsAxiosConfig": {
"baseURL": "http:\/\/example.com\/json-api\/v1",
"headers": {
"Authorization": "Bearer ApiTokenValue",
"Content-Type": "application\/vnd.api+json"
}
}
},
"open": true,
"hideOpenCloseIcons": true,
"disableCloseChat": false,
"useAvatars": true,
"webchatHistory": {
"showHistory": true,
"numberOfMessages": 10
}
}
## Chat Init [/chat-init/{user_id}/{number_of_messages}{?ignore}]
The endpoint returns message history for the given user. Optionally, the number of messages parameter can be passed in
to chose how many messages to return.
+ Parameters
+ user_id: `123ABC` (string, required) - The ID of the user to get the message history for.
+ number_of_messages: `20` (number, optional) - How many messages to return in the history
+ Default: `10`
+ ignore: `chat-open` (enum<string>) - A comma separated list of message types to ignore from the list of known message types. Each value should be separated by a comma - eg `chat-open,trigger`
+ members
+ `chat-open`
+ `trigger`
+ `text`
+ `image`
+ `button`
+ `button_response`
+ `url_click`
### Get Message History [GET]
Get the message history for the given user. Returns the number of messages provided from the latest messages sent to and received by the user in question.
Messages are ordered by
+ Response 200 (application/json; charset=utf-8)
[
{
"id": 1,
"created_at": "2019-05-20 12:00:00",
"updated_at": "2019-05-20 12:00:00",
"user_id": "user@example.com",
"author": "them",
"message": "Message copy",
"type": "text",
"data": {
"text": "Message copy",
"disable_text": false,
"internal": false,
"hidetime": false,
"time": "12:00 PM",
"date": "Mon 20 May"
},
"message_id": "6bfcad8c-ec1d-4757-9066-72ac14e3977f",
"user": {
"first_name": "Example",
"last_name": "User",
"email": "user@example.com",
"external_id": "1",
"ip_address": "n\/a",
"country": null,
"browser_language": "en-GB",
"os": "Mac OS",
"browser": "chrome 74.0.3729",
"timezone": "Europe\/London",
"custom": null
},
"microtime": "2019-05-20 12:00:00.000000"
}
]
## Webchat Incoming Messages [/incoming/webchat]
To post a message from a webchat user to the chatbot
### Post a message [POST]
The JSON spec defines the validation of the request data
#### Supported notifiation types
+ `message`: A standard incoming message
#### Supported conent types
These are the currently supported message types for the webchat endpoint
+ `text`: A text only incoming message
+ `button_response`: A message resulting from a button click
+ `chat_open`: Message automatically sent when the chat widget first opens
+ `trigger`: A message sent in response to a trigger being activated
+ `url_click`: A message sent when a user clicks on a link in the chatbot
+ Request (application/json)
+ Attributes
+ `notification`: `message` (string, required) - The type of notification being sent. Only message is supported at the moment
+ `user_id`: `user@example.com` (string, required) - The ID of the user sending the message. This must be a uniquely identifiable string
+ `author`: `user@example.com` (string, required) - Who authored the message. For incoming messages, this should always be the user
+ `message_id`: `a09a8fba-e1f3-45fd-b0cd-028d6153195c` (string, required) - A uniquie ID for the new message
+ `content` (object, required) - The content of the message
+ `content.id`: `a09a8fba-e1f3-45fd-b0cd-028d6153195c` (string, required) - The message ID. Should match the top level value
+ `content.author`: `user@example.com` (string, required) - The author of the message. Should match the top level value
+ `content.type`: `button_response,chat_open,text,trigger,url_click` (string, required) - The type of message the user is sending
+ `content.user_id`: `user@example.com` (string, required) - The user ID. Should match the user if at the top level
+ `content.data` (object, required) - The data associated with the message. Varies depending on the message type
+ `content.data.date`: `Tue 20 May`(string, required) - A date in the format DOW dd mmm
+ `content.data.time`: `12:00 PM`(string, required) - A time in the format HH:MM AM|PM
+ `content.data.callback_id`: `WELCOME` (string, optional) - Required for `button_response`, `trigger` and `chat_open` messages
+ `content.data.value`: `true` (string, optional) - The value assocated with the callback id if there is one
+ `content.data.text`: `Hello` (string, optional) - The text entered by the user. Required for `text` messages
+ `content.user` (object, optional) - The user details passed in are persisted against the user. Each subsequent message will update any existing values
+ `content.user.first_name`: `Example` (string, optional)
+ `content.user.last_name`: `User` (string, optional)
+ `content.user.email`: `user@example.com` (string, optional)
+ `content.user.external_id`: `1` (string, optional) - The ID of the user in a system external to the chatbot. Useful for integrations
+ `content.user.ipAddress`: `127.0.0.1` (string, optional)
+ `content.user.browserLanguage`: `en-GB` (string, optional)
+ `content.user.os`: `Mac OS` (string, optional)
+ `content.user.browser`: `chrome 74.0.3729` (string, optional)
+ `content.user.timezone`: `Europe/London` (string, optional)
+ Body
{
"notification": "message",
"user_id": "user@example.com",
"author": "user@example.com",
"message_id": "a09a8fba-e1f3-45fd-b0cd-028d6153195c",
"content": {
"type": "chat_open",
"data": {
"callback_id": "WELCOME",
"date": "Tue 20 May",
"time": "12:00 PM"
},
"user_id": "user@example.com",
"user": {
"first_name": "Example",
"last_name": "User",
"email": "user@example.com",
"external_id": "1",
"ipAddress": "n/a",
"browserLanguage": "en-GB",
"os": "Mac OS",
"browser": "chrome 74.0.3729",
"timezone": "Europe/London"
},
"id": "a09a8fba-e1f3-45fd-b0cd-028d6153195c",
"author": "user@example.com"
}
}
+ Response 200 (application/json)
+ Body
[
{
"author": "them",
"type": "text",
"data": {
"text": "Response",
"disable_text": false,
"internal": false,
"hidetime": false,
"time": "12:00 PM",
"date": "Mon 20 May"
}
}
]