Documentation
Chat
- Getting Started
- Installation
- Core Concepts
- Escalation System
- Widget Keys
- Secret Keys (sk_)
- REST API
- Channels & Integrations
- Messaging Platform API
Voice
- Voice Agent
- Setup Guide
- Phone Numbers
- Outbound Campaigns
Platform
- Billing & Pricing
- Glossary
- FAQ
Channels & Integrations
Connect your Sampan chatbot to messaging platforms like WhatsApp, Messenger, Instagram, and Telegram. Each channel can be configured independently with its own routing mode, credentials, and AI settings.
Available Channels
Connect a WhatsApp Business account to receive and respond to customer messages. Requires the WhatsApp Integration feature on your plan.
- Requires a Meta Business App with WhatsApp Cloud API access
- You'll need: Phone Number ID, Access Token, and optionally a Business Account ID
- Supports text, image, document, and location messages
- Webhook signature validation ensures message authenticity
Messenger
Connect a Facebook Page to handle customer conversations through Messenger. Requires the Messenger Integration feature.
- Link your Facebook Page via the Meta Business dashboard
- You'll need: Page ID and a long-lived Page Access Token
- Messages are received via Meta's webhook system
Handle DMs from your Instagram Professional Account. Requires the Instagram Integration feature.
- Your Instagram account must be a Professional Account linked to a Facebook Page
- You'll need: Instagram Account ID and the linked Page Access Token
- Uses the same Meta webhook infrastructure as Messenger
Telegram
Connect a Telegram bot to your workspace. Requires the Telegram Integration feature.
- Create a bot via @BotFather on Telegram
- You'll need: the Bot Token provided by BotFather
- Sampan sets the webhook automatically when you save the configuration
- No app review or approval process required
Routing Modes
Each channel can be configured with a routing mode that determines how inbound messages are processed.
Chatbot
AI auto-replies using your knowledge base. This is the default mode and matches the behavior of the web widget.
Passthrough
Messages are forwarded to your webhook URL without AI processing. Use this when you want full control over responses from your own backend.
Hybrid
AI replies first, but if confidence is low or escalation is triggered, the message is also forwarded to your webhook. Best of both worlds.
Inbox Only
Messages are stored in the conversation inbox but no reply is sent and no webhook is called. Useful for monitoring or manual review workflows.
Passthrough and Hybrid modes require a valid HTTPS webhook URL. Sampan signs webhook payloads with HMAC-SHA256 so you can verify authenticity.
Setting Up a Channel
- Go to Channels in your dashboard sidebar
- Click "Add Channel" and select the platform
- Enter the required credentials for that platform
- Choose a routing mode (Chatbot, Passthrough, Hybrid, or Inbox Only)
- If using Passthrough or Hybrid, enter your webhook URL
- Toggle AI Chatbot Enabled if you want the bot to respond
- Save the configuration
Webhook Delivery
When using Passthrough or Hybrid routing, Sampan delivers messages to your webhook URL with the following guarantees:
- Payloads are signed with HMAC-SHA256 using your channel's webhook secret
- The X-Sampan-Signature header contains the hex-encoded signature
- The X-Sampan-Timestamp header contains a Unix timestamp for replay prevention
- Failed deliveries are retried 3 times with exponential backoff (1s, 4s, 16s)
- After all retries fail, the payload is stored in a dead-letter queue visible in your dashboard
Feature Flags
Each channel requires a specific feature flag on your plan. If the feature isn't available, the channel type won't appear in the Channels page.
whatsappIntegration
Messenger
messengerIntegration
instagramIntegration
Telegram
telegramIntegration
Messaging API
apiAccess
