API Reference

This API is in beta

This API is in beta and is subject to change. Please keep this in mind when using it in production and let us know if you have any feedback.

Introduction

The Botpress API is a RESTful set of HTTP endpoints that allow you to create, deploy, and run chatbots on the Botpress Cloud.

It can be used to create and manage bots, handle conversations and messages, as well as to manage their content, users, and configuration.

The API endpoints will expect the Content-type: application/json HTTP header to be present in the request and the request body (if any) to be in JSON format, and will send back the same header in the response and return a JSON response body as well.

Authentication

To authenticate with the Botpress Cloud API, you'll need to use one of the methods below to obtain an access token.

These tokens can be used as a Bearer token to call all the endpoints of the API, by passing the following HTTP header to the API endpoints:

Authorization: Bearer {ACCESS_TOKEN}

Method 1: Identity Token

Personal Access Token (PAT): Can be generated in the Profile Settings section of your Botpress Cloud account.
Bot Token: This will be provided to the bot (once deployed) in the BP_TOKEN environment variable.
Integration Token: This will be provided to the integration (once deployed) in the BP_TOKEN environment variable.

Method 2: OAuth2 Token

Obtain a token from our OAuth2 server by passing the API key and secret for the bot, integration, or user you want to authenticate as to the following endpoint:

https://api.botpress.cloud/v1/authenticate

This endpoint will expect a request with the Content-type: application/json HTTP header and a request body containing the API key (clientKey) and secret (clientSecret):

1
{
2
  "clientKey": "{API_KEY}",
3
  "clientSecret": "{API_SECRET}"
4
}

The endpoint will return the following response:

1
{
2
  "token": "{ACCESS_TOKEN}",
3
  "expiresIn": {EXPIRATION_TIMESTAMP_IN_MILLISECONDS_SINCE_JANUARY_1_1970}
4
}

Please note that the access granted by these OAuth2 tokens will be scoped to the bot, integration, or user you are authenticating as.

Pagination

The "List" endpoints of our API will return paginated results based on the creation date of the resource, with a default limit of 20 results per page.

When the number of results exceeds the limit, the response body will include a meta.nextToken property that can be passed as a query string parameter (e.g. endpoint?nextToken={nextToken}) to retrieve the next page of results.

If there are no more results, the endpoint will not provide a nextToken value.

Example:

Call the /v1/chat/conversations endpoint to obtain the first page of results:

1
{
2
  "conversations": [
3
    (...)
4
  ],
5
  "meta": {
6
    "nextToken": "wwNgQn6tWNR/IHhKGHv/sg9zcIAGsxOk0TfmM+DdmcWkBZrXYjVvcfSZIZSs4ppCr/g="
7
  }
8
}

Call the endpoint again but now passing the nextToken as a query string parameter, making sure the value is URL-encoded:

/v1/chat/conversations?nextToken=wwNgQn6tWNR%2FIHhKGHv%2Fsg9zcIAGsxOk0TfmM%2BDdmcWkBZrXYjVvcfSZIZSs4ppCr%2Fg%3D

Repeat until the response body doesn't provide a nextToken value anymore:

1
{
2
  "conversations": [
3
    (...)
4
  ],
5
  "meta": {}
6
}

Errors

If an error occurs when calling an API endpoint, the response will return the appropriate HTTP status code as indicated below and the response body will be one of the following JSON objects indicating the nature of the error:

Unknown

HTTP status code: 500

1
{
2
  "type": "Unknown",
3
  "description": "An unknown error occurred",
4
  "status": 500
5
}

Internal

HTTP status code: 500

1
{
2
  "type": "Internal",
3
  "description": "An internal error occurred",
4
  "status": 500
5
}

Forbidden

HTTP status code: 403

1
{
2
  "type": "Forbidden",
3
  "description": "The requested action can't be peform by this resource.",
4
  "status": 403
5
}

InvalidPayload

HTTP status code: 400

1
{
2
  "type": "InvalidPayload",
3
  "description": "The request payload isn't invalid.",
4
  "status": 400
5
}

MethodNotFound

HTTP status code: 405

1
{
2
  "type": "MethodNotFound",
3
  "description": "The requested method does not exist.",
4
  "status": 405
5
}

ResourceNotFound

HTTP status code: 404

1
{
2
  "type": "ResourceNotFound",
3
  "description": "The requested resource does not exist.",
4
  "status": 404
5
}

InvalidJsonSchema

HTTP status code: 400

1
{
2
  "type": "InvalidJsonSchema",
3
  "description": "The provided JSON schema is invalid.",
4
  "status": 400
5
}

InvalidDataFormat

HTTP status code: 400

1
{
2
  "type": "InvalidDataFormat",
3
  "description": "The provided data doesn't respect the provided JSON schema.",
4
  "status": 400
5
}

InvalidIdentifier

HTTP status code: 400

1
{
2
  "type": "InvalidIdentifier",
3
  "description": "The provided identifier is not valid. An identifier must start with a lowercase letter, be between 2 and 100 characters long and use only alphanumeric characters.",
4
  "status": 400
5
}

RelationConflict

HTTP status code: 409

1
{
2
  "type": "RelationConflict",
3
  "description": "The resource is not related with another resource. This is usually caused when providing two resources that aren't linked together.",
4
  "status": 409
5
}

ReferenceNotFound

HTTP status code: 400

1
{
2
  "type": "ReferenceNotFound",
3
  "description": "The provided resource reference is missing. This is usually caused when providing an invalid id inside the payload of a request.",
4
  "status": 400
5
}

InvalidQuery

HTTP status code: 400

1
{
2
  "type": "InvalidQuery",
3
  "description": "The provided query is invalid. This is usually caused when providing an invalid parameter for querying a resource.",
4
  "status": 400
5
}

User

Endpoints

POST

/v1/chat/users

GET

/v1/chat/users/{id}

GET

/v1/chat/users

POST

/v1/chat/users/get-or-create

PUT

/v1/chat/users/{id}

DELETE

/v1/chat/users/{id}

The User object

Attributes

id

string

Id of the User

createdAt

string

Creation date of the User in the ISO 8601 format

updatedAt

string

Updating date of the User in the ISO 8601 format

tags

object

Set of Tags that you can attach to a User. The set of Tags available on a User is restricted by the list of Tags defined previously by the Bot. Individual keys can be unset by posting an empty value to them.

Create User

Creates a new User. When creating a new User, the required tags must be provided. See the specific integration for more details.

Body

tags

object

Tags for the User

Response

Returns a User object if creation succeeds. Returns an error otherwise

user

object

The user object represents someone interacting with the bot within a specific integration. The same person interacting with a bot in slack and messenger will be represented with two different users.

Show child parameters

Get User

Retrieves the User object for a valid identifier.

Path

id

string

User ID

Response

Returns a User object if a valid identifier was provided. Returns an error otherwise

user

object

The user object represents someone interacting with the bot within a specific integration. The same person interacting with a bot in slack and messenger will be represented with two different users.

Show child parameters

List Users

Retrieves a list of User previously created. The users are returned in sorted order, with the most recent appearing first. The list can be filtered using Tags.

Query

nextToken

optional string

Provide the meta.nextToken value provided in the last API response to retrieve the next page of results

conversationId

optional string

Filter by conversation id. This will return all users that have participated in the conversation.

tags

optional object

Filter by tags

Response

Returns a list of User objects

users

array of object

Show child parameters

meta

object

Show child parameters

Get Or Create User

Retrieves the User object for a valid identifier. If the user does not exist, it will be created.

Body

tags

object

Tags for the User

Response

Returns a User object if a valid identifier was provided. Returns an error otherwise

user

object

The user object represents someone interacting with the bot within a specific integration. The same person interacting with a bot in slack and messenger will be represented with two different users.

Show child parameters

Update User

Update a User object by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Path

id

string

User ID

Body

tags

object

Tags for the User

Response

Returns an updated User object if a valid identifier was provided. Returns an error otherwise

user

object

The user object represents someone interacting with the bot within a specific integration. The same person interacting with a bot in slack and messenger will be represented with two different users.

Show child parameters

Delete User

Permanently deletes a User. It cannot be undone.

Path

id

string

User ID

Response

Returns the User object that was deleted

Conversation

Endpoints

POST

/v1/chat/conversations

GET

/v1/chat/conversations/{id}

GET

/v1/chat/conversations

POST

/v1/chat/conversations/get-or-create

PUT

/v1/chat/conversations/{id}

DELETE

/v1/chat/conversations/{id}

The Conversation object

Attributes

id

string

Id of the Conversation

createdAt

string

Creation date of the Conversation in the ISO 8601 format

updatedAt

string

Updating date of the Conversation in the ISO 8601 format

channel

string

Name of the channel where the Conversation is happening

integration

string

Name of the integration that created the Conversation

tags

object

Set of Tags that you can attach to a Conversation. The set of Tags available on a Conversation is restricted by the list of Tags defined previously by the Bot. Individual keys can be unset by posting an empty value to them.

Create Conversation

Creates a new Conversation. When creating a new Conversation, the required tags must be provided. See the specific integration for more details.

Body

channel

string

Channel name

tags

object

Tags for the Conversation

Response

Returns a Conversation object if creation succeeds. Returns an error otherwise

conversation

object

The conversation object represents an exchange of messages between one or more users. A Conversation is always linked to an integration's channels. For example, a Slack channel represents a conversation.

Show child parameters

Get Conversation

Retrieves the Conversation object for a valid identifier.

Path

id

string

Conversation id

Response

Returns a Conversation object if a valid identifier was provided. Returns an error otherwise

conversation

object

Show child parameters

List Conversations

Retrieves a list of Conversation you’ve previously created. The conversations are returned in sorted order, with the most recent appearing first. The list can be filtered using Tags.

Query

nextToken

optional string

Provide the meta.nextToken value provided in the last API response to retrieve the next page of results

tags

optional object

Filter by tags

participantIds

optional array

Filter by participant ids

Response

Returns a list of Conversation objects

conversations

array of object

Show child parameters

meta

object

Show child parameters

Get Or Create Conversation

Retrieves the Conversation object for a valid identifier. If the conversation does not exist, it will be created.

Body

channel

string

Channel name

tags

object

Tags for the Conversation

Response

Returns a Conversation object if a valid identifier was provided. Returns an error otherwise

conversation

object

Show child parameters

Update Conversation

Update a Conversation object by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Path

id

string

Conversation id

Body

tags

object

Tags for the Conversation

participantIds

array of string

Ids of the [User]s(#schema_user) participating in the conversation

Response

Returns an updated Conversation object if a valid identifier was provided. Returns an error otherwise

conversation

object

Show child parameters

Delete Conversation

Permanently deletes a Conversation. It cannot be undone. Also immediately deletes corresponding Messages.

Path

id

string

Conversation id

Response

Returns the Conversation object that was deleted

Event

Endpoints

POST

/v1/chat/events

GET

/v1/chat/events/{id}

GET

/v1/chat/events

The Event object

Attributes

id

string

Id of the Event

createdAt

string

Creation date of the Event in the ISO 8601 format

type

string

Type of the Event.

payload

object

Payload is the content of the event defined by the integration installed on your bot or one of the default events created by our api.

Create Event

Creates a new Event . When creating a new Event, the required tags must be provided. See the specific integration for more details.

Body

type

string

Type of the Event.

payload

object

Payload is the content of the event defined by the integration installed on your bot or one of the default events created by our API.

schedule

optional object

Schedule the Event to be sent at a specific time. Either dateTime or delay must be provided.

Show child parameters

Response

Returns a Event object if creation succeeds. Returns an error otherwise

event

object

The event object represents an action or an occurrence.

Show child parameters

Get Event

Retrieves the Event object for a valid identifiers.

Path

id

string

Event id

Response

Returns the Event object if a valid identifiers were provided. Returns an error otherwise

event

object

The event object represents an action or an occurrence.

Show child parameters

List Events

Retreives a list of Event you’ve previously created. The events are returned in sorted order, with the most recent appearing first. The list can be filtered using Tags.

Query

nextToken

optional string

Provide the meta.nextToken value provided in the last API response to retrieve the next page of results

Response

Returns a list of Event objects

events

array of object

Show child parameters

meta

object

Show child parameters

Message

Endpoints

POST

/v1/chat/messages

POST

/v1/chat/messages/get-or-create

GET

/v1/chat/messages/{id}

PUT

/v1/chat/messages/{id}

GET

/v1/chat/messages

DELETE

/v1/chat/messages/{id}

The Message object

Attributes

id

string

Id of the Message

createdAt

string

Creation date of the Message in the ISO 8601 format

type

string

Type of the Message represents the resource type that the message is related to

payload

object

Payload is the content type of the message. Accepted payload options: Text, Image, Choice, Dropdown, Card, Carousel, File, Audio, Video, Location

direction

string

Direction of the message (incoming or outgoing).

userId

string

ID of the User

conversationId

string

ID of the Conversation

tags

object

Create Message

Creates a new Message. When creating a new Message, the required tags must be provided. See the specific integration for more details.

Body

payload

object

Payload is the content type of the message. Accepted payload options: Text, Image, Choice, Dropdown, Card, Carousel, File, Audio, Video, Location

userId

string

ID of the User

conversationId

string

ID of the Conversation

type

string

Type of the Message represents the resource type that the message is related to

tags

object

schedule

optional object

Schedule the Message to be sent at a specific time. Either dateTime or delay must be provided.

Show child parameters

Response

Returns a Message object if creation succeeds.

message

object

The Message object represents a message in a Conversation for a specific User.

Show child parameters

Get Or Create Message

Retrieves the Message object for a valid identifier. If the message does not exist, it will be created.

Body

payload

object

Payload is the content type of the message. Accepted payload options: Text, Image, Choice, Dropdown, Card, Carousel, File, Audio, Video, Location

userId

string

ID of the User

conversationId

string

ID of the Conversation

type

string

Type of the Message represents the resource type that the message is related to

tags

object

Response

Returns a Message object if a valid identifier was provided. Returns an error otherwise

message

object

The Message object represents a message in a Conversation for a specific User.

Show child parameters

Get Message

Retrieves the Message object for a valid identifier.

Path

id

string

Id of the Message

Response

Returns a Message object if a valid identifier was provided. Returns an error otherwise

message

object

The Message object represents a message in a Conversation for a specific User.

Show child parameters

Update Message

Update a message

Path

id

string

Message id

Body

tags

object

Response

Message information

message

object

The Message object represents a message in a Conversation for a specific User.

Show child parameters

List Messages

Retrieves a list of Messages you’ve previously created. The messages are returned in sorted order, with the most recent appearing first. The list can be filtered using Tags.

Query

nextToken

optional string

Provide the meta.nextToken value provided in the last API response to retrieve the next page of results

conversationId

optional string

Conversation id

tags

optional object

Filter by tags

Response

Returns a list of Messages objects.

messages

array of object

Show child parameters

meta

object

Show child parameters

Delete Message

Permanently deletes a Message. It cannot be undone.

Path

id

string

Message id

Response

Returns the Message object that was deleted

File

Endpoints

POST

/v1/storage/files

GET

/v1/storage/files/{id}

GET

/v1/storage/files/{id}/download

DELETE

/v1/storage/files/{id}

GET

/v1/storage/files

The File object

Attributes

botId

string

ID of the bot the file will be used for

name

string

Optional arbitrary file name (e.g. my-image.jpg), will be used for display purposes only.

accessType

string

Accepted values: private, public

id

string

ID of the File

createdAt

string

Creation date of the File in ISO 8601 format

size

number

Size of the file in bytes

publicUrl

optional string

Public URL to the file contents, available only if the access type is public. If the file is private, use the Download endpoint to retrieve the file contents.

Create File

Body

botId

string

ID of the bot the file will be used for

contents

string

Base64-encoded file contents

name

string

Optional arbitrary file name (e.g. my-image.jpg), will be used for display purposes only.

accessType

string

Accepted values: private, public

Response

Success

file

object

Show child parameters

Get File

Path

id

string

File ID

Response

Success

file

object

Show child parameters

Download File

Path

id

string

File ID

Response

Raw file contents

Delete File

Path

id

string

File ID

Response

Success

List Files

Query

nextToken

optional string

Provide the meta.nextToken value provided in the last API response to retrieve the next page of results

botId

string

Bot ID

Response

Success

files

array of object

Show child parameters

meta

object

Show child parameters

State

Endpoints

GET

/v1/chat/states/{type}/{id}/{name}

POST

/v1/chat/states/{type}/{id}/{name}

PATCH

/v1/chat/states/{type}/{id}/{name}

The State object

Attributes

id

string

Id of the State

createdAt

string

Creation date of the State in the ISO 8601 format

updatedAt

string

Updating date of the State in the ISO 8601 format

botId

string

Id of the Bot

conversationId

optional string

Id of the Conversation

userId

optional string

Id of the User

name

string

Name of the State which is declared inside the bot definition

type

string

Type of the State represents the resource type (conversation, user, bot or integration) that the state is related to

payload

object

Payload is the content of the state defined by your bot.

Get State

Retrieves the State object for a valid identifiers.

Path

type

string

State type

id

string

State id

name

string

State name

Response

Returns the State object if a valid identifiers were provided. Returns an error otherwise

state

object

The state object represents the current payload. A state is always linked to either a bot, a conversation or a user.

Show child parameters

Set State

Overrides the State object by setting the values of the parameters passed.

Path

type

string

State type

id

string

State id

name

string

State name

Body

payload

object

Payload is the content of the state defined by your bot.

expiry

optional number

Expiry of the State in milliseconds. The state will expire if it is idle for the configured value. By default, a state doesn't expire.

Response

Returns the updated State object if a valid identifier was provided. Returns an an error otherwise

state

object

The state object represents the current payload. A state is always linked to either a bot, a conversation or a user.

Show child parameters

Patch State

Updates the State object by setting the values of the parameters passed.

Path

type

string

State type

id

string

State id

name

string

State name

Body

payload

object

Payload is the content of the state defined by your bot.

Response

Returns the updated State object if a valid identifier was provided. Returns an an error otherwise

state

object

The state object represents the current payload. A state is always linked to either a bot, a conversation or a user.

Show child parameters

Hub

Endpoints

GET

/v1/admin/hub/integrations

GET

/v1/admin/hub/integrations/{name}

List Public Integrations

List public integration

Query

nextToken

optional string

Provide the meta.nextToken value provided in the last API response to retrieve the next page of results

name

optional string

Integration Name

version

optional string

Integration Version

Response

Success

integrations

array of object

Show child parameters

meta

object

Show child parameters

Get Public Integration

Get public integration

Path

name

string

Integration Name

Query

version

optional string

Integration Version

Response

Success

integration

object

Show child parameters

Action

Endpoints

POST

/v1/chat/actions

Call Action

Call an action

Body

type

string

Type of the action

input

object

Input of the action

Response

Action payload

output

object

Input of the action

Bot

Endpoints

POST

/v1/admin/bots

PUT

/v1/admin/bots/{id}

GET

/v1/admin/bots

GET

/v1/admin/bots/{id}

DELETE

/v1/admin/bots/{id}

GET

/v1/admin/bots/{id}/logs

GET

/v1/admin/bots/{id}/webchat

GET

/v1/admin/bots/{id}/analytics

The Bot object

Attributes

id

string

Id of the Bot

createdAt

string

Creation date of the Bot in the ISO 8601 format

updatedAt

string

Updating date of the Bot in the ISO 8601 format

signingSecret

string

Signing secret of the Bot

integrations

object

A mapping of integrations to their configuration

states

object

A mapping of states to their definition

tags

object

Tags of the bot

Show child parameters

configuration

object

Configuration of the bot

Show child parameters

events

object

Events definition

recurringEvents

object

Recurring events

name

string

Name of the Bot

deployedAt

optional string

Last deployment date of the Bot in the ISO 8601 format

medias

array of object

Media files associated with the Bot

Show child parameters

Create Bot

Create bot

Body

states

optional object

A mapping of states to their definition

tags

optional object

Tags of the bot

Show child parameters

events

optional object

Events definition

recurringEvents

optional object

Recurring events

configuration

optional object

Show child parameters

code

optional string

JavaScript code of the bot

name

optional string

Optional name for the bot, if not provided will be auto-generated

medias

optional array of object

Media files associated with the Bot

Show child parameters

Response

Success

bot

object

Show child parameters

Update Bot

Update bot

Path

id

string

Bot ID

Body

url

optional string

URL for the bot

authentication

optional string

Type of the Bot authentication (iam)

states

optional object

A mapping of states to their definition

tags

optional object

Tags of the bot

Show child parameters

events

optional object

Events definition

recurringEvents

optional object

Recurring events

configuration

optional object

Show child parameters

blocked

optional boolean

integrations

optional object

code

optional string

JavaScript code of the bot

name

optional string

Optional name for the bot, if not provided will be auto-generated

medias

optional array of object

Media files associated with the Bot

Show child parameters

Response

Success

bot

object

Show child parameters

List Bots

List bots

Query

nextToken

optional string

Provide the meta.nextToken value provided in the last API response to retrieve the next page of results

Response

Success

bots

array of object

Show child parameters

meta

object

Show child parameters

Get Bot

Get bot details

Path

id

string

Bot ID

Response

Success

bot

object

Show child parameters

Delete Bot

Delete bot

Path

id

string

Bot ID

Response

Success

Get Bot Logs

Get bot logs

Path

id

string

Bot ID

Response

Success

logs

array of object

Show child parameters

Get Bot Webchat

Get the webchat code/URL for a bot

Path

id

string

Bot ID

Query

type

string

type of script to get

Response

Success

code

string

Get Bot Analytics

Get bot analytics

Path

id

string

Bot ID

Query

startDate

string

Start date/time (inclusive)

endDate

string

End date/time (exclusive)

Response

Success

records

array of object

Show child parameters

Integration

Endpoints

POST

/v1/admin/integrations

PUT

/v1/admin/integrations/{id}

GET

/v1/admin/integrations

GET

/v1/admin/integrations/{id}

DELETE

/v1/admin/integrations/{id}

The Integration object

Attributes

id

string

Id of the Integration

createdAt

string

Creation date of the Integration in the ISO 8601 format

updatedAt

string

Updating date of the Integration in the ISO 8601 format

name

string

Name of the Integration

version

string

Version of the Integration

channels

object

Channels definition

states

optional object

States definition

configuration

object

Configuration definition

Show child parameters

events

object

Events definition

actions

object

Action definition

Create Integration

Create integration

Body

name

string

Name of the Integration

version

string

Version of the Integration

tags

optional object

Tags of the Integration

Show child parameters

channels

optional object

Channels definition

states

optional object

States definition

configuration

optional object

Configuration definition

Show child parameters

events

optional object

Events definition

actions

optional object

Action definition

code

optional string

JavaScript code of the integration

public

optional boolean

Whether the integration is public

Response

Success

integration

object

Show child parameters

Update Integration

Update integration

Path

id

string

Integration Id

Body

tags

optional object

Tags of the Integration

Show child parameters

channels

optional object

Channels definition

states

optional object

States definition

configuration

optional object

Configuration definition

Show child parameters

events

optional object

Events definition

actions

optional object

Action definition

code

optional string

JavaScript code of the integration

public

optional boolean

Whether the integration is public

Response

Success

integration

object

Show child parameters

List Integrations

List integrations

Query

nextToken

optional string

Provide the meta.nextToken value provided in the last API response to retrieve the next page of results

name

optional string

Integration Name

version

optional string

Integration Version

Response

Success

integrations

array of object

Show child parameters

meta

object

Show child parameters

Get Integration

Get integration

Path

id

string

Integration Id

Response

Success

integration

object

Show child parameters

Delete Integration

Delete integration

Path

id

string

Integration Id

Response

Success