Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/botpress/botpress/llms.txt

Use this file to discover all available pages before exploring further.

The IntegrationContext provides runtime information and configuration to all integration handlers.

​
Context Structure

type IntegrationContext<TIntegration> = {
  botId: string
  botUserId: string
  integrationId: string
  integrationAlias: string
  webhookId: string
  operation: string
  configuration: /* your configuration schema */
  configurationType: string | null
}

​
Properties

​
botId
string
ID of the bot using this integration.
​
botUserId
string
ID of the bot’s user account.
​
integrationId
string
Unique ID of this integration instance.
​
integrationAlias
string
Alias assigned when adding the integration to the bot.
​
webhookId
string
Unique webhook ID for receiving external events.
​
operation
string
Current operation being executed:
  • 'webhook' - Webhook handler
  • 'action_triggered' - Action execution
  • 'register' - Integration registration
  • 'unregister' - Integration removal
  • 'create_user' - User creation
  • 'create_conversation' - Conversation creation
​
configuration
object
Integration configuration values matching your schema. Fully typed based on your IntegrationDefinition.
​
configurationType
string | null
For integrations with multiple configurations, indicates which one is active. null if using the primary configuration.

​
Usage Examples

​
Accessing Configuration

import { Integration } from '@botpress/sdk'

export default new Integration({
  definition,
  
  handler: async ({ ctx, logger }) => {
    // Access typed configuration
    const apiKey = ctx.configuration.apiKey
    const webhookSecret = ctx.configuration.webhookSecret
    
    logger.forBot().info('Webhook for bot:', ctx.botId)
  },
  
  actions: {
    sendMessage: async ({ ctx, input }) => {
      // Use configuration in actions
      const client = createAPIClient({
        apiKey: ctx.configuration.apiKey,
        baseUrl: ctx.configuration.baseUrl
      })
      
      return await client.send(input)
    }
  }
})

​
Multiple Configurations

// integration.definition.ts
export default new IntegrationDefinition({
  name: 'github',
  version: '1.0.0',
  
  configurations: {
    oauth: {
      title: 'OAuth',
      schema: z.object({
        clientId: z.string(),
        clientSecret: z.string()
      })
    },
    personalAccessToken: {
      title: 'Personal Access Token',
      schema: z.object({
        token: z.string()
      })
    }
  }
})

// index.ts
export default new Integration({
  definition,
  
  register: async ({ ctx }) => {
    if (ctx.configurationType === 'oauth') {
      // OAuth setup
      const { clientId, clientSecret } = ctx.configuration
      // ...
    } else if (ctx.configurationType === 'personalAccessToken') {
      // PAT setup
      const { token } = ctx.configuration
      // ...
    }
  }
})

​
Bot-Specific Logic

export default new Integration({
  definition,
  
  handler: async ({ ctx, client, logger }) => {
    logger.forBot().info('Processing webhook for bot:', ctx.botId)
    
    // Store state specific to this bot
    await client.setState({
      type: 'integration',
      name: 'lastWebhook',
      id: ctx.integrationId,
      payload: {
        botId: ctx.botId,
        timestamp: new Date().toISOString()
      }
    })
  }
})

​
Webhook URL

export default new Integration({
  definition,
  
  register: async ({ ctx, webhookUrl, logger }) => {
    logger.forBot().info('Webhook URL:', webhookUrl)
    logger.forBot().info('Webhook ID:', ctx.webhookId)
    
    // Register with external service
    await externalAPI.createWebhook({
      url: webhookUrl,
      events: ['message.created', 'message.updated']
    })
  }
})

​
Type Safety

Context configuration is fully typed based on your definition: 
import { IntegrationDefinition, z } from '@botpress/sdk'

const definition = new IntegrationDefinition({
  name: 'myintegration',
  version: '1.0.0',
  configuration: {
    schema: z.object({
      apiKey: z.string(),
      region: z.enum(['us', 'eu', 'asia']),
      debug: z.boolean().optional()
    })
  }
})

export default new Integration({
  definition,
  
  handler: async ({ ctx }) => {
    // TypeScript knows these types:
    ctx.configuration.apiKey    // string
    ctx.configuration.region    // 'us' | 'eu' | 'asia'
    ctx.configuration.debug     // boolean | undefined
    
    // @ts-expect-error - Property doesn't exist
    ctx.configuration.invalid
  }
})

​
See Also