Botpress API Documentation

Introduction

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

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

The base URL of the Botpress Cloud API is: https://api.botpress.cloud

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.

Using the Botpress Client

If you're using JavaScript or TypeScript, we recommend using our official Botpress Client (opens in a new tab) to call our API, but if you're using another programming language or just want direct access to our REST API you can use this documentation as reference.

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}

Identity Token

Personal Access Token (PAT): Can be generated in the Profile Settings section of your Botpress Cloud account (opens in a new tab).
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.

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:

{
  "conversations": [
    (...)
  ],
  "meta": {
    "nextToken": "wwNgQn6tWNR/IHhKGHv/sg9zcIAGsxOk0TfmM+DdmcWkBZrXYjVvcfSZIZSs4ppCr/g="
  }
}

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:

{
  "conversations": [
    (...)
  ],
  "meta": {}
}

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

 {
  "type": "Unknown",
  "description": "An unknown error occurred",
  "status": 500
}

Internal

 {
  "type": "Internal",
  "description": "An internal error occurred",
  "status": 500
}

Unauthorized

 {
  "type": "Unauthorized",
  "description": "The request requires to be authenticated.",
  "status": 401
}

Forbidden

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

Payload Too Large

 {
  "type": "PayloadTooLarge",
  "description": "The request payload is too large.",
  "status": 413
}

Invalid Payload

 {
  "type": "InvalidPayload",
  "description": "The request payload is invalid.",
  "status": 400
}

Unsupported Media Type

 {
  "type": "UnsupportedMediaType",
  "description": "The request is invalid because the content-type is not supported.",
  "status": 415
}

Method Not Found

 {
  "type": "MethodNotFound",
  "description": "The requested method does not exist.",
  "status": 405
}

Resource Not Found

 {
  "type": "ResourceNotFound",
  "description": "The requested resource does not exist.",
  "status": 404
}

Invalid Json Schema

 {
  "type": "InvalidJsonSchema",
  "description": "The provided JSON schema is invalid.",
  "status": 400
}

Invalid Data Format

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

Invalid Identifier

 {
  "type": "InvalidIdentifier",
  "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.",
  "status": 400
}

Relation Conflict

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

Reference Not Found

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

Invalid Query

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

Runtime

 {
  "type": "Runtime",
  "description": "An error happened during the execution of a runtime (bot or integration).",
  "status": 400
}

Already Exists

 {
  "type": "AlreadyExists",
  "description": "The record attempted to be created already exists.",
  "status": 409
}

Rate Limited

 {
  "type": "RateLimited",
  "description": "The request has been rate limited.",
  "status": 429
}

Payment Required

 {
  "type": "PaymentRequired",
  "description": "A payment is required to perform this request.",
  "status": 402
}

Quota Exceeded

 {
  "type": "QuotaExceeded",
  "description": "The request exceeds the allowed quota. Quotas are a soft limit that can be increased.",
  "status": 429
}

Limit Exceeded

 {
  "type": "LimitExceeded",
  "description": "The request exceeds the allowed limit. Limits are a hard limit that cannot be increased.",
  "status": 413
}

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}

Required Headers

To access these API endpoints the following HTTP headers are required to be passed in all requests:

x-bot-id: The ID of the bot that the User belongs to.
x-integration-id: When the endpoint is being called as an Integration, this should be the ID of the integration that's calling it.

The User object

Attributes

id : string

Id of the User

createdAt : string

Creation date of the User in ISO 8601 format

updatedAt : string

Updating date of the User in ISO 8601 format

tags : map of objects

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

POST

/v1/chat/users

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

Body

tags : map of objects

Tags for the User

integrationName : string

Name of the integration to which the user creation will be delegated

Response

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

user : object (4)

Get User

GET

/v1/chat/users/{id}

Retrieves the User object for a valid identifier.

Path

id : string

Response

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

user : object (4)

List Users

GET

/v1/chat/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 : string

conversationId : string

tags : object

Response

Returns a list of User objects

users : array of object

id : string

Id of the User

createdAt : string

Creation date of the User in ISO 8601 format

updatedAt : string

Updating date of the User in ISO 8601 format

tags : map of objects

meta : object (1)

Get Or Create User

POST

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

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

Body

tags : map of objects

Tags for the User

integrationName : string

Name of the integration to which the user creation will be delegated

Response

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

user : object (4)

Update User

PUT

/v1/chat/users/{id}

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

Path

id : string

Body

tags : map of objects

Tags for the User

Response

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

user : object (4)

Delete User

DELETE

/v1/chat/users/{id}

Permanently deletes a User. It cannot be undone.

Path

id : string

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}

Required Headers

To access these API endpoints the following HTTP headers are required to be passed in all requests:

x-bot-id: The ID of the bot that the Conversation belongs to.
x-integration-id: When the endpoint is being called as an Integration, this should be the ID of the integration that's calling it.

The Conversation object

Attributes

id : string

Id of the Conversation

createdAt : string

Creation date of the Conversation in ISO 8601 format

updatedAt : string

Updating date of the Conversation in 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 : map of objects

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

POST

/v1/chat/conversations

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 : map of objects

Tags for the Conversation

integrationName : string

Name of the integration to which the conversation creation will be delegated

Response

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

conversation : object (6)

Get Conversation

GET

/v1/chat/conversations/{id}

Retrieves the Conversation object for a valid identifier.

Path

id : string

Response

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

conversation : object (6)

List Conversations

GET

/v1/chat/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 : string

tags : object

participantIds : array of string

Response

Returns a list of Conversation objects

conversations : array of object

id : string

Id of the Conversation

createdAt : string

Creation date of the Conversation in ISO 8601 format

updatedAt : string

Updating date of the Conversation in 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 : map of objects

meta : object (1)

Get Or Create Conversation

POST

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

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

Body

channel : string

Channel name

tags : map of objects

Tags for the Conversation

integrationName : string

Name of the integration to which the conversation creation will be delegated

Response

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

conversation : object (6)

Update Conversation

PUT

/v1/chat/conversations/{id}

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

Path

id : string

Body

tags : map of objects

Tags for the Conversation

Response

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

conversation : object (6)

Delete Conversation

DELETE

/v1/chat/conversations/{id}

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

Path

id : string

Response

Returns the Conversation object that was deleted

Event

Endpoints

POST

/v1/chat/events

GET

/v1/chat/events/{id}

GET

/v1/chat/events

Required Headers

To access these API endpoints the following HTTP headers are required to be passed in all requests:

x-bot-id: The ID of the bot that the Event belongs to.
x-integration-id: When the endpoint is being called as an Integration, this should be the ID of the integration that's calling it.

The Event object

Attributes

id : string

Id of the Event

createdAt : string

Creation date of the Event in ISO 8601 format

type : string

Type of the Event.

payload : map of objects

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

POST

/v1/chat/events

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 : map of objects

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 : object (2)

Response

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

event : object (4)

Get Event

GET

/v1/chat/events/{id}

Retrieves the Event object for a valid identifiers.

Path

id : string

Response

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

event : object (4)

List Events

GET

/v1/chat/events

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

Query

nextToken : string

type : string

Response

Returns a list of Event objects

events : array of object

id : string

Id of the Event

createdAt : string

Creation date of the Event in ISO 8601 format

type : string

Type of the Event.

payload : map of objects

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.

meta : object (1)

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}

Required Headers

To access these API endpoints the following HTTP headers are required to be passed in all requests:

x-bot-id: The ID of the bot that the Message belongs to.
x-integration-id: When the endpoint is being called as an Integration, this should be the ID of the integration that's calling it.

The Message object

Attributes

id : string

Id of the Message

createdAt : string

Creation date of the Message in ISO 8601 format

type : string

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

payload : map of objects

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 : map of objects

Create Message

POST

/v1/chat/messages

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

Body

payload : map of objects

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 : map of objects

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

schedule : object (2)

Response

Returns a Message object if creation succeeds.

message : object (8)

Get Or Create Message

POST

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

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

Body

payload : map of objects

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 : map of objects

schedule : object (2)

Response

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

message : object (8)

Get Message

GET

/v1/chat/messages/{id}

Retrieves the Message object for a valid identifier.

Path

id : string

Response

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

message : object (8)

Update Message

PUT

/v1/chat/messages/{id}

Update a message

Path

id : string

Body

tags : map of objects

Response

Message information

message : object (8)

List Messages

GET

/v1/chat/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 : string

conversationId : string

tags : object

Response

Returns a list of Messages objects.

messages : array of object

id : string

Id of the Message

createdAt : string

Creation date of the Message in ISO 8601 format

type : string

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

payload : map of objects

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 : map of objects

meta : object (1)

Delete Message

DELETE

/v1/chat/messages/{id}

Permanently deletes a Message. It cannot be undone.

Path

id : string

Response

Returns the Message object that was deleted

State

Endpoints

GET

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

POST

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

PATCH

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

Required Headers

To access these API endpoints the following HTTP headers are required to be passed in all requests:

x-bot-id: The ID of the bot that the State belongs to.
x-integration-id: When the endpoint is being called as an Integration, this should be the ID of the integration that's calling it.

The State object

Attributes

id : string

Id of the State

createdAt : string

Creation date of the State in ISO 8601 format

updatedAt : string

Updating date of the State in ISO 8601 format

botId : string

Id of the Bot

conversationId : string

Id of the Conversation

userId : 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 : map of objects

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

Get State

GET

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

Retrieves the State object for a valid identifiers.

Path

type : string

id : string

name : string

Response

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

state : object (9)

Set State

POST

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

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

Path

type : string

id : string

name : string

Body

payload : map of objects

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

expiry : 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 (9)

Patch State

PATCH

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

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

Path

type : string

id : string

name : string

Body

payload : map of objects

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 (9)

Hub

Endpoints

GET

/v1/admin/hub/integrations

GET

/v1/admin/hub/integrations/{id}

GET

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

List Public Integrations

GET

/v1/admin/hub/integrations

List public integration

Query

nextToken : string

name : string

version : string

Response

Success

integrations : array of object

id : string

Id of the Integration

name : string

Name of the Integration

version : string

Version of the Integration

createdAt : string

Creation date of the Integration in ISO 8601 format

updatedAt : string

Updating date of the Integration in ISO 8601 format

title : string

Title of the integration. This is the name that will be displayed in the UI

description : string

Description of the integration. This is the description that will be displayed in the UI

iconUrl : string

URL of the icon of the integration. This is the icon that will be displayed in the UI

meta : object (1)

Get Public Integration By Id

GET

/v1/admin/hub/integrations/{id}

Get public integration by Id

Path

id : string

Response

Success

integration : object (16)

id : string

Id of the Integration

createdAt : string

Creation date of the Integration in ISO 8601 format

updatedAt : string

Updating date of the Integration in ISO 8601 format

name : string

Name of the Integration

version : string

Version of the Integration

configuration : object (1)

channels : map of objects (5)

states : map of objects (2)

events : map of objects (3)

actions : map of objects (4)

user : object (2)

dev : boolean

Indicates if the integration is a development integration; Dev integrations run locally

title : string

Title of the integration. This is the name that will be displayed in the UI

description : string

Description of the integration. This is the description that will be displayed in the UI

iconUrl : string

URL of the icon of the integration. This is the icon that will be displayed in the UI

readmeUrl : string

URL of the readme of the integration. This is the readme that will be displayed in the UI

Get Public Integration

GET

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

Get public integration by name and version

Path

name : string

version : string

Response

Success

integration : object (16)

id : string

Id of the Integration

createdAt : string

Creation date of the Integration in ISO 8601 format

updatedAt : string

Updating date of the Integration in ISO 8601 format

name : string

Name of the Integration

version : string

Version of the Integration

configuration : object (1)

channels : map of objects (5)

states : map of objects (2)

events : map of objects (3)

actions : map of objects (4)

user : object (2)

dev : boolean

Indicates if the integration is a development integration; Dev integrations run locally

title : string

Title of the integration. This is the name that will be displayed in the UI

description : string

Description of the integration. This is the description that will be displayed in the UI

iconUrl : string

URL of the icon of the integration. This is the icon that will be displayed in the UI

readmeUrl : string

URL of the readme of the integration. This is the readme that will be displayed in the UI

Action

Endpoints

POST

/v1/chat/actions

Required Headers

To access these API endpoints the following HTTP headers are required to be passed in all requests:

x-bot-id: The ID of the bot that the Action belongs to.
x-integration-id: When the endpoint is being called as an Integration, this should be the ID of the integration that's calling it.

Call Action

POST

/v1/chat/actions

Call an action

Body

type : string

Type of the action

input : map of objects

Input of the action

Response

Action payload

output : map of objects

Input of the action

Bot

Endpoints

POST

/v1/admin/bots

PUT

/v1/admin/bots/{id}

POST

/v1/admin/bots/{id}/transfer

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

Required Headers

To access these API endpoints the following HTTP headers are required to be passed in all requests:

x-workspace-id: The ID of the workspace that the Bot belongs to.

The Bot object

Attributes

id : string

Id of the Bot

createdAt : string

Creation date of the Bot in ISO 8601 format

updatedAt : string

Updating date of the Bot in ISO 8601 format

signingSecret : string

Signing secret of the Bot

integrations : map of objects (13)

user : object (1)

conversation : object (1)

message : object (1)

states : map of objects (3)

configuration : object (2)

events : map of objects (3)

recurringEvents : map of objects (3)

name : string

Name of the Bot

deployedAt : string

Last deployment date of the Bot in the ISO 8601 format

dev : boolean

Indicates if the Bot is a development bot; Development bots run locally and can install dev integrations

createdBy : string

Id of the user that created the bot

medias : array of object

Media files associated with the Bot

url : string

URL of the media file

name : string

Name of the media file

Create Bot

POST

/v1/admin/bots

Create bot

Body

states : map of objects (3)

events : map of objects (3)

recurringEvents : map of objects (3)

configuration : object (2)

user : object (1)

conversation : object (1)

message : object (1)

code : string

JavaScript code of the bot

name : string

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

medias : array of object

Media files associated with the Bot

url : string

name : string

url : string

URL of the Bot; Only available for dev bots

dev : boolean

Indicates if the Bot is a development bot; Development bots run locally and can install dev integrations

Response

Success

bot : object (17)

id : string

Id of the Bot

createdAt : string

Creation date of the Bot in ISO 8601 format

updatedAt : string

Updating date of the Bot in ISO 8601 format

signingSecret : string

Signing secret of the Bot

integrations : map of objects (13)

user : object (1)

conversation : object (1)

message : object (1)

states : map of objects (3)

configuration : object (2)

events : map of objects (3)

recurringEvents : map of objects (3)

name : string

Name of the Bot

deployedAt : string

Last deployment date of the Bot in the ISO 8601 format

dev : boolean

Indicates if the Bot is a development bot; Development bots run locally and can install dev integrations

createdBy : string

Id of the user that created the bot

medias : array of object

Media files associated with the Bot

url : string

URL of the media file

name : string

Name of the media file

Update Bot

PUT

/v1/admin/bots/{id}

Update bot

Path

id : string

Body

url : string

URL of the Bot; Only available for dev bots

authentication : string

Type of the Bot authentication (iam)

configuration : object (2)

blocked : boolean

user : object (1)

message : object (1)

conversation : object (1)

events : map of objects (3)

states : map of objects (3)

recurringEvents : map of objects (3)

integrations : map of objects (2)

code : string

JavaScript code of the bot

name : string

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

medias : array of object