Integrations

Integrations connect your bots to AI backends that generate responses. An integration is a webhook configuration that defines how to communicate with services like OpenAI, Anthropic, or your own custom API.

Overview

An integration consists of:

Webhook URL: The endpoint to send messages to
HTTP Headers: Authentication and custom headers
Timeout: Maximum wait time for responses
Weight: For A/B testing (optional)
Payload Format: The request structure sent to your backend

Creating an Integration

Navigate to Integrations

From your bot page, click Integrations in the sidebar.

Click Create Integration

Click the Create Integration button to open the form.

Configure Basic Settings

Enter the integration details:

Name: Friendly name (e.g., “OpenAI GPT-4”)
Webhook URL: Your AI backend endpoint
Timeout: Response timeout in seconds (default: 30)

Add Headers (Optional)

Add authentication or custom headers:

Example headers:

Authorization: Bearer sk-...
Content-Type: application/json
X-Custom-Header: value

Configure Advanced Settings

Set additional options:

Weight: For A/B testing (default: 1)
Fallback: Mark as fallback integration

Preview Payload

Review the payload format that will be sent:

Save

Click Create to save the integration.

Request Payload Format

When a user sends a message, your integration receives a POST request with this structure:

{
  "messages": [
    {
      "role": "user",
      "content": "Hello, how are you?"
    }
  ],
  "conversation_id": "conv_123",
  "user": {
    "id": "user_456",
    "platform": "telegram",
    "name": "John Doe"
  },
  "bot": {
    "id": "bot_789",
    "name": "Support Bot"
  },
  "metadata": {
    "channel": "telegram",
    "chat_id": "123456789"
  }
}

Messages Array

The messages array contains conversation history based on your configured context window:

"messages": [
  {
    "role": "user",
    "content": "What's the weather?"
  },
  {
    "role": "assistant",
    "content": "I'll check the weather for you."
  },
  {
    "role": "user",
    "content": "Thanks"
  }
]

This follows the OpenAI/Anthropic message format for easy integration.

Expected Response

Your backend should return JSON with this structure:

{
  "content": "The response message to send to the user"
}

Or with metadata:

{
  "content": "The response message",
  "metadata": {
    "model": "gpt-4",
    "tokens": 150,
    "custom_field": "value"
  }
}

The content field is required. Everything else is optional and stored for your reference.

Integration Types

OpenAI Compatible

For OpenAI API or compatible services:

URL: https://api.openai.com/v1/chat/completions
Headers:
  Authorization: Bearer YOUR_API_KEY
  Content-Type: application/json

You’ll need to transform the payload or use a proxy that accepts our format.

Anthropic (Claude)

For Anthropic’s API:

URL: https://api.anthropic.com/v1/messages
Headers:
  x-api-key: YOUR_API_KEY
  anthropic-version: 2023-06-01

Use a proxy to transform our payload to Anthropic’s format.

Custom Backend

For your own API:

URL: https://your-domain.com/api/chat
Headers:
  Authorization: Bearer YOUR_TOKEN
  X-Custom: value

Your backend receives our payload format and returns content as JSON.

Fallback Integrations

Mark an integration as “fallback” to use it when the primary integration fails:

Fallback behavior:

Bot tries primary integration (highest weight)
If it times out or errors, tries fallback
If fallback also fails, sends error message to user

This provides reliability for production bots.

Webhook Setup

Detailed webhook configuration guide

A/B Testing

Compare multiple AI backends

Custom Headers

Authentication and custom headers

Testing Your Integration

Use the built-in test feature:

Go to Integration

Open the integration you want to test.

Click Test

Click the Test button.

Send Test Message

Enter a test message and submit.

Review Response

Check the response from your backend. Look for errors or unexpected behavior.

Troubleshooting

Timeout Errors

If requests timeout:

Increase timeout value
Optimize your backend for faster responses
Check network connectivity

Authentication Errors

If you get 401/403 errors:

Verify API keys are correct
Check header format
Ensure headers include required authentication

Invalid Response Format

If the bot can’t parse responses:

Ensure response is valid JSON
Include required content field
Check for encoding issues

API Access

Manage integrations programmatically using the API.

Create an integration via API

cURL
JavaScript
PHP
Python

curl -X POST https://api.chatbotplatform.io/v1/bots/bot_123/integrations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OpenAI GPT-4",
    "webhook_url": "https://api.openai.com/v1/chat/completions",
    "headers": {
      "Authorization": "Bearer sk-...",
      "Content-Type": "application/json"
    },
    "timeout": 30,
    "weight": 1
  }'

const response = await fetch('https://api.chatbotplatform.io/v1/bots/bot_123/integrations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'OpenAI GPT-4',
    webhook_url: 'https://api.openai.com/v1/chat/completions',
    headers: {
      'Authorization': 'Bearer sk-...',
      'Content-Type': 'application/json'
    },
    timeout: 30,
    weight: 1
  })
});
const data = await response.json();

$response = Http::withToken('YOUR_API_KEY')
    ->post('https://api.chatbotplatform.io/v1/bots/bot_123/integrations', [
        'name' => 'OpenAI GPT-4',
        'webhook_url' => 'https://api.openai.com/v1/chat/completions',
        'headers' => [
            'Authorization' => 'Bearer sk-...',
            'Content-Type' => 'application/json'
        ],
        'timeout' => 30,
        'weight' => 1
    ]);

$integration = $response->json();

response = requests.post(
    'https://api.chatbotplatform.io/v1/bots/bot_123/integrations',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'name': 'OpenAI GPT-4',
        'webhook_url': 'https://api.openai.com/v1/chat/completions',
        'headers': {
            'Authorization': 'Bearer sk-...',
            'Content-Type': 'application/json'
        },
        'timeout': 30,
        'weight': 1
    }
)
integration = response.json()

List bot integrations

cURL
JavaScript
PHP
Python

curl https://api.chatbotplatform.io/v1/bots/bot_123/integrations \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('https://api.chatbotplatform.io/v1/bots/bot_123/integrations', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const { data } = await response.json();

$response = Http::withToken('YOUR_API_KEY')
    ->get('https://api.chatbotplatform.io/v1/bots/bot_123/integrations');

$integrations = $response->json('data');

response = requests.get(
    'https://api.chatbotplatform.io/v1/bots/bot_123/integrations',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
integrations = response.json()['data']

Update an integration

cURL
JavaScript
PHP
Python

curl -X PATCH https://api.chatbotplatform.io/v1/integrations/int_123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "timeout": 60,
    "weight": 2
  }'

await fetch('https://api.chatbotplatform.io/v1/integrations/int_123', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    timeout: 60,
    weight: 2
  })
});

Http::withToken('YOUR_API_KEY')
    ->patch('https://api.chatbotplatform.io/v1/integrations/int_123', [
        'timeout' => 60,
        'weight' => 2
    ]);

requests.patch(
    'https://api.chatbotplatform.io/v1/integrations/int_123',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={'timeout': 60, 'weight': 2}
)

Complete API Reference

View the full API specification with all endpoints, parameters, and response schemas.

Overview

Creating an Integration

Request Payload Format

Messages Array

Expected Response

Integration Types

OpenAI Compatible

Anthropic (Claude)

Custom Backend

Fallback Integrations

Webhook Setup

A/B Testing

Custom Headers

Testing Your Integration

Troubleshooting

Timeout Errors

Authentication Errors

Invalid Response Format

API Access

Complete API Reference

Next Steps

Webhook Setup Guide

A/B Testing

Documentation Index

​Overview

​Creating an Integration

​Request Payload Format

​Messages Array

​Expected Response

​Integration Types

​OpenAI Compatible

​Anthropic (Claude)

​Custom Backend

​Fallback Integrations

​Related Topics

Webhook Setup

A/B Testing

Custom Headers

​Testing Your Integration

​Troubleshooting

​Timeout Errors

​Authentication Errors

​Invalid Response Format

​API Access

Complete API Reference

​Next Steps

Webhook Setup Guide

A/B Testing

Overview

Creating an Integration

Request Payload Format

Messages Array

Expected Response

Integration Types

OpenAI Compatible

Anthropic (Claude)

Custom Backend

Fallback Integrations

Related Topics

Testing Your Integration

Troubleshooting

Timeout Errors

Authentication Errors

Invalid Response Format

API Access

Next Steps