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": 5005}
Internal
HTTP status code: 500
1{2"type": "Internal",3"description": "An internal error occurred",4"status": 5005}
Unauthorized
HTTP status code: 401
1{2"type": "Unauthorized",3"description": "The request requires to be authenticated.",4"status": 4015}
Forbidden
HTTP status code: 403
1{2"type": "Forbidden",3"description": "The requested action can't be peform by this resource.",4"status": 4035}
PayloadTooLarge
HTTP status code: 413
1{2"type": "PayloadTooLarge",3"description": "The request payload is too large.",4"status": 4135}
InvalidPayload
HTTP status code: 400
1{2"type": "InvalidPayload",3"description": "The request payload is invalid.",4"status": 4005}
UnsupportedMediaType
HTTP status code: 415
1{2"type": "UnsupportedMediaType",3"description": "The request is invalid because the content-type is not supported.",4"status": 4155}
MethodNotFound
HTTP status code: 405
1{2"type": "MethodNotFound",3"description": "The requested method does not exist.",4"status": 4055}
ResourceNotFound
HTTP status code: 404
1{2"type": "ResourceNotFound",3"description": "The requested resource does not exist.",4"status": 4045}
InvalidJsonSchema
HTTP status code: 400
1{2"type": "InvalidJsonSchema",3"description": "The provided JSON schema is invalid.",4"status": 4005}
InvalidDataFormat
HTTP status code: 400
1{2"type": "InvalidDataFormat",3"description": "The provided data doesn't respect the provided JSON schema.",4"status": 4005}
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": 4005}
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": 4095}
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": 4005}
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": 4005}
Runtime
HTTP status code: 400
1{2"type": "Runtime",3"description": "An error happened during the execution of a runtime (bot or integration).",4"status": 4005}
User
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
Create User
Body
integrationNameoptional string
Name of the integration to which the user creation will be delegated
Response
userobject
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.
Get User
Retrieves the User object for a valid identifier.
Path
idstring
User ID
Response
userobject
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.
List Users
Query
nextTokenoptional string
Provide the meta.nextToken
value provided in the last API response to retrieve the next page of results
conversationIdoptional string
Filter by conversation id. This will return all users that have participated in the conversation.
tagsoptional object
Filter by tags
Response
Returns a list of User objects
usersarray of object
metaobject
nextTokenoptional string
The token to use to retrieve the next page of results, passed as a query string parameter (value should be URL-encoded) to this API endpoint.
Get Or Create User
Retrieves the User object for a valid identifier. If the user does not exist, it will be created.
Body
integrationNameoptional string
Name of the integration to which the user creation will be delegated
Response
userobject
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.
Update User
Update a User object by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
Path
idstring
User ID
Body
Response
userobject
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.
Conversation
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
tagsobject
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
channelstring
Channel name
integrationNameoptional 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
conversationobject
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.
tagsobject
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.
Get Conversation
Retrieves the Conversation object for a valid identifier.
Path
idstring
Conversation id
Response
Returns a Conversation object if a valid identifier was provided. Returns an error otherwise
conversationobject
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.
tagsobject
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.
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
nextTokenoptional string
Provide the meta.nextToken
value provided in the last API response to retrieve the next page of results
tagsoptional object
Filter by tags
participantIdsoptional array
Filter by participant ids
Response
Returns a list of Conversation objects
conversationsarray of object
tagsobject
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.
metaobject
nextTokenoptional string
The token to use to retrieve the next page of results, passed as a query string parameter (value should be URL-encoded) to this API endpoint.
Get Or Create Conversation
Retrieves the Conversation object for a valid identifier. If the conversation does not exist, it will be created.
Body
channelstring
Channel name
integrationNameoptional 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
conversationobject
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.
tagsobject
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.
Update Conversation
Update a Conversation object by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
Path
idstring
Conversation id
Body
participantIdsarray 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
conversationobject
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.
tagsobject
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.
Delete Conversation
Permanently deletes a Conversation. It cannot be undone. Also immediately deletes corresponding Messages.
Path
idstring
Conversation id
Response
Returns the Conversation object that was deleted
Event
POST
/v1/chat/events
GET
/v1/chat/events/{id}
GET
/v1/chat/events
The Event object
Create Event
Body
payloadobject
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.
Response
eventobject
The event object represents an action or an occurrence.
Get Event
Retrieves the Event object for a valid identifiers.
Path
idstring
Event id
Response
eventobject
The event object represents an action or an occurrence.
List Events
Retreives a list of Event you’ve previously created. The events are returned in sorted order, with the most recent appearing first.
Query
nextTokenoptional string
Provide the meta.nextToken
value provided in the last API response to retrieve the next page of results
typeoptional string
Filter by event type
Response
Returns a list of Event objects
eventsarray of object
metaobject
nextTokenoptional string
The token to use to retrieve the next page of results, passed as a query string parameter (value should be URL-encoded) to this API endpoint.
Message
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
payloadobject
Payload is the content type of the message. Accepted payload options: Text, Image, Choice, Dropdown, Card, Carousel, File, Audio, Video, Location
directionstring
Direction of the message (incoming
or outgoing
).
tagsobject
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
Body
payloadobject
Payload is the content type of the message. Accepted payload options: Text, Image, Choice, Dropdown, Card, Carousel, File, Audio, Video, Location
tagsobject
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
Returns a Message object if creation succeeds.
payloadobject
Payload is the content type of the message. Accepted payload options: Text, Image, Choice, Dropdown, Card, Carousel, File, Audio, Video, Location
directionstring
Direction of the message (incoming
or outgoing
).
tagsobject
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.
Get Or Create Message
Retrieves the Message object for a valid identifier. If the message does not exist, it will be created.
Body
payloadobject
Payload is the content type of the message. Accepted payload options: Text, Image, Choice, Dropdown, Card, Carousel, File, Audio, Video, Location
tagsobject
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
payloadobject
Payload is the content type of the message. Accepted payload options: Text, Image, Choice, Dropdown, Card, Carousel, File, Audio, Video, Location
directionstring
Direction of the message (incoming
or outgoing
).
tagsobject
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.
Get Message
Retrieves the Message object for a valid identifier.
Path
idstring
Id of the Message
Response
payloadobject
Payload is the content type of the message. Accepted payload options: Text, Image, Choice, Dropdown, Card, Carousel, File, Audio, Video, Location
directionstring
Direction of the message (incoming
or outgoing
).
tagsobject
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.
Update Message
Update a message
Path
idstring
Message id
Body
tagsobject
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
payloadobject
Payload is the content type of the message. Accepted payload options: Text, Image, Choice, Dropdown, Card, Carousel, File, Audio, Video, Location
directionstring
Direction of the message (incoming
or outgoing
).
tagsobject
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.
List Messages
Query
nextTokenoptional string
Provide the meta.nextToken
value provided in the last API response to retrieve the next page of results
conversationIdoptional string
Conversation id
tagsoptional object
Filter by tags
Response
Returns a list of Messages objects.
messagesarray of object
payloadobject
Payload is the content type of the message. Accepted payload options: Text, Image, Choice, Dropdown, Card, Carousel, File, Audio, Video, Location
directionstring
Direction of the message (incoming
or outgoing
).
tagsobject
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.
metaobject
nextTokenoptional string
The token to use to retrieve the next page of results, passed as a query string parameter (value should be URL-encoded) to this API endpoint.
File
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
botIdstring
ID of the bot the file will be used for
namestring
Optional arbitrary file name (e.g. my-image.jpg), will be used for display purposes only.
accessTypestring
Accepted values: private, public
sizenumber
Size of the file in bytes
publicUrloptional 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
Create File
Body
botIdstring
ID of the bot the file will be used for
contentsstring
Base64-encoded file contents
namestring
Optional arbitrary file name (e.g. my-image.jpg), will be used for display purposes only.
accessTypestring
Accepted values: private, public
Response
Success
fileobject
botIdstring
ID of the bot the file will be used for
namestring
Optional arbitrary file name (e.g. my-image.jpg), will be used for display purposes only.
accessTypestring
Accepted values: private, public
sizenumber
Size of the file in bytes
publicUrloptional 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.
Get File
Get File
Path
idstring
File ID
Response
Success
fileobject
botIdstring
ID of the bot the file will be used for
namestring
Optional arbitrary file name (e.g. my-image.jpg), will be used for display purposes only.
accessTypestring
Accepted values: private, public
sizenumber
Size of the file in bytes
publicUrloptional 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.
Download File
Download File
Path
idstring
File ID
Response
Raw file contents
Delete File
Delete File
Path
idstring
File ID
Response
Success
List Files
List Files
Query
nextTokenoptional string
Provide the meta.nextToken
value provided in the last API response to retrieve the next page of results
botIdstring
Bot ID
Response
Success
filesarray of object
botIdstring
ID of the bot the file will be used for
namestring
Optional arbitrary file name (e.g. my-image.jpg), will be used for display purposes only.
accessTypestring
Accepted values: private, public
sizenumber
Size of the file in bytes
publicUrloptional 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.
metaobject
nextTokenoptional string
The token to use to retrieve the next page of results, passed as a query string parameter (value should be URL-encoded) to this API endpoint.
State
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
typestring
Type of the State represents the resource type (conversation
, user
, bot
or integration
) that the state is related to
payloadobject
Payload is the content of the state defined by your bot.
Get State
Retrieves the State object for a valid identifiers.
Path
typestring
State type
idstring
State id
namestring
State name
Response
stateobject
The state object represents the current payload. A state is always linked to either a bot, a conversation or a user.
typestring
Type of the State represents the resource type (conversation
, user
, bot
or integration
) that the state is related to
payloadobject
Payload is the content of the state defined by your bot.
Set State
Overrides the State object by setting the values of the parameters passed.
Path
typestring
State type
idstring
State id
namestring
State name
Body
payloadobject
Payload is the content of the state defined by your bot.
expiryoptional 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
stateobject
The state object represents the current payload. A state is always linked to either a bot, a conversation or a user.
typestring
Type of the State represents the resource type (conversation
, user
, bot
or integration
) that the state is related to
payloadobject
Payload is the content of the state defined by your bot.
Patch State
Updates the State object by setting the values of the parameters passed.
Path
typestring
State type
idstring
State id
namestring
State name
Body
payloadobject
Payload is the content of the state defined by your bot.
Response
stateobject
The state object represents the current payload. A state is always linked to either a bot, a conversation or a user.
typestring
Type of the State represents the resource type (conversation
, user
, bot
or integration
) that the state is related to
payloadobject
Payload is the content of the state defined by your bot.
Hub
GET
/v1/admin/hub/integrations
GET
/v1/admin/hub/integrations/{id}
GET
/v1/admin/hub/integrations/{name}/{version}
List Public Integrations
List public integration
Query
nextTokenoptional string
Provide the meta.nextToken
value provided in the last API response to retrieve the next page of results
nameoptional string
Integration Name
versionoptional string
Integration version. Either a semver version or tag "latest"
Response
Success
integrationsarray of object
titlestring
Title of the integration. This is the name that will be displayed in the UI
descriptionstring
Description of the integration. This is the description that will be displayed in the UI
iconUrlstring
URL of the icon of the integration. This is the icon that will be displayed in the UI
metaobject
nextTokenoptional string
The token to use to retrieve the next page of results, passed as a query string parameter (value should be URL-encoded) to this API endpoint.
Get Public Integration By Id
Get public integration by Id
Path
idstring
Integration Id
Response
Success
integrationobject
channelsobject
Channels definition
statesoptional object
States definition
configurationobject
Configuration definition
schemaobject
Schema for the configuration
eventsobject
Events definition
actionsobject
Action definition
userobject
creationobject
The user creation setting determines how to create a user through the API directly. The integration will have to implement the createUser
functionality to support this setting.
enabledboolean
Enable user creation
requiredTagsarray of string
The list of tags that are required to be specified when calling the API directly to create a user.
devboolean
Indicates if the integration is a development integration; Dev integrations run locally
titlestring
Title of the integration. This is the name that will be displayed in the UI
descriptionstring
Description of the integration. This is the description that will be displayed in the UI
iconUrlstring
URL of the icon of the integration. This is the icon that will be displayed in the UI
readmeUrlstring
URL of the readme of the integration. This is the readme that will be displayed in the UI
Get Public Integration
Get public integration by name and version
Path
namestring
Integration Name
versionstring
Integration version. Either a semver version or tag "latest"
Response
Success
integrationobject
channelsobject
Channels definition
statesoptional object
States definition
configurationobject
Configuration definition
schemaobject
Schema for the configuration
eventsobject
Events definition
actionsobject
Action definition
userobject
creationobject
The user creation setting determines how to create a user through the API directly. The integration will have to implement the createUser
functionality to support this setting.
enabledboolean
Enable user creation
requiredTagsarray of string
The list of tags that are required to be specified when calling the API directly to create a user.
devboolean
Indicates if the integration is a development integration; Dev integrations run locally
titlestring
Title of the integration. This is the name that will be displayed in the UI
descriptionstring
Description of the integration. This is the description that will be displayed in the UI
iconUrlstring
URL of the icon of the integration. This is the icon that will be displayed in the UI
readmeUrlstring
URL of the readme of the integration. This is the readme that will be displayed in the UI
Action
POST
/v1/chat/actions
Call Action
Call an action
Body
typestring
Type of the action
inputobject
Input of the action
Response
Action payload
outputobject
Input of the action
Bot
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
The Bot object
Attributes
integrationsobject
A mapping of integrations to their configuration
statesobject
A mapping of states to their definition
tagsobject
Tags of the bot
messagesoptional array of string
conversationsoptional array of string
usersoptional array of string
configurationobject
Configuration of the bot
dataobject
Configuration data
schemaobject
Schema of the configuration in the JSON schema
format. The configuration data is validated against this JSON schema
.
eventsobject
Events definition
recurringEventsobject
Recurring events
devboolean
Indicates if the Bot is a development bot; Development bots run locally and can install dev integrations
createdByoptional string
Id of the user that created the bot
urlstring
URL of the media file
namestring
Name of the media file
Create Bot
Create bot
Body
statesoptional object
A mapping of states to their definition
tagsoptional object
Tags of the bot
messagesoptional array of string
conversationsoptional array of string
usersoptional array of string
eventsoptional object
Events definition
recurringEventsoptional object
Recurring events
configurationoptional object
dataoptional object
Configuration data
schemaoptional object
Schema of the configuration in the JSON schema
format. The configuration data is validated against this JSON schema
.
codeoptional string
JavaScript code of the bot
nameoptional string
Optional name for the bot, if not provided will be auto-generated
urlstring
namestring
devoptional boolean
Indicates if the Bot is a development bot; Development bots run locally and can install dev integrations
Response
Success
botobject
integrationsobject
A mapping of integrations to their configuration
statesobject
A mapping of states to their definition
tagsobject
Tags of the bot
messagesoptional array of string
conversationsoptional array of string
usersoptional array of string
configurationobject
Configuration of the bot
dataobject
Configuration data
schemaobject
Schema of the configuration in the JSON schema
format. The configuration data is validated against this JSON schema
.
eventsobject
Events definition
recurringEventsobject
Recurring events
devboolean
Indicates if the Bot is a development bot; Development bots run locally and can install dev integrations
createdByoptional string
Id of the user that created the bot
urlstring
URL of the media file
namestring
Name of the media file
Update Bot
Update bot
Path
idstring
Bot ID
Body
statesoptional object
A mapping of states to their definition
tagsoptional object
Tags of the bot
messagesoptional array of string
conversationsoptional array of string
usersoptional array of string
eventsoptional object
Events definition
recurringEventsoptional object
Recurring events
configurationoptional object
dataoptional object
Configuration data
schemaoptional object
Schema of the configuration in the JSON schema
format. The configuration data is validated against this JSON schema
.
blockedoptional boolean
integrationsoptional object
codeoptional string
JavaScript code of the bot
nameoptional string
Optional name for the bot, if not provided will be auto-generated
urlstring
namestring
Response
Success
botobject
integrationsobject
A mapping of integrations to their configuration
statesobject
A mapping of states to their definition
tagsobject
Tags of the bot
messagesoptional array of string
conversationsoptional array of string
usersoptional array of string
configurationobject
Configuration of the bot
dataobject
Configuration data
schemaobject
Schema of the configuration in the JSON schema
format. The configuration data is validated against this JSON schema
.
eventsobject
Events definition
recurringEventsobject
Recurring events
devboolean
Indicates if the Bot is a development bot; Development bots run locally and can install dev integrations
createdByoptional string
Id of the user that created the bot
urlstring
URL of the media file
namestring
Name of the media file
Transfer Bot
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
idstring
Bot ID
Body
targetWorkspaceIdstring
The ID of the workspace you want to transfer the bot to.
Response
Success
List Bots
List bots
Query
nextTokenoptional string
Provide the meta.nextToken
value provided in the last API response to retrieve the next page of results
Response
Success
botsarray of object
metaobject
nextTokenoptional string
The token to use to retrieve the next page of results, passed as a query string parameter (value should be URL-encoded) to this API endpoint.
Get Bot
Get bot details
Path
idstring
Bot ID
Response
Success
botobject
integrationsobject
A mapping of integrations to their configuration
statesobject
A mapping of states to their definition
tagsobject
Tags of the bot
messagesoptional array of string
conversationsoptional array of string
usersoptional array of string
configurationobject
Configuration of the bot
dataobject
Configuration data
schemaobject
Schema of the configuration in the JSON schema
format. The configuration data is validated against this JSON schema
.
eventsobject
Events definition
recurringEventsobject
Recurring events
devboolean
Indicates if the Bot is a development bot; Development bots run locally and can install dev integrations
createdByoptional string
Id of the user that created the bot
urlstring
URL of the media file
namestring
Name of the media file
Delete Bot
Delete bot
Path
idstring
Bot ID
Response
Success
Get Bot Logs
Get bot logs
Path
idstring
Bot ID
Response
Success
logsarray of object
timestampstring
levelstring
messagestring
Get Bot Webchat
Get the webchat code/URL for a bot
Path
idstring
Bot ID
Query
typestring
type of script to get
Response
Success
codestring
Get Bot Analytics
Get bot analytics
Path
idstring
Bot ID
Query
startDatestring
Start date/time (inclusive)
endDatestring
End date/time (exclusive)
Response
Success
recordsarray of object
startDateTimeUtcstring
ISO 8601 date string of the beginning (inclusive) of the period
endDateTimeUtcstring
ISO 8601 date string of the end (exclusive) of the period
returningUsersnumber
newUsersnumber
sessionsnumber
messagesnumber
Integration
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}
The Integration object
Attributes
channelsobject
Channels definition
statesoptional object
States definition
configurationobject
Configuration definition
schemaobject
Schema for the configuration
eventsobject
Events definition
actionsobject
Action definition
userobject
creationobject
The user creation setting determines how to create a user through the API directly. The integration will have to implement the createUser
functionality to support this setting.
enabledboolean
Enable user creation
requiredTagsarray of string
The list of tags that are required to be specified when calling the API directly to create a user.
devboolean
Indicates if the integration is a development integration; Dev integrations run locally
titlestring
Title of the integration. This is the name that will be displayed in the UI
descriptionstring
Description of the integration. This is the description that will be displayed in the UI
iconUrlstring
URL of the icon of the integration. This is the icon that will be displayed in the UI
readmeUrlstring
URL of the readme of the integration. This is the readme that will be displayed in the UI
Create Integration
Create integration
Body
usersoptional array of string
channelsoptional object
Channels definition
statesoptional object
States definition
configurationoptional object
Configuration definition
schemaobject
Schema for the configuration
eventsoptional object
Events definition
actionsoptional object
Action definition
useroptional object
creationobject
The user creation setting determines how to create a user through the API directly. The integration will have to implement the createUser
functionality to support this setting.
enabledboolean
Enable user creation
requiredTagsarray of string
The list of tags that are required to be specified when calling the API directly to create a user.
codeoptional string
JavaScript code of the integration
publicoptional boolean
Whether the integration is public
urloptional string
URL of the integration; Only available for dev integrations
devoptional boolean
Indicates if the integration is a development integration; Dev integrations run locally
iconoptional string
Base64 encoded svg of the integration icon. This icon is global to the integration each versions will be updated when this changes.
readmeoptional string
Base64 encoded markdown of the integration readme. The readme is specific to each integration versions.
titleoptional string
Title of the integration. This is the name that will be displayed in the UI
descriptionoptional string
Description of the integration. This is the description that will be displayed in the UI
Response
Success
integrationobject
channelsobject
Channels definition
statesoptional object
States definition
configurationobject
Configuration definition
schemaobject
Schema for the configuration
eventsobject
Events definition
actionsobject
Action definition
userobject
creationobject
The user creation setting determines how to create a user through the API directly. The integration will have to implement the createUser
functionality to support this setting.
enabledboolean
Enable user creation
requiredTagsarray of string
The list of tags that are required to be specified when calling the API directly to create a user.
devboolean
Indicates if the integration is a development integration; Dev integrations run locally
titlestring
Title of the integration. This is the name that will be displayed in the UI
descriptionstring
Description of the integration. This is the description that will be displayed in the UI
iconUrlstring
URL of the icon of the integration. This is the icon that will be displayed in the UI
readmeUrlstring
URL of the readme of the integration. This is the readme that will be displayed in the UI
Update Integration
Update integration
Path
idstring
Integration Id
Body
usersoptional array of string
channelsoptional object
Channels definition
statesoptional object
States definition
configurationoptional object
Configuration definition
schemaobject
Schema for the configuration
eventsoptional object
Events definition
actionsoptional object
Action definition
useroptional object
creationobject
The user creation setting determines how to create a user through the API directly. The integration will have to implement the createUser
functionality to support this setting.
enabledboolean
Enable user creation
requiredTagsarray of string
The list of tags that are required to be specified when calling the API directly to create a user.
codeoptional string
JavaScript code of the integration
publicoptional boolean
Whether the integration is public
urloptional string
URL of the integration; Only available for dev integrations
iconoptional string
Base64 encoded svg of the integration icon. This icon is global to the integration each versions will be updated when this changes.
readmeoptional string
Base64 encoded markdown of the integration readme. The readme is specific to each integration versions.
titleoptional string
Title of the integration. This is the name that will be displayed in the UI
descriptionoptional string
Description of the integration. This is the description that will be displayed in the UI
Response
Success
integrationobject
channelsobject
Channels definition
statesoptional object
States definition
configurationobject
Configuration definition
schemaobject
Schema for the configuration
eventsobject
Events definition
actionsobject
Action definition
userobject
creationobject
The user creation setting determines how to create a user through the API directly. The integration will have to implement the createUser
functionality to support this setting.
enabledboolean
Enable user creation
requiredTagsarray of string
The list of tags that are required to be specified when calling the API directly to create a user.
devboolean
Indicates if the integration is a development integration; Dev integrations run locally
titlestring
Title of the integration. This is the name that will be displayed in the UI
descriptionstring
Description of the integration. This is the description that will be displayed in the UI
iconUrlstring
URL of the icon of the integration. This is the icon that will be displayed in the UI
readmeUrlstring
URL of the readme of the integration. This is the readme that will be displayed in the UI
List Integrations
List integrations
Query
nextTokenoptional string
Provide the meta.nextToken
value provided in the last API response to retrieve the next page of results
nameoptional string
Integration Name
versionoptional string
Integration version. Either a semver version or tag "latest"
Response
Success
integrationsarray of object
titlestring
Title of the integration. This is the name that will be displayed in the UI
descriptionstring
Description of the integration. This is the description that will be displayed in the UI
iconUrlstring
URL of the icon of the integration. This is the icon that will be displayed in the UI
metaobject
nextTokenoptional string
The token to use to retrieve the next page of results, passed as a query string parameter (value should be URL-encoded) to this API endpoint.
Get Integration
Get integration
Path
idstring
Integration Id
Response
Success
integrationobject
channelsobject
Channels definition
statesoptional object
States definition
configurationobject
Configuration definition
schemaobject
Schema for the configuration
eventsobject
Events definition
actionsobject
Action definition
userobject
creationobject
The user creation setting determines how to create a user through the API directly. The integration will have to implement the createUser
functionality to support this setting.
enabledboolean
Enable user creation
requiredTagsarray of string
The list of tags that are required to be specified when calling the API directly to create a user.
devboolean
Indicates if the integration is a development integration; Dev integrations run locally
titlestring
Title of the integration. This is the name that will be displayed in the UI
descriptionstring
Description of the integration. This is the description that will be displayed in the UI
iconUrlstring
URL of the icon of the integration. This is the icon that will be displayed in the UI
readmeUrlstring
URL of the readme of the integration. This is the readme that will be displayed in the UI
Get Integration Logs
Get integration logs
Path
idstring
Integration Id
Response
Success
logsarray of object
timestampstring
levelstring
messagestring
Get Integration By Name
Get integration
Path
namestring
Integration Name
versionstring
Integration version. Either a semver version or tag "latest"
Response
Success
integrationobject
channelsobject
Channels definition
statesoptional object
States definition
configurationobject
Configuration definition
schemaobject
Schema for the configuration
eventsobject
Events definition
actionsobject
Action definition
userobject
creationobject
The user creation setting determines how to create a user through the API directly. The integration will have to implement the createUser
functionality to support this setting.
enabledboolean
Enable user creation
requiredTagsarray of string
The list of tags that are required to be specified when calling the API directly to create a user.
devboolean
Indicates if the integration is a development integration; Dev integrations run locally
titlestring
Title of the integration. This is the name that will be displayed in the UI
descriptionstring
Description of the integration. This is the description that will be displayed in the UI
iconUrlstring
URL of the icon of the integration. This is the icon that will be displayed in the UI
readmeUrlstring
URL of the readme of the integration. This is the readme that will be displayed in the UI
Delete Integration
Delete integration
Path
idstring
Integration Id
Response
Success
Workspace
The Workspace object
Attributes
idstring
namestring
ownerIdstring
createdAtstring
updatedAtstring
accountTypestring
blockedboolean
spendingLimitnumber