createBot

Create bot

POST/v1/admin/bots

Authorization

AuthorizationBearerrequired

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Header parameters

x-workspace-idstringrequired

Workspace ID

x-multiple-integrationsstring

Whether the client supports bots with multiple instances of the same integration. Set to "true" to receive integration instances keyed by their alias instead of their id. This header will be removed in the future, and the API will always return multiple instances keyed by alias.

Request body

Bot metadata

statesobject

A mapping of states to their definition

eventsobject

Events definition

recurringEventsobject

subscriptionsobject

Subscriptions of the bot

actionsobject

Actions definition

configurationobject

userobject

conversationobject

messageobject

tagsobject

Optional attributes of the Bot

codestring

JavaScript code of the bot

namestring

Optional name for the bot, if not provided will be auto-generated(min length: 1)

descriptionstring

Optional description for the bot(max length: 2000)

mediasobject[]

Media files associated with the Bot

urlstring

URL of the Bot

secretsobject

Secrets are values available in the code via environment variables formatted with a SECRET_ prefix followed by your secret name. A secret name must respect SCREAMING_SNAKE casing.

devboolean

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

typeenum<string>

Type of the Bot

Available options:"studio","adk","desk"

Response

Success

botobjectrequired

Request

curl --request POST \ \
  --url https://api.botpress.cloud/v1/admin/bots \
  --header 'x-workspace-id: <x-workspace-id>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "states": {},
  "events": {},
  "recurringEvents": {},
  "subscriptions": {},
  "actions": {},
  "configuration": {},
  "user": {},
  "conversation": {},
  "message": {},
  "tags": {},
  "code": "",
  "name": "",
  "description": "",
  "medias": [],
  "url": "",
  "secrets": {},
  "dev": false,
  "type": "studio"
}
'

Response

{
  "bot": {
    "id": "string",
    "createdAt": "2025-01-15T12:00:00Z",
    "updatedAt": "2025-01-15T12:00:00Z",
    "signingSecret": "string",
    "integrations": {
      "key": {
        "enabled": true,
        "name": "string",
        "version": "string",
        "webhookUrl": "string",
        "webhookId": "string",
        "identifier": "string",
        "configurationType": "string",
        "configuration": {},
        "status": "registration_pending",
        "statusReason": "string",
        "disabledChannels": [
          "string"
        ],
        "id": "string",
        "createdAt": "2025-01-15T12:00:00Z",
        "updatedAt": "2025-01-15T12:00:00Z",
        "title": "string",
        "description": "string",
        "iconUrl": "string",
        "public": true,
        "visibility": "public",
        "verificationStatus": "unapproved",
        "lifecycleStatus": "published"
      }
    },
    "plugins": {
      "key": {
        "enabled": true,
        "name": "string",
        "version": "string",
        "configuration": {},
        "interfaces": {
          "key": {}
        },
        "integrations": {
          "key": {}
        },
        "id": "string",
        "createdAt": "2025-01-15T12:00:00Z",
        "updatedAt": "2025-01-15T12:00:00Z",
        "title": "string",
        "description": "string",
        "iconUrl": "string",
        "readmeUrl": "string",
        "public": true,
        "visibility": "public",
        "lifecycleStatus": "published"
      }
    },
    "maxExecutionTime": 0,
    "user": {
      "tags": {
        "key": {
          "title": "string",
          "description": "string"
        }
      }
    },
    "conversation": {
      "tags": {
        "key": {
          "title": "string",
          "description": "string"
        }
      }
    },
    "message": {
      "tags": {
        "key": {
          "title": "string",
          "description": "string"
        }
      }
    },
    "states": {
      "key": {
        "type": "conversation",
        "schema": {},
        "expiry": 1
      }
    },
    "configuration": {
      "data": {},
      "schema": {}
    },
    "events": {
      "key": {
        "title": "string",
        "description": "string",
        "schema": {},
        "attributes": {
          "key": "string"
        }
      }
    },
    "recurringEvents": {
      "key": {
        "schedule": {
          "cron": "string"
        },
        "type": "string",
        "payload": {},
        "failedAttempts": 0,
        "lastFailureReason": "string"
      }
    },
    "subscriptions": {
      "events": {
        "key": {}
      }
    },
    "actions": {
      "key": {
        "title": "string",
        "description": "string",
        "billable": true,
        "cacheable": true,
        "input": {
          "schema": {}
        },
        "output": {
          "schema": {}
        },
        "attributes": {
          "key": "string"
        }
      }
    },
    "tags": {
      "key": "string"
    },
    "name": "string",
    "description": "string",
    "deployedAt": "2025-01-15T12:00:00Z",
    "dev": true,
    "secrets": [
      "string"
    ],
    "createdBy": "string",
    "alwaysAlive": true,
    "status": "active",
    "medias": [
      {
        "url": "string",
        "name": "string"
      }
    ],
    "type": "studio"
  }
}