Introduction

Welcome to Botmock API (early preview). You can use our API to access your Botmock projects and get details like messages payload, boards etc.

Please note that this early preview of our API. In coming months we will be updating our API to provide more robust information. For specific requests please email at support@botmock.com.

API Endpoint

All API requests should be sent to https://app.botmock.com/api

Overview

In Botmock everyone must belong to a team. Each team can have multiple projects under it and each project can be of one of two types:

Conversation Flow
Conversation Mock

Conversation Flows

As the name suggests, conversation flows represent an entire conversation tree where each node can have multiple outgoing connections. Each node is called a message. Messages can be of different types. See message types for more details.

Conversation Mocks

Another way to visualize a single conversation path is to build a conversation mock. This type of project has multiple boards that represent a conversation screen based on the project type. In a mock project, a user can create multiple boards but each board can only have one chain of linked messages. In other words, each message can only have one previous and one next possible message.

Project Types

We have to different kinds of projects in Botmock.

Conversation Flow

Conversation flows are tree like structures which enable to you map out the entire conversations. This is a great way to map out how your user journey would look like within your bot. We recommend you to create the conversation flow around a specific user story. You can always extract specific paths as conversation mocks.

Conversation Mock

Conversation mocks are simply a single conversation layout. They are great if you want to quickly visualize a single conversation path and perhaps create variations for it. In a conversation mock project you are able to create multiple boards. Each board represents a single chat window.

Message Types

Facebook Messenger

Message Type	Key	Description
User Reply	user_reply	Represents an input from a user
Text	text	Represents what your bot says to the user
Image	image	Represents an image template. Can be shown as a user input
Typing	typing_indicator	Shows typing bubble
Button	button	Represents the button template
Quick Replies	quick_replies	Represents the quick replies template
Generic	generic	Represents the generic card template. Turns into carousel if multiple cards are added
List	list	Represents the list template
Location	location	Represents the location template
Webview	webview	Represents the webview template
Receipt	receipt	Represents the receipt template

Amazon Alexa

Message Type	Key	Description
User Reply	user_reply	Represents an input from a user
Text	text	Represents what your bot says to the user

Actions on Google

Message Type	Key	Description
User Reply	user_reply	Represents an input from a user
Text	text	Represents what your bot says to the user
Suggestion Chips	suggestion_chips	Represents the suggestion chips template
Card	card	Represents the card template
Carousel	carousel	Represents the carousel template
List	list	Represents the list template

Authentication

# With shell, you can just pass the correct header with each request
curl "https://app.botmock.com/api/teams"
  -H "Authorization: Bearer YOUR-API-TOKEN"

Botmock uses API tokens to grant access to the API. You can register a new Botmock API token at our account settings. Please note that tokens are only shown once and are as important as your account login details.

Botmock expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer YOUR-API-TOKEN

You must replace YOUR-API-TOKEN with your personal API token.

Teams

Get All Teams

curl "https://app.botmock.com/api/teams"
  -H "Authorization: Bearer YOUR-API-TOKEN"

[
    {
        "id": 38881,
        "name": "First Team",
        "photo": "https://www.gravatar.com/avatar/00f062fb089de61b9a7e8033bc40109a.jpg?s=200&d=identicon",
        "created_at": {
            "date": "2017-01-10 20:45:21.000000",
            "timezone_type": 3,
            "timezone": "UTC"
        }
    },
    {
        "id": 133244,
        "name": "Second team",
        "photo": "https://www.gravatar.com/avatar/1c5a10ff164629b4da3be8ef5f7fe18d.jpg?s=200&d=identicon",
        "created_at": {
            "date": "2017-07-07 19:22:50.000000",
            "timezone_type": 3,
            "timezone": "UTC"
        }
    },
    {
        "id": 183331,
        "name": "Third Team",
        "photo": "https://www.gravatar.com/avatar/7c507a4e30c13b100a7175f494647e83.jpg?s=200&d=identicon",
        "created_at": {
            "date": "2017-08-12 03:38:19.000000",
            "timezone_type": 3,
            "timezone": "UTC"
        }
    }
]

This endpoint retrieves all teams.

Response:

Attribute	Type	Description
id	int	a unique id that represents this team
name	string	name of the team
photo	url	URL representing the image for the team
created_at	object	date this team was created

HTTP Request

GET https://app.botmock.com/api/teams

Get a Specific Team

curl "https://app.botmock.com/api/teams/38881"
  -H "Authorization: Bearer YOUR-API-TOKEN"

{
    "id": 38881,
    "name": "First Team",
    "photo": "https://www.gravatar.com/avatar/00f062fb089de61b9a7e8033bc40109a.jpg?s=200&d=identicon",
    "created_at": {
        "date": "2017-01-10 20:45:21.000000",
        "timezone_type": 3,
        "timezone": "UTC"
    }
}

This endpoint retrieves a specific team.

HTTP Request

GET https://app.botmock.com/teams/<TEAM-ID>

URL Parameters

Parameter	Description
TEAM-ID	The ID of the team to retrieve

Projects

Get All Projects

curl "https://app.botmock.com/api/teams/38881/projects"
  -H "Authorization: Bearer YOUR-API-TOKEN"

[
    {
        "id": "8063ca00-8877-11e7-a797-4f95526152d6",
        "name": "Google Actions Sample Project",
        "created_at": "2017-08-24 02:54:09",
        "updated_at": "2017-11-08 05:21:23",
        "type": "flow",
        "platform": "google-actions"
    },
    {
        "id": "1935e1c0-4638-11e7-a11b-cd5cada6e9c1",
        "name": "Facebook Conversation Flow",
        "created_at": "2017-05-31 19:34:01",
        "updated_at": "2017-11-08 05:19:11",
        "type": "flow",
        "platform": "facebook"
    },
    {
        "id": "06855dd0-3923-11e7-be67-1174531b58f7",
        "name": "Facebook Mock Project",
        "created_at": "2017-05-15 04:00:25",
        "updated_at": "2017-07-19 21:20:57",
        "type": "mock",
        "platform": "facebook"
    }
]

This endpoint retrieves all projects for a team.

HTTP Request

GET https://app.botmock.com/api/teams/<TEAM-ID>/projects

URL Parameters

Parameter	Description
TEAM-ID	The ID of the team to retrieve

Get Specific Project

curl "https://app.botmock.com/api/teams/38881/projects/16f1c520-05c6-11e7-bc31-5554df9b496b"
  -H "Authorization: Bearer YOUR-API-TOKEN"

{
    "id": "16f1c520-05c6-11e7-bc31-5554df9b496b",
    "name": "Kindly",
    "created_at": "2017-03-10 19:16:40",
    "updated_at": "2017-09-15 14:15:59",
    "type": "mock",
    "platform": "facebook"
}

This endpoint retrieves a single project for a team.

HTTP Request

GET https://app.botmock.com/api/teams/<TEAM-ID>/projects/<PROJECT-ID>

URL Parameters

Parameter	Description
TEAM-ID	The ID of the team to retrieve
PROJECT-ID	The ID of the project you want to retrieve

Get Project Boards

curl "https://app.botmock.com/api/teams/38881/projects/16f1c520-05c6-11e7-bc31-5554df9b496b/boards"
  -H "Authorization: Bearer YOUR-API-TOKEN"

[
    {
        "id": "16f212e0-05c6-11e7-a955-8d23fe368669",
        "created_at": "2017-03-10 19:16:40",
        "updated_at": "2017-05-25 20:28:13",
        "name": "Your Charity",
        "is_private": false,
        "avatar": "",
        "project_id": "16f1c520-05c6-11e7-bc31-5554df9b496b"
    },
    {
        "id": "5b810a20-3505-11e7-a0b2-2bc799a132cf",
        "created_at": "2017-05-09 22:17:58",
        "updated_at": "2017-05-09 22:17:58",
        "name": "Untitled",
        "is_private": false,
        "avatar": "",
        "project_id": "16f1c520-05c6-11e7-bc31-5554df9b496b"
    },
    {
        "id": "618bdc40-9a20-11e7-b4a3-95d634181268",
        "created_at": "2017-09-15 14:15:52",
        "updated_at": "2017-09-15 14:15:59",
        "name": "Your Charity",
        "is_private": false,
        "avatar": "",
        "project_id": "16f1c520-05c6-11e7-bc31-5554df9b496b"
    }
]

This endpoint retrieves all boards for a single project. Boards are similar to canvas, as they are what contains all your messages. For projects for flow type, there is only 1 board at any given time. For mock projects, you can have multiple boards.

HTTP Request

GET https://app.botmock.com/api/teams/<TEAM-ID>/projects/<PROJECT-ID>/boards

URL Parameters

Parameter	Description
TEAM-ID	The ID of the team to retrieve
PROJECT-ID	The ID of the project you want to retrieve

Get Specific Board

curl "https://app.botmock.com/api/teams/38881/projects/16f1c520-05c6-11e7-bc31-5554df9b496b/boards/16f212e0-05c6-11e7-a955-8d23fe368669"
  -H "Authorization: Bearer YOUR-API-TOKEN"

{
    "board": {
        "root_messages": [
            "6af54577-593a-436a-866f-11be95c55b64"
        ],
        "messages": [
            {
                "message_id": "c13bf3c7-fd33-4f82-af21-f927d0d21988",
                "message_type": "text",
                "next_message_ids": [
                    {
                        "message_id": "881a52a8-69f9-4706-8c6a-efdc98d50805",
                        "action": {
                            "type": "custom",
                            "title": "Click to edit",
                            "payload": "CLICK_TO_EDIT"
                        },
                        "intent": "",
                        "conditional": false
                    }
                ],
                "previous_message_ids": [],
                "is_root": true,
                "payload": {}
            },
            {
                "message_id": "881a52a8-69f9-4706-8c6a-efdc98d50805",
                "message_type": "text",
                "next_message_ids": [
                    {
                        "message_id": "f7064ff1-c729-4e94-9342-b43cbe154c69",
                        "action": {
                            "type": "postback",
                            "title": "Create",
                            "payload": "CREATE"
                        },
                        "intent": {
                            "value": "57c694c0-1620-11e9-a7a9-c737e119ebc2",
                            "label": "CreateObject"
                        },
                        "conditional": {
                            "id": "g-b3a93da2-a413-4cbf-b57a-a8e015294dde",
                            "rules": [
                                {
                                    "id": "r-62b03208-11bc-4fed-85f3-1d5844dd1d4c",
                                    "field": "aed6d0a0-161f-11e9-a3c8-71dcddbc03ea",
                                    "value": "2",
                                    "operator": "="
                                }
                            ],
                            "combinator": "and"
                        }
                    },
                    {
                        "message_id": "026af6f5-d651-4af2-96ba-431c8d8c9cd3",
                        "action": {
                            "type": "postback",
                            "title": "list",
                            "payload": "LIST"
                        },
                        "intent": {
                            "value": "2cfcf330-1620-11e9-8b75-2b956cac7c2c",
                            "label": "LIstObjects"
                        },
                        "conditional": false
                    }
                ],
                "previous_message_ids": [
                    {
                        "message_id": "c13bf3c7-fd33-4f82-af21-f927d0d21988",
                        "action": "*"
                    },
                    {
                        "message_id": "026af6f5-d651-4af2-96ba-431c8d8c9cd3",
                        "action": "*"
                    },
                    {
                        "message_id": "efb97b02-ff88-4309-a19a-dda71db763d3",
                        "action": "*"
                    }
                ],
                "is_root": false,
                "payload": {
                    "nodeName": "Ask",
                    "context": [],
                    "text": "What would you like me to do? List object or create object?",
                    "audio_file": ""
                }
            },
            ...
        ]
    },
    "created_at": {
        "date": "2017-09-20 23:47:47.000000",
        "timezone_type": 3,
        "timezone": "UTC"
    },
    "updated_at": {
        "date": "2017-09-20 23:47:47.000000",
        "timezone_type": 3,
        "timezone": "UTC"
    }
}

This endpoint retrieves a specific board that you requests. Each board contains a root_messages property that is an array of message ids that act as a starting point (i.e. they have no connections coming into them) and a messages property that is an Array of messages that have the following attributes:

Attribute	Type	Description
message_id	string	a unique id that represents this message
message_type	string	type of message (see Message Types for details)
next_message_ids	array	an array representing a list of possible messages that you can go to from here
previous_message_ids	array	an array representing a list of possible messages that lead to this message
is_root	boolean	a boolean is this a root message
payload	object	a data structure that represents the JSON representation of what the message looks like. NOTE this might not be a complete payload that you can send to the platform.

HTTP Request

GET https://app.botmock.com/api/teams/<TEAM-ID>/projects/<PROJECT-ID>/boards/<BOARD-ID>

URL Parameters

Parameter	Description
TEAM-ID	The ID of the team to retrieve
PROJECT-ID	The ID of the project you want to retrieve
BOARD-ID	The ID of the specific board you want to retrieve

Get Intents For Project

curl "https://app.botmock.com/api/teams/38881/projects/16f1c520-05c6-11e7-bc31-5554df9b496b/intents"
  -H "Authorization: Bearer YOUR-API-TOKEN"

[
    {
        "id": "2cc1c820-256e-11e9-bdec-d7703deefc80",
        "name": "SelectProduct",
        "utterances": [
            {
                "text": "%ProductName%",
                "variables": [
                    {
                        "id": "9450ca70-2560-11e9-af2c-015ec1f36ff1",
                        "name": "%ProductName%",
                        "type": "text",
                        "entity": "85cdacd0-2560-11e9-8622-f736038e9f6f",
                        "default_value": "pizza",
                        "start_index": 0
                    }
                ]
            },
            {
                "text": "wings",
                "variables": []
            },
            {
                "text": "I would like a %ProductName%",
                "variables": [
                    {
                        "id": "9450ca70-2560-11e9-af2c-015ec1f36ff1",
                        "name": "%ProductName%",
                        "type": "text",
                        "entity": "85cdacd0-2560-11e9-8622-f736038e9f6f",
                        "default_value": "pizza",
                        "start_index": 15
                    }
                ]
            },
            {
                "text": "I would like some %ProductName%",
                "variables": [
                    {
                        "id": "9450ca70-2560-11e9-af2c-015ec1f36ff1",
                        "name": "%ProductName%",
                        "type": "text",
                        "entity": "85cdacd0-2560-11e9-8622-f736038e9f6f",
                        "default_value": "pizza",
                        "start_index": 18
                    }
                ]
            },
            {
                "text": "Can I get a %ProductName% please",
                "variables": [
                    {
                        "id": "9450ca70-2560-11e9-af2c-015ec1f36ff1",
                        "name": "%ProductName%",
                        "type": "text",
                        "entity": "85cdacd0-2560-11e9-8622-f736038e9f6f",
                        "default_value": "pizza",
                        "start_index": 12
                    }
                ]
            },
            {
                "text": "pizza",
                "variables": []
            }
        ],
        "created_at": {
            "date": "2019-01-31 15:37:53.000000",
            "timezone_type": 3,
            "timezone": "UTC"
        },
        "updated_at": {
            "date": "2019-01-31 17:40:20.000000",
            "timezone_type": 3,
            "timezone": "UTC"
        }
    },
]

This endpoint retrieves all intents for a given project. Each intent has the following properties:

Attribute	Type	Description
id	string	a unique id that represents this intent
name	string	Name for this intent
utterances	array	an array representing a of utterances. Each utterance has a "text" (aka training phrase) and a list of variables (aka context variables or slots) used in that utterance.
created_at	object	an object representing the timestamp of when this intent was created
updated_at	object	an object representing the timestamp of when this intent was updated

HTTP Request

GET https://app.botmock.com/api/teams/<TEAM-ID>/projects/<PROJECT-ID>/intents

URL Parameters

Parameter	Description
TEAM-ID	The ID of the team to retrieve
PROJECT-ID	The ID of the project you want to retrieve

Get Entities For Project

curl "https://app.botmock.com/api/teams/38881/projects/16f1c520-05c6-11e7-bc31-5554df9b496b/entities"
  -H "Authorization: Bearer YOUR-API-TOKEN"

[
    {
        "id": "85cdacd0-2560-11e9-8622-f736038e9f6f",
        "name": "product",
        "data": [
            {
                "value": "pizza",
                "synonyms": [
                    "meat lovers",
                    " veggie",
                    " greek"
                ]
            },
            {
                "value": "wings",
                "synonyms": [
                    "chicken wings",
                    " spicy wings",
                    " awesome wings"
                ]
            }
        ],
        "data_count": 2,
        "created_at": {
            "date": "2019-01-31 14:00:10.000000",
            "timezone_type": 3,
            "timezone": "UTC"
        },
        "updated_at": {
            "date": "2019-01-31 14:00:10.000000",
            "timezone_type": 3,
            "timezone": "UTC"
        }
    }
]

This endpoint retrieves all entities for a given project. Each entity has the following properties:

Attribute	Type	Description
id	string	a unique id that represents this entity
name	string	Name for this entity
data	array	an array representing all the values associated with this entity. Each value has an associated array of synonyms as well.
data_count	int	a count for how many values are part of this entity
created_at	object	an object representing the timestamp of when this entity was created
updated_at	object	an object representing the timestamp of when this entity was updated

HTTP Request

GET https://app.botmock.com/api/teams/<TEAM-ID>/projects/<PROJECT-ID>/entities

URL Parameters

Parameter	Description
TEAM-ID	The ID of the team to retrieve
PROJECT-ID	The ID of the project you want to retrieve

Get Variables For Project

curl "https://app.botmock.com/api/teams/38881/projects/16f1c520-05c6-11e7-bc31-5554df9b496b/variables"
  -H "Authorization: Bearer YOUR-API-TOKEN"

[
    {
        "id": "9450ca70-2560-11e9-af2c-015ec1f36ff1",
        "name": "ProductName",
        "default_value": "pizza",
        "type": "text",
        "entity": "85cdacd0-2560-11e9-8622-f736038e9f6f",
        "created_at": {
            "date": "2019-01-31 14:00:34.000000",
            "timezone_type": 3,
            "timezone": "UTC"
        },
        "updated_at": {
            "date": "2019-01-31 14:00:34.000000",
            "timezone_type": 3,
            "timezone": "UTC"
        }
    },
]

This endpoint retrieves all entities for a given project. Each entity has the following properties:

Attribute	Type	Description
id	string	a unique id that represents this variable
name	string	Name for this variable
default_value	string	the default value of this variable
type	string	type of this variable - Can only be: text, int, boolean or list
entity	string	a unique id of the entity associated with this variable or a text representing default entities provided by Botmock
created_at	object	an object representing the timestamp of when this variable was created
updated_at	object	an object representing the timestamp of when this variable was updated

HTTP Request

GET https://app.botmock.com/api/teams/<TEAM-ID>/projects/<PROJECT-ID>/variables

URL Parameters

Parameter	Description
TEAM-ID	The ID of the team to retrieve
PROJECT-ID	The ID of the project you want to retrieve

Wrappers

We're actively working on creating wrappers that will make interacting with our API a breeze.

Botmock-JS (Javascript)

Exporting to ...

We have some open-source extensions that can help you export to specific platforms like DialogFlow, Watson etc.

Errors

This error section is stored in a separate file in includes/_errors.md. Slate allows you to optionally separate out your docs into many files...just save them to the includes folder and add them to the top of your index.md's frontmatter. Files are included in the order listed.

The Kittn API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- The kitten requested is hidden for administrators only.
404	Not Found -- The specified kitten could not be found.
405	Method Not Allowed -- You tried to access a kitten with an invalid method.
406	Not Acceptable -- You requested a format that isn't json.
410	Gone -- The kitten requested has been removed from our servers.
418	I'm a teapot.
429	Too Many Requests -- You're requesting too many kittens! Slow down!
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.