### Install Dependencies and Start App
Source: https://botpress.com/docs/webchat/integrations/react-native
Run these commands to install project dependencies and start the development server for your React Native application.
```bash
npm install
npx expo start
```
--------------------------------
### Fetching a Bot using Botpress Client
Source: https://botpress.com/docs/api-reference/admin-api/getting-started
This example shows how to fetch a specific bot using the Botpress client library. It requires installation of the client and configuration of environment variables for authentication.
```APIDOC
## Fetching a Bot with Botpress Client
### Description
This example demonstrates how to use the Botpress client library to programmatically fetch a bot. It requires the `@botpress/client` package to be installed and environment variables for authentication.
### Installation
```bash
npm install @botpress/client
```
### Code Example
```javascript
import dotenv from 'dotenv'
import { Client } from '@botpress/client'
dotenv.config()
async function main() {
const token = process.env.TOKEN
const workspaceId = process.env.WORKSPACE_ID
const botId = process.env.BOT_ID
if (!botId) {
throw new Error('Missing required BOT_ID environment variable')
}
console.log(token, workspaceId, botId)
const client = new Client({
token,
workspaceId
})
const { bot } = await client.getBot({ id: botId })
console.log('Bot: ', bot)
}
void main()
```
### Parameters
- **token** (string) - Your Botpress API token.
- **workspaceId** (string) - The ID of the workspace.
- **botId** (string) - The ID of the bot to fetch.
```
--------------------------------
### Fetch Bots
Source: https://botpress.com/docs/api-reference/admin-api
This example demonstrates how to fetch a list of bots using an HTTP GET request. It includes the necessary Authorization and x-workspace-id headers.
```APIDOC
## GET /bots
### Description
Fetches a list of all bots within the workspace.
### Method
GET
### Endpoint
/bots
### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.
- **x-workspace-id** (string) - Required - The ID of the workspace.
### Request Example
```bash
curl -X GET "https://api.botpress.cloud/v1/admin/bots" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "x-workspace-id: YOUR_WORKSPACE_ID"
```
### Response
#### Success Response (200)
- **bots** (array) - A list of bot objects.
- **id** (string) - The unique identifier of the bot.
- **createdAt** (string) - The timestamp when the bot was created.
- **updatedAt** (string) - The timestamp when the bot was last updated.
- **name** (string) - The name of the bot.
- **deployedAt** (string) - The timestamp when the bot was deployed.
- **meta** (object) - Metadata about the response.
- **nextToken** (string) - A token for paginating to the next set of results.
#### Response Example
```json
{
"bots": [
{
"id": "string",
"createdAt": "2025-04-03T19:25:44.810Z",
"updatedAt": "2025-04-03T19:25:44.810Z",
"name": "string",
"deployedAt": "2025-04-03T19:25:44.810Z"
}
],
"meta": {
"nextToken": "string"
}
}
```
```
--------------------------------
### Install Dependencies and Build Integration
Source: https://botpress.com/docs/integrations/sdk/integration/getting-started
Navigate to your integration's directory, install its dependencies using npm, and then build the integration using the Botpress CLI.
```bash
cd ./my-integration
npm i
bp build
```
--------------------------------
### List Tables using TypeScript Client
Source: https://botpress.com/docs/api-reference/tables-api/getting-started
This example shows how to list tables using the official Botpress TypeScript client. Ensure you have installed the client (`npm install @botpress/client`) and configured your environment variables for `TOKEN` and `BOT_ID`.
```APIDOC
import dotenv from 'dotenv'
import { Client } from '@botpress/client'
dotenv.config()
const main = async () => {
const token = process.env.TOKEN
const botId = process.env.BOT_ID
const client = new Client({
token,
botId,
})
const response = await client.listTables({})
console.log(response.tables)
}
void main()
```
--------------------------------
### Install dependencies and build the bot
Source: https://botpress.com/docs/integrations/sdk/bots-as-code
Navigate to your bot's directory, install its Node.js dependencies, and then build the bot project. The build command prepares the bot for execution.
```bash
cd ./my-bot
npm i
bp build
```
--------------------------------
### Create Table with Example Schema
Source: https://botpress.com/docs/studio/concepts/tables
Create a new table by providing a name and an example object for the schema. The schema can be empty initially and populated later.
```javascript
const { table } = await client.createTable({
name: 'Data1Table',
schema: {
name: 'test',
},
})
```
--------------------------------
### Install Botpress Client
Source: https://botpress.com/docs/api-reference/admin-api/getting-started
Install the Botpress client library using npm. This is required for interacting with the Admin API programmatically.
```bash
npm install @botpress/client
```
--------------------------------
### Instructing Autonomous Node to Use Action
Source: https://botpress.com/docs/studio/concepts/actions
Provide clear instructions in the Autonomous Node's prompt to guide when a specific Action should be invoked. This example shows how to prompt for an API fetch action.
```markdown
Use the `fetchApiData` Action when you need data from an external API.
```
--------------------------------
### Install All ADK Skills
Source: https://botpress.com/docs/adk/ai-native/skills
Installs all available skills for the specified AI coding assistants. Use `bunx` if your project uses `bun.lockb`.
```bash
npx skills add botpress/skills -s '*' -a codex claude-code -y
```
--------------------------------
### Setup: Trigger Workflow
Source: https://botpress.com/docs/adk/testing/evals
Initiate a specific workflow as part of the setup phase, optionally providing input data for the workflow.
```typescript
setup: {
workflow: {
trigger: "onboarding",
input: { userId: "user123" },
},
},
```
--------------------------------
### List Files using TypeScript Client
Source: https://botpress.com/docs/api-reference/files-api/getting-started
This example shows how to list files using the official Botpress TypeScript client. Ensure you have installed the `@botpress/client` package and configured your environment variables for `TOKEN` and `BOT_ID`.
```APIDOC
## List Files
### Description
Lists all files associated with the bot using the Botpress TypeScript client.
### Method
`client.listFiles({})`
### Parameters
This method accepts an optional object for configuration, but no specific parameters are required for basic listing.
### Request Example
```ts
import dotenv from 'dotenv'
import { Client } from '@botpress/client'
dotenv.config()
const main = async () => {
const token = process.env.TOKEN
const botId = process.env.BOT_ID
const client = new Client({
token,
botId,
})
const response = await client.listFiles({})
console.log(response.files)
}
void main()
```
### Response
#### Success Response
The `response.files` property will contain an array of file objects.
```
--------------------------------
### Install Botpress TypeScript Client
Source: https://botpress.com/docs/api-reference/files-api/getting-started
Install the official Botpress TypeScript client using npm, pnpm, or yarn.
```bash
npm install @botpress/client
```
```bash
pnpm install @botpress/client
```
```bash
yarn add @botpress/client
```
--------------------------------
### Install Botpress CLI with npm
Source: https://botpress.com/docs/integrations/sdk/installation
Install the Botpress CLI globally using npm. This command includes the Botpress SDK and other development packages.
```bash
npm install -g @botpress/cli
```
--------------------------------
### Start Development Mode with ADK CLI
Source: https://botpress.com/docs/adk/cli-reference
Start the development server with hot reloading. You can specify custom ports for the bot server and the dev console.
```bash
adk dev
adk dev --port 3000 --port-console 3001
```
--------------------------------
### Basic Container Setup
Source: https://botpress.com/docs/webchat/react-library/components/container
Demonstrates how to set up the Container component with basic styling and connection status. Ensure you replace '$CLIENT_ID$' with your actual Client ID.
```jsx
import { Container, useWebchat } from '@botpress/webchat'
function App() {
const [isWebchatOpen, setIsWebchatOpen] = useState(false)
const { clientState } = useWebchat({
clientId: '$CLIENT_ID$', // Insert your Client ID here
})
return (
// Your Webchat content goes here
)
}
```
--------------------------------
### Conversation Flow Prompt Example
Source: https://botpress.com/docs/studio/concepts/nodes/autonomous-node
Guide the conversation flow with specific instructions for greetings, escalations, and closings. This example demonstrates how to structure these conversational elements within a prompt.
```markdown
## Instructions
- **Greeting**: Start every conversation with a friendly welcome.
_Example_: "Hi, welcome to [COMPANY NAME] Support! How can I help you today?"
- **Escalation**: When a customer query becomes too complex or sensitive, transition to the "Human agent" sub-Workflow and notify the customer that you'll escalate the conversation to a human agent.
_Example_: "I’m having trouble resolving this. Let me get a human agent to assist you further."
- **Closing**: End interactions by confirming that the customer's issue has been addressed.
_Example_: "Is there anything else I can help you with today?"
```
--------------------------------
### Rewrite text
Source: https://botpress.com/docs/adk/zai/generate
Transforms existing text based on provided instructions. Can be guided by few-shot examples and length constraints.
```APIDOC
## Rewrite text
`zai.rewrite()` transforms text based on instructions:
```typescript
const formal = await adk.zai.rewrite(
"hey, the meeting is tmrw at 3",
"Make this professional and formal"
)
// "The meeting has been scheduled for tomorrow at 3:00 PM."
```
### Parameters
- `text` (string) - Required - The text to rewrite.
- `instructions` (string) - Required - The instructions for rewriting.
- `options` (object) - Optional - Configuration options.
- `length` (number) - Max tokens to generate.
- `examples` (Array<{input, output, instructions?}>) - Few-shot examples to guide the rewriting.
```
--------------------------------
### Start Development Server
Source: https://botpress.com/docs/adk/quickstart
Builds the agent, deploys it to a development bot on Botpress, and starts the dev console at http://localhost:3001/. Enables hot reloading for instant feedback on changes.
```bash
adk dev
```
--------------------------------
### Initialize a New Botpress Project
Source: https://botpress.com/docs/integrations/sdk/cli-reference
Use `bp init` to start a new project. Specify the project type (`bot`, `integration`, `plugin`) and optionally a template and name.
```bash
bp init
```
```bash
bp init --type bot --name my-bot
```
```bash
bp init --type integration --template webhook-message
```
--------------------------------
### Example Autonomous Node Instructions
Source: https://botpress.com/docs/studio/concepts/nodes/autonomous-node
Defines the identity, scope, responsibilities, response style, abilities, and guardrails for an AI agent. Use this structure to guide the behavior of your Autonomous Node.
```markdown
## Identity
You are the Customer Support AI Agent for [COMPANY NAME]. Your role is to interact with customers, address their inquiries, and provide assistance with common support topics.
## Scope
- Focus on customer inquiries about orders, billing, account issues, and general support.
- Don't handle advanced technical support or sensitive financial issues.
- Redirect or escalate issues outside your expertise to a human agent.
## Responsibility
- Initiate interactions with a friendly greeting.
- Guide the conversation based on customer needs.
- Provide accurate and concise information.
- Escalate to a human agent when customer inquiries exceed your capabilities.
## Response Style
- Maintain a friendly, clear, and professional tone.
- Keep responses brief and to the point.
- Use buttons for quick replies and easy navigation whenever possible.
## Ability
- Delegate specialized tasks to AI-Associates or escalate to a human when needed.
## Guardrails
- **Privacy**: Respect customer privacy; only request personal data if absolutely necessary.
- **Accuracy**: Provide verified and factual responses coming from Knowledge Base or official sources. Avoid speculation.
## Instructions
- **Greeting**: Start every conversation with a friendly welcome.
_Example_: "Hi, welcome to [COMPANY NAME] Support! How can I help you today?"
- **Escalation**: When a customer query becomes too complex or sensitive, notify the customer that you'll escalate the conversation to a human agent.
_Example_: "I’m having trouble resolving this. Let me get a human agent to assist you further."
- **Closing**: End interactions by confirming that the customer's issue has been addressed.
_Example_: "Is there anything else I can help you with today?"
```
--------------------------------
### Initialize a New Project with ADK CLI
Source: https://botpress.com/docs/adk/cli-reference
Scaffold a new agent project. You can specify a name and a template, or omit the name to be prompted. Use `--list-templates` to see available templates.
```bash
adk init my-agent
adk init my-agent --template hello-world
adk init --list-templates
```
--------------------------------
### Implement `startHitl` Action for Zendesk Integration
Source: https://botpress.com/docs/integrations/sdk/interface/how-tos/implementing-hitl
This snippet demonstrates the implementation of the `startHitl` action for a Zendesk integration. It includes fetching the Botpress user, retrieving the external user ID from tags, creating a Zendesk ticket, creating a Botpress conversation, and mapping the ticket and conversation IDs between the two systems.
```typescript
export default new bp.Integration({
actions: {
async startHitl({ ctx, input, client }) {
// Fetch the Botpress user that was passed in the input parameters:
const { user } = await client.getUser({
id: input.userId,
})
// From the user's tags, retrieve the external user's id:
const zendeskAuthorId = user.tags.id
if (!zendeskAuthorId) {
throw new sdk.RuntimeError(
`User ${user.id} isn't linked to a Zendesk user`
)
}
// Create a new ticket on Zendesk:
const zendeskClient = getZendeskClient(ctx.configuration)
const ticketTitle = input.title ?? 'Untitled Ticket'
const ticketBody = 'A user created a support ticket'
const createdZendeskTicket = await zendeskClient
.createTicket(ticketTitle, ticketBody, {
id: zendeskAuthorId, // <= map the ticket to the external user ID
})
// Create a Botpress conversation and map it to the Zendesk ticket:
const { conversation } = await client.getOrCreateConversation({
channel: 'hitl',
tags: {
id: createdZendeskTicket.id.toString(), // <= map to the ticket ID
},
})
// Map the Zendesk ticket to the Botpress conversation:
await zendeskClient.updateTicket(createdZendeskTicket.id, {
external_id: conversation.id, // <= map to the Botpress conversation ID
})
// Yield control back to the plugin and return the conversation ID:
return {
conversationId: conversation.id, // <= return the Botpress conversation ID
}
},
},
})
```
--------------------------------
### Fetching Bots via HTTP Request
Source: https://botpress.com/docs/api-reference/admin-api/getting-started
This example demonstrates how to fetch a list of bots using an HTTP GET request to the Admin API. It includes the necessary Authorization and x-workspace-id headers.
```APIDOC
## GET /bots
### Description
Fetches a list of bots within the specified workspace.
### Method
GET
### Endpoint
https://api.botpress.cloud/v1/admin/bots
### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.
- **x-workspace-id** (string) - Required - The ID of the workspace to query.
### Request Example
```bash
curl -X GET "https://api.botpress.cloud/v1/admin/bots" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "x-workspace-id: YOUR_WORKSPACE_ID"
```
### Response
#### Success Response (200)
- **bots** (array) - A list of bot objects.
- **id** (string) - The unique identifier of the bot.
- **createdAt** (string) - The timestamp when the bot was created.
- **updatedAt** (string) - The timestamp when the bot was last updated.
- **name** (string) - The name of the bot.
- **deployedAt** (string) - The timestamp when the bot was deployed.
- **meta** (object) - Metadata about the response.
- **nextToken** (string) - A token for paginating through results.
#### Response Example
```json
{
"bots": [
{
"id": "string",
"createdAt": "2025-04-03T19:25:44.810Z",
"updatedAt": "2025-04-03T19:25:44.810Z",
"name": "string",
"deployedAt": "2025-04-03T19:25:44.810Z"
}
],
"meta": {
"nextToken": "string"
}
}
```
```
--------------------------------
### LLM-Driven Component with Metadata
Source: https://botpress.com/docs/adk/conversations/custom-components
Configures a custom component for LLM-driven rendering by providing a description, Zod schema for props, and example values. This metadata guides the LLM in deciding when to use the component.
```typescript
import { CustomComponent, z } from "@botpress/runtime"
import component from "./TicketCard.bp.tsx"
export const TicketCardComponent = new CustomComponent(component, {
description:
"Display a ticket summary card. Use this after creating or looking up a ticket.",
props: z.object({
ticketId: z.string().describe("The ticket ID"),
title: z.string().describe("Short summary of the issue"),
priority: z.enum(["low", "medium", "high", "urgent"]).describe("Priority level"),
ticketStatus: z.string().describe("Current ticket status"),
}),
exampleValues: [
{ ticketId: "TKT-001", title: "VPN not working", priority: "high", ticketStatus: "open" },
],
})
```
--------------------------------
### Initialize MCP Configuration
Source: https://botpress.com/docs/adk/cli-reference
Generate MCP configuration files for supported AI assistants. Use --all to generate for all tools, or specify individual tools with --tool.
```bash
adk mcp:init --all
```
```bash
adk mcp:init --tool claude-code
```
```bash
adk mcp:init --tool vscode cursor
```
--------------------------------
### Create a Knowledge Base
Source: https://botpress.com/docs/adk/data/knowledge
Define a new knowledge base with a name, description, and data sources. Use `DataSource.Website.fromSitemap` to index website content.
```typescript
import { Knowledge, DataSource } from "@botpress/runtime"
export default new Knowledge({
name: "product-docs",
description: "Product documentation and FAQ",
sources: [
DataSource.Website.fromSitemap("https://docs.example.com/sitemap.xml"),
],
})
```
--------------------------------
### Confirmation Capture Card Example
Source: https://botpress.com/docs/studio/concepts/cards/capture-information
Set up a Confirmation capture card to get a binary confirmation from the user. This is useful for actions like purchase confirmation, storing the response as true or false in a workflow variable.
```yaml
Type: Confirmation
Variable name: proceedWithPurchase
Prompt message: Are you sure you want to proceed with the purchase? Please enter 'Accept' or 'Decline'.
```
--------------------------------
### Initialize and Use Tables API Client (TypeScript)
Source: https://botpress.com/docs/api-reference/tables-api
Installs the official TypeScript client and demonstrates how to initialize it using environment variables for authentication. It then calls the `listTables` method and logs the response.
```bash
npm install @botpress/client
```
```typescript
import dotenv from 'dotenv'
import { Client } from '@botpress/client'
dotenv.config()
const main = async () => {
const token = process.env.TOKEN
const botId = process.env.BOT_ID
const client = new Client({
token,
botId,
})
const response = await client.listTables({})
console.log(response.tables)
}
void main()
```
--------------------------------
### Initialize a new bot project
Source: https://botpress.com/docs/integrations/sdk/bots-as-code
Create a new bot project using the Botpress CLI. Specify the bot type, name, and template to set up the project structure.
```bash
bp init --type "bot" --name "my-bot" --template "empty"
```
--------------------------------
### Create and Upload File via HTTP Request
Source: https://botpress.com/docs/api-reference/files-api/how-tos/creating-files
Use this method when you cannot install the Botpress Client package or are working with a different programming language. It requires two HTTP requests: one to create the empty file and another to upload its content. A third request may be needed to get the file URL.
```typescript
const fileContent = 'Here goes the content of your file'
const buffer = Buffer.from(fileContent)
// Step 1: Create the file in Botpress Cloud.
// Please note that specifying the file size (in raw bytes, not characters) is required when calling this endpoint.
const result = await fetch('https://api.botpress.cloud/v1/files', {
method: 'PUT',
headers: {
'x-bot-id': 'YOUR_BOT_ID_GOES_HERE',
'Content-Type': 'application/json',
Authorization: `Bearer ${process.env.BOTPRESS_PAT}`,
},
body: JSON.stringify({
key: 'unique_file_name.txt',
size: buffer.byteLength,
}),
})
const response = await result.json()
// Step 2: Upload the file content to the unique upload URL provided for the created file.
await fetch(response.file.uploadUrl, {
method: 'PUT',
body: buffer,
})
```
--------------------------------
### Get Label
Source: https://botpress.com/docs/integrations/integration-guides/gmail
Gets the specified label by its ID.
```APIDOC
## Get Label
### Description
Gets the specified label by its ID.
### Input
- **id** (string, required) - The ID of the label to retrieve.
### Output
- **id** (string) - The immutable ID of the label.
- **name** (string) - The display name of the label.
- **type** (string) - The owner type for the label (system or user).
- **messageListVisibility** (string) - The visibility of messages with this label in the message list.
- **labelListVisibility** (string) - The visibility of the label in the label list.
- **messagesTotal** (number) - The total number of messages with the label.
- **messagesUnread** (number) - The number of unread messages with the label.
- **threadsTotal** (number) - The total number of threads with the label.
- **threadsUnread** (number) - The number of unread threads with the label.
- **color** (object) - The color to assign to the label.
- **backgroundColor** (string) - The background color.
- **textColor** (string) - The text color.
```
--------------------------------
### Initialize a New Integration
Source: https://botpress.com/docs/integrations/sdk/integration/getting-started
Create a new integration project using the Botpress CLI. Specify the type, name, and template for your integration.
```bash
bp init --type "integration" --name "my-integration" --template "hello-world"
```
--------------------------------
### Get Draft
Source: https://botpress.com/docs/integrations/integration-guides/gmail
Gets the specified draft by its ID.
```APIDOC
## Get Draft
### Description
Gets the specified draft by its ID.
### Input
- **id** (string, required) - The ID of the draft to retrieve.
### Output
- **id** (string) - The immutable ID of the draft.
- **message** (object) - The message content of the draft.
- **id** (string) - The ID of the message.
- **threadId** (string) - The ID of the thread.
- **labelIds** (array) - List of label IDs applied to the draft message.
- **snippet** (string) - A short part of the message text.
```
--------------------------------
### Verify ADK Installation
Source: https://botpress.com/docs/adk/quickstart
Checks if the ADK CLI has been installed correctly by displaying its version.
```bash
adk --version
```
--------------------------------
### Verify Botpress CLI Installation
Source: https://botpress.com/docs/integrations/sdk/installation
Check if the Botpress CLI was installed successfully by running this command in your terminal.
```bash
bp --help
```
--------------------------------
### Example Bot Response Structure
Source: https://botpress.com/docs/api-reference/admin-api/getting-started
This is an example of the JSON response structure you can expect when fetching a list of bots.
```json
{
"bots": [
{
"id": "string",
"createdAt": "2025-04-03T19:25:44.810Z",
"updatedAt": "2025-04-03T19:25:44.810Z",
"name": "string",
"deployedAt": "2025-04-03T19:25:44.810Z"
}
],
"meta": {
"nextToken": "string"
}
}
```
--------------------------------
### Implement `startHitl` Action with Custom Parameters
Source: https://botpress.com/docs/integrations/sdk/interface/how-tos/implementing-hitl
Retrieve and use custom parameters, such as 'priority', from the `hitlSession` input within the `startHitl` action to configure the external service session.
```typescript
export default new bp.Integration({
actions: {
async startHitl({ ctx, input, client }) {
// Retrieve the extra parameter:
const priority = input.hitlSession?.priority ?? 'normal'
// Then use it to create the HITL session:
const createdZendeskTicket = await zendeskClient
.createTicket(ticketTitle, ticketBody, {
priority, // <= pass the extra parameter to the external service
})
},
},
})
```
--------------------------------
### Serve Botpress Project Locally
Source: https://botpress.com/docs/integrations/sdk/cli-reference
Use `bp serve` to run your project locally. You can specify the port and provide secrets for your bot or integration.
```bash
bp serve
```
```bash
bp serve --port 8080 --secrets SECRET1=value1 SECRET2=value2
```
--------------------------------
### Install Single ADK Skill
Source: https://botpress.com/docs/adk/ai-native/skills
Installs a specific skill, such as the core 'adk' skill, for AI coding assistants.
```bash
npx skills add botpress/skills --skill adk
```
--------------------------------
### Start Conversation
Source: https://botpress.com/docs/integrations/integration-guides/whatsapp
Proactively starts a conversation with a WhatsApp user by sending them a message using a WhatsApp Message Template.
```APIDOC
## Start Conversation
### Description
Proactively starts a conversation with a WhatsApp user by sending them a message using a WhatsApp Message Template.
### Input
* **conversation** (object) - Required - Details of the conversation
* **userPhone** (string) - Required - Phone number of the WhatsApp user to start a conversation with. Add the country code (e.g. +81 for japan)
* **templateName** (string) - Required - Name of the WhatsApp Message Template to start the conversation with
* **templateLanguage** (string) - Optional - Language of the WhatsApp Message Template to start the conversation with. Defaults to "en" (English)
* **templateVariablesJson** (string) - Deprecated: use templateBodyParams instead. JSON array of body variable values: ["val1", "val2"]
* **templateHeaderParams** (object | object | object | object) - Optional - Header parameter. For text headers: type="text", value is the replacement text, parameterName is optional (for named params). For media headers: type="image"|"video"|"document", url is the media URL. Documents may include a filename.
* **templateBodyParams** (object | object) - Optional - Body parameters. For positional params ({{1}}, {{2}}, ...): type="positional", values is an ordered array of strings. For named params ({{buyer_name}}): type="named", values is a record mapping param names to values.
* **templateButtonParams** (array) - Optional - Button parameters as an ordered array. url: value is the URL suffix. quick_reply: payload is the callback data. copy_code: code is the coupon code. skip: no parameter needed (for phone number buttons, etc.).
* **url**
* **type** (string) - Required
* **value** (string) - Required
* **quick_reply**
* **type** (string) - Required
* **payload** (string) - Required
* **copy_code**
* **type** (string) - Required
* **code** (string) - Required
* **skip**
* **type** (string) - Required
* **botPhoneNumberId** (string) - Optional - Phone number ID to use as sender (uses the default phone number ID if not provided)
### Output
* **conversationId** (string) - Required - The Botpress ID of the created conversation
* **messageId** (string) - Optional - ID of the message created
```
--------------------------------
### Start a Workflow Programmatically
Source: https://botpress.com/docs/adk/workflows/create
Import a workflow and use its `start` method to initiate an instance with specific input data.
```typescript
import ProcessOrderWorkflow from "../workflows/processOrder"
const instance = await ProcessOrderWorkflow.start({ orderId: "12345" })
console.log("Started workflow:", instance.id)
```
--------------------------------
### adk init
Source: https://botpress.com/docs/adk/cli-reference
Scaffolds a new agent project. You can specify a project name and a template, or omit them to be prompted.
```APIDOC
### `adk init`
Scaffold a new agent project. Pass a name, or omit it to be prompted:
```
adk init my-agent
adk init my-agent --template hello-world
adk init --list-templates
```
Flag| Description
---|---
`-t, --template `| Template to use (default: `blank`)
`-y, --yes`, `--defaults`| Skip prompts, use defaults
`--skip-link`| Skip the linking step
`--list-templates`| List available templates and exit
```
--------------------------------
### Get or Create Conversation
Source: https://botpress.com/docs/api-reference/chat-api/openapi/getOrCreateConversation
This endpoint allows you to get an existing conversation by its ID or create a new one if it doesn't exist.
```APIDOC
## POST /conversations/get-or-create
### Description
Get or create a new [Conversation](#schema_conversation)
### Method
POST
### Endpoint
/conversations/get-or-create
### Parameters
#### Header Parameters
- **x-user-key** (string) - Required - Authentication Key
#### Request Body
- **id** (string) - Required - Identifier of the [Conversation](#schema_conversation)
### Request Example
```json
{
"id": "conversation_id"
}
```
### Response
#### Success Response (201)
- **conversation** (object) - Contains conversation details including id, createdAt, and updatedAt.
- **id** (string) - Identifier of the [Conversation](#schema_conversation)
- **createdAt** (string) - Creation date of the [Conversation](#schema_conversation) in ISO 8601 format
- **updatedAt** (string) - Updating date of the [Conversation](#schema_conversation) in ISO 8601 format
#### Response Example
```json
{
"conversation": {
"id": "conversation_id",
"createdAt": "2023-10-27T10:00:00Z",
"updatedAt": "2023-10-27T10:00:00Z"
}
}
```
```
--------------------------------
### Initialize New Agent Project
Source: https://botpress.com/docs/adk/quickstart
Creates a new Botpress agent project named 'my-agent'. Follow the on-screen wizard to select a template, package manager, and link to your Botpress workspace.
```bash
adk init my-agent
```
--------------------------------
### Add a file to a Knowledge Base using HTTP request
Source: https://botpress.com/docs/api-reference/files-api/how-tos/creating-files
This example demonstrates how to upload a file and configure it to be indexed in a Knowledge Base by setting specific tags and ensuring the 'index' parameter is true.
```APIDOC
## PUT /v1/files (with Knowledge Base tags)
### Description
Creates a file and configures it for indexing in a Knowledge Base. Requires setting `index` to `true` and providing relevant tags.
### Method
PUT
### Endpoint
https://api.botpress.cloud/v1/files
### Parameters
#### Request Body
- **key** (string) - Required - The unique name for the file (e.g., 'filename.txt').
- **index** (boolean) - Required - Set to `true` to enable indexing in the Knowledge Base.
- **tags** (object) - Required - Metadata for the file.
- **source** (string) - Required - Should be set to 'knowledge-base'.
- **kbId** (string) - Required - The ID of the Knowledge Base.
- **title** (string) - Optional - A display title for the file.
- **size** (integer) - Required - The size of the file in raw bytes.
### Request Example
```json
{
"key": "filename.txt",
"index": true,
"tags": {
"source": "knowledge-base",
"kbId": "kb_xxxxxxxxxxxxxxxxxxxxxxxxxx",
"title": "My file"
},
"size": 12345
}
```
### Response
#### Success Response (200)
- **file** (object) - Contains details about the created file.
- **uploadUrl** (string) - The URL to upload the file content.
- **url** (string) - The URL to download the file content.
#### Response Example
```json
{
"file": {
"uploadUrl": "https://storage.googleapis.com/...",
"url": "https://api.botpress.cloud/v1/files/download/...?"
}
}
```
```