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
To authorize, use this code:
# 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"
Make sure to replace
YOUR-API-TOKENwith 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
Teams
Get All Teams
To get all teams, use this code:
curl "https://app.botmock.com/api/teams"
-H "Authorization: Bearer YOUR-API-TOKEN"
The above command returns JSON structured like this:
[
{
"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"
The above command returns JSON structured like this:
{
"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"
The above command returns JSON structured like this:
[
{
"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"
The above command returns JSON structured like this:
{
"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"
The above command returns JSON structured like this:
[
{
"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"
The above command returns JSON structured like this:
{
"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"
The above command returns JSON structured like this:
[
{
"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"
The above command returns JSON structured like this:
[
{
"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"
The above command returns JSON structured like this:
[
{
"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.
Open-source Export Libs
We have some open-source export libraries that can help you export to specific platforms like DialogFlow, Watson etc.
- DialogFlow (code)
- IBM Watson (code)
- RASA (code)
- Microsoft Bot Framework (code)
- Microsoft LUIS (code)
- Jovo (code)
- Alexa Skills Kit (code)
- Amazon Lex (code)
- BotPress (Coming Soon)
- RiveScript (Coming Soon)
If you have a specific platform that is not listed above, please reach out to us at help@botmock.com
Errors
The Botmock 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 -- Most likely you are trying to access a resource which you are not authorized for. |
| 404 | Not Found -- The specified resource 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 resource requested has been removed from our servers. |
| 429 | Too Many Requests -- You're requesting too many resources! 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. |