Custom Backend Integration

Connect your widget to any custom API or backend service using webhooks and HTTP requests.

Overview

ChatWidgetPro can connect to any webhook-compatible backend. When a user sends a message, the widget makes an HTTP POST request to your specified URL with the message payload.

What You Need

A publicly accessible HTTPS endpoint that accepts POST requests and returns JSON responses.

Basic Setup

Configure Webhook URL

Set your webhook URL in the widget editor:

Security

In direct mode, the webhook URL is visible in browser network requests. Use managed mode or authentication tokens for sensitive integrations.

Request Format

Your endpoint will receive this payload:

Response Format

Your endpoint should return JSON in this format:

Simple Response

You can also return just a plain string: `"Bot's response message"`. The widget will handle it correctly.

Backend Examples

Node.js / Express

Python / Flask

PHP

Advanced Features

Context Management

Maintain conversation context across messages:

Rich Responses

Return structured responses with buttons, cards, and more:

File Handling

Process uploaded files from users:

AI Integration

Integrate with OpenAI, Anthropic, or other AI services:

Error Handling

Status Codes

Use appropriate HTTP status codes:

200 OK: Successful response
400 Bad Request: Invalid input from widget
401 Unauthorized: Authentication failed
429 Too Many Requests: Rate limit exceeded
500 Internal Server Error: Server-side error
503 Service Unavailable: Temporary outage

Error Response Format

Timeout Handling

Configure timeouts for slow responses:

Security Best Practices

HTTPS Only: Always use HTTPS for webhook URLs
Authentication: Require API keys or bearer tokens
Input Validation: Validate and sanitize all inputs
Rate Limiting: Implement rate limits per session/IP
CORS Configuration: Set appropriate CORS headers
Request Signing: Verify requests come from your widget
Logging: Log requests for security monitoring

Never Trust Client Input

Always validate and sanitize data from the widget. Treat all input as potentially malicious.

Testing Your Integration

Test Tools

Use these tools to test your webhook:

Postman: Send test requests manually
curl: Command-line testing
Widget Test Mode: Built-in testing in the editor
ngrok: Expose localhost for testing

Example Test Request

Next: Webhook Configuration

Learn advanced webhook configuration options and payload customization.

Webhook Configuration →