API Documentation
Home

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:

  1. Call the /v1/chat/conversations endpoint to obtain the first page of results:
{
  "conversations": [
    (...)
  ],
  "meta": {
    "nextToken": "wwNgQn6tWNR/IHhKGHv/sg9zcIAGsxOk0TfmM+DdmcWkBZrXYjVvcfSZIZSs4ppCr/g="
  }
}
  1. 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
  1. 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": 403
}

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.

name : string

Name of the User

pictureUrl : string

Picture URL of the User

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

name : string

Name of the user

pictureUrl : string

URL of the user picture

Response

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

user : object (6)

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

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

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.

name : string

Name of the User

pictureUrl : string

Picture URL of the User

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

name : string

Name of the user

pictureUrl : string

URL of the user picture

Response

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

user : object (6)

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

name : string

Name of the user

pictureUrl : string

URL of the user picture

Response

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

user : object (6)

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

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.

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

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 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

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 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

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.

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

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.

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

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

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
GET
/v1/admin/bots/{id}/issues
DELETE
/v1/admin/bots/{id}/issues/{issueId}
GET
/v1/admin/bots/{id}/issues/{issueId}/events

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

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)

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

Media files associated with the Bot

url : string

name : string

Response

Success

bot : object (17)

Transfer Bot

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

Transfer bot to another workspace. You need to be a Manager member of the workspace the bot currently belongs to and have permission to create bots in the target workspace.

Path

id : string

Body

targetWorkspaceId : string

The ID of the workspace you want to transfer the bot to.

Response

Success

List Bots

GET
/v1/admin/bots

List bots

Query

nextToken : string

Response

Success

bots : array of object

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

name : string

deployedAt : string

meta : object (1)

Get Bot

GET
/v1/admin/bots/{id}

Get bot details

Path

id : string

Response

Success

bot : object (17)

Delete Bot

DELETE
/v1/admin/bots/{id}

Delete bot

Path

id : string

Response

Success

Get Bot Logs

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

Get bot logs

Path

id : string

Query

timeStart : string

timeEnd : string

nextToken : string

Response

Success

logs : array of object

timestamp : string

level : string

message : string

nextToken : string

Get Bot Webchat

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

Get the webchat code/URL for a bot

Path

id : string

Query

type : string

Response

Success

code : string

Get Bot Analytics

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

Get bot analytics

Path

id : string

Query

startDate : string

endDate : string

Response

Success

records : array of object

startDateTimeUtc : string

ISO 8601 date string of the beginning (inclusive) of the period

endDateTimeUtc : string

ISO 8601 date string of the end (exclusive) of the period

returningUsers : integer

newUsers : integer

sessions : integer

messages : integer

Deprecated. Use userMessages instead.

userMessages : integer

botMessages : integer

events : integer

eventTypes : map of objects

List Bot Issues

GET
/v1/admin/bots/{id}/issues

List Bot Issues

Path

id : string

Query

nextToken : string

Response

Success

issues : array of object

id : string

code : string

createdAt : string

lastSeenAt : string

title : string

description : string

groupedData : map of objects (2)

eventsCount : number

category : string

resolutionLink : string

meta : object (1)

Delete Bot Issue

DELETE
/v1/admin/bots/{id}/issues/{issueId}

Delete Bot Issue

Path

id : string

issueId : string

Response

Success

List Bot Issue Events

GET
/v1/admin/bots/{id}/issues/{issueId}/events

List Events for a Bot Issue

Path

id : string

issueId : string

Response

Success

issueEvents : array of object

id : string

createdAt : string

data : map of objects (2)

Integration

Endpoints
POST
/v1/admin/integrations
PUT
/v1/admin/integrations/{id}
GET
/v1/admin/integrations
GET
/v1/admin/integrations/{id}
GET
/v1/admin/integrations/{id}/logs
GET
/v1/admin/integrations/{name}/{version}
DELETE
/v1/admin/integrations/{id}

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 Integration belongs to.

The Integration object

Attributes

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

identifier : object (1)

name : string

Name of the Integration

version : string

Version of the Integration

configuration : object (2)

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

Create Integration

POST
/v1/admin/integrations

Create integration

Body

name : string

Name of the Integration

version : string

Version of the Integration

configuration : object (2)

states : map of objects (2)

events : map of objects (3)

actions : map of objects (4)

identifier : object (1)

channels : map of objects (5)

user : object (2)

code : string

JavaScript code of the integration

url : string

URL of the integration; Only available for dev integrations

dev : boolean

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

icon : string

Base64 encoded svg of the integration icon. This icon is global to the integration each versions will be updated when this changes.

readme : string

Base64 encoded markdown of the integration readme. The readme is specific to each integration versions.

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

Response

Success

integration : object (17)

Update Integration

PUT
/v1/admin/integrations/{id}

Update integration

Path

id : string

Body

configuration : object (2)

channels : map of objects (5)

identifier : object (1)

actions : map of objects (4)

events : map of objects (3)

states : map of objects (2)

user : object (2)

code : string

JavaScript code of the integration

icon : string

Base64 encoded svg of the integration icon. This icon is global to the integration each versions will be updated when this changes.

readme : string

Base64 encoded markdown of the integration readme. The readme is specific to each integration versions.

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

url : string

URL of the integration; Only available for dev integrations

Response

Success

integration : object (17)

List Integrations

GET
/v1/admin/integrations

List integrations

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 Integration

GET
/v1/admin/integrations/{id}

Get integration

Path

id : string

Response

Success

integration : object (17)

Get Integration Logs

GET
/v1/admin/integrations/{id}/logs

Get integration logs

Path

id : string

Query

timeStart : string

timeEnd : string

nextToken : string

Response

Success

logs : array of object

timestamp : string

level : string

message : string

nextToken : string

Get Integration By Name

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

Get integration

Path

name : string

version : string

Response

Success

integration : object (17)

Delete Integration

DELETE
/v1/admin/integrations/{id}

Delete integration

Path

id : string

Response

Success

Workspace

Endpoints
GET
/v1/admin/workspaces/{id}/billing/details
PUT
/v1/admin/workspaces/{id}/billing/payment-method
GET
/v1/admin/workspaces/{id}/billing/invoices
POST
/v1/admin/workspaces/{id}/billing/invoices/charge-unpaid
POST
/v1/admin/workspaces
GET
/v1/admin/workspaces/{id}
GET
/v1/admin/workspaces/{id}/usages
GET
/v1/admin/workspaces/{id}/quota
GET
/v1/admin/workspaces/{id}/quotas
PUT
/v1/admin/workspaces/{id}
GET
/v1/admin/workspaces
PUT
/v1/admin/workspaces/{id}/change-plan
DELETE
/v1/admin/workspaces/{id}
GET
/v1/admin/workspaces/{id}/audit-records

The Workspace object

Attributes

id : string

name : string

ownerId : string

createdAt : string

updatedAt : string

botCount : number

accountType : string

plan : string

blocked : boolean

spendingLimit : number

Get Workspace Billing Details

GET
/v1/admin/workspaces/{id}/billing/details

Get billing details of workspace

Path

id : string

Response

Success

currentPeriod : object (3)

paymentMethod : object (2)

Set Workspace Payment Method

PUT
/v1/admin/workspaces/{id}/billing/payment-method

Set the Stripe PaymentMethod to use for billing the workspace. To create a PaymentMethod, use the Stripe API or SDK with our Stripe Publishable Key which is listed in this documentation.

Path

id : string

Body

stripePaymentMethodId : string

ID of the Stripe PaymentMethod to attach to the workspace.

Response

Success

stripePaymentMethodId : string

paymentMethod : object (2)

status : string

nextAction : object (1)

List Workspace Invoices

GET
/v1/admin/workspaces/{id}/billing/invoices

List invoices billed to workspace

Path

id : string

Response

Success

invoices : array of object

id : string

period : object (2)

date : string

Date on which the invoice was generated.

amount : number

Total amount to pay of the invoice.

currency : string

Currency of the invoice amount.

paymentStatus : string

paymentAttemptCount : number

Number of times payment has been unsuccessfully attempted on the invoice.

nextPaymentAttemptDate : string

Date on which the next payment attempt will be made.

pdfUrl : string

URL to download the PDF file of the invoice.

Charge Workspace Unpaid Invoices

POST
/v1/admin/workspaces/{id}/billing/invoices/charge-unpaid

Charge unpaid invoices of a workspace.

Path

id : string

Body

invoiceIds : array of string

Response

Success

chargedInvoices : array of object

Invoices that were successfully charged by this request.

id : string

amount : number

failedInvoices : array of object

Invoices that failed to be charged by this request.

id : string

amount : number

failedReason : string

Create Workspace

POST
/v1/admin/workspaces

Create workspace

Body

name : string

Response

Success

id : string

name : string

ownerId : string

createdAt : string

updatedAt : string

botCount : number

accountType : string

plan : string

blocked : boolean

spendingLimit : number

Get Workspace

GET
/v1/admin/workspaces/{id}

Get workspace details

Path

id : string

Response

Success

id : string

name : string

ownerId : string

createdAt : string

updatedAt : string

botCount : number

accountType : string

plan : string

blocked : boolean

spendingLimit : number

List Workspace Usages

GET
/v1/admin/workspaces/{id}/usages

List workspace usages

Path

id : string

Query

type : string

period : string

Response

Success

usages : array of object

id : string

Id of the usage that it is linked to. It can either be a workspace id or a bot id

period : string

Period of the quota that it is applied to

value : number

Value of the current usage

quota : number

Quota of the current usage

type : string

Usage type that can be used

Get Workspace Quota

GET
/v1/admin/workspaces/{id}/quota

Get workspace quota

Path

id : string

Query

type : string

period : string

Response

Success

quota : object (3)

List Workspace Quotas

GET
/v1/admin/workspaces/{id}/quotas

List workspace quotas

Path

id : string

Query

period : string

Response

Success

quotas : array of object

period : string

Period of the quota that it is applied to

value : number

Value of the quota that is used

type : string

Usage type that can be used

Update Workspace

PUT
/v1/admin/workspaces/{id}

Update workspace

Path

id : string

Body

name : string

spendingLimit : number

Response

Success

id : string

name : string

ownerId : string

createdAt : string

updatedAt : string

botCount : number

accountType : string

plan : string

blocked : boolean

spendingLimit : number

List Workspaces

GET
/v1/admin/workspaces

List workspaces the user has access to

Query

nextToken : string

Response

Success

workspaces : array of object

id : string

name : string

ownerId : string

createdAt : string

updatedAt : string

botCount : number

accountType : string

plan : string

blocked : boolean

spendingLimit : number

meta : object (1)

Change Workspace Plan

PUT
/v1/admin/workspaces/{id}/change-plan

Change workspace billing plan

Path

id : string

Body

plan : string

Response

Success

id : string

name : string

ownerId : string

createdAt : string

updatedAt : string

botCount : number

accountType : string

plan : string

blocked : boolean

spendingLimit : number

Delete Workspace

DELETE
/v1/admin/workspaces/{id}

Delete workspace

Path

id : string

Response

Success

Get Audit Records

GET
/v1/admin/workspaces/{id}/audit-records

Get the audit records of a workspace, sorted from most recent to oldest.

Query

nextToken : string

Path

id : string

Response

List of audit records

records : array of object

id : string

recordedAt : string

userId : string

userEmail : string

resourceId : string

resourceName : string

action : string

meta : object (1)

Workspace Member

Endpoints
GET
/v1/admin/workspace-members
DELETE
/v1/admin/workspace-members/{id}
POST
/v1/admin/workspace-members
PUT
/v1/admin/workspace-members/{id}

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 Workspace Member belongs to.

The WorkspaceMember object

Attributes

id : string

userId : string

email : string

role : string

List Workspace Members

GET
/v1/admin/workspace-members

Lists all the members in a workspace

Query

nextToken : string

Response

Success

members : array of object

id : string

userId : string

email : string

role : string

meta : object (1)

Delete Workspace Member

DELETE
/v1/admin/workspace-members/{id}

Remove a member of a workspace

Path

id : string

Response

Success

Create Workspace Member

POST
/v1/admin/workspace-members

Add a member to the workspace

Body

email : string

role : string

Response

Success

id : string

userId : string

email : string

role : string

Update Workspace Member

PUT
/v1/admin/workspace-members/{id}

Update the member of a workspace

Path

id : string

Body

role : string

Response

Success

id : string

userId : string

email : string

role : string

Account

Endpoints
GET
/v1/admin/account/me
GET
/v1/admin/account/pats
POST
/v1/admin/account/pats
DELETE
/v1/admin/account/pats/{id}

The Account object

Attributes

id : string

email : string

createdAt : string

Creation date of the Account in ISO 8601 format

Get Account

GET
/v1/admin/account/me

Get details of the account authenticating with this endpoint.

Response

Success

account : object (3)

List Personal Access Tokens

GET
/v1/admin/account/pats

List PATs (Personal Access Tokens) of account.

Response

Success

pats : array of object

id : string

createdAt : string

note : string

Create Personal Access Token

POST
/v1/admin/account/pats

Create a PAT

Body

note : string

Note to identify the PAT

Response

Success

pat : object (4)

Delete Personal Access Token

DELETE
/v1/admin/account/pats/{id}

Delete a PAT

Path

id : string

Response

Success

Usage

Endpoints
GET
/v1/admin/usages/{id}

The Usage object

Attributes

id : string

Id of the usage that it is linked to. It can either be a workspace id or a bot id

period : string

Period of the quota that it is applied to

value : number

Value of the current usage

quota : number

Quota of the current usage

type : string

Usage type that can be used

Get Usage

GET
/v1/admin/usages/{id}

Get usage

Query

type : string

period : string

Path

id : string

Response

Success

usage : object (5)