IntegrationContext

Runtime context available in integration handlers

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

• IntegrationDefinition - Define configuration schema
• IntegrationImplementation - Use context in handlers
• IntegrationSpecificClient - API client reference