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
Messaging Platform API
Build your own chat experience using Sampan as the messaging backend. The Messaging Platform API lets you send and receive messages between participants, manage conversations, and optionally layer in AI chatbot responses — all through a simple REST API.
The Messaging Platform API is separate from the Chatbot REST API (/api/v1/chat). The chatbot API is for AI-only interactions. The Messaging Platform API supports multi-participant conversations with optional AI.
Overview
Think of Sampan as a messaging backend (like Twilio or SendBird) that your application connects to. Your users send messages through your app, Sampan stores and routes them, and the other participant receives them in real-time.
- Create conversations between participants
- Send and receive messages via REST API
- Get real-time delivery via webhooks or AppSync subscriptions
- Optionally enable AI chatbot to auto-reply
- Connect external channels (WhatsApp, Telegram, etc.) into the same conversation
- Full conversation history with cursor-based pagination
Authentication
The Messaging Platform API uses its own API keys, managed from the API Keys page in your dashboard. These are separate from widget keys (wk_/sk_).
curl https://api.sampan.club/messages \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk_live_your_api_key_here" \
-d '{
"participantId": "user-123",
"content": "Hello!",
"contentType": "text"
}'Endpoints
POST /messages
Send a message. If no conversationId is provided, a new conversation is created.
// Request
POST /messages
Authorization: Bearer sk_live_...
{
"participantId": "user-123",
"content": "Hey, I need help with my order",
"contentType": "text",
"conversationId": "conv-456" // optional — omit to create new conversation
}
// Response
{
"messageId": "msg-789",
"conversationId": "conv-456",
"timestamp": "2025-01-15T10:30:00Z",
"aiReply": { // only if AI is enabled
"content": "I'd be happy to help with your order...",
"confidence": 0.82
}
}GET /conversations/:id/messages
Retrieve messages for a conversation with cursor-based pagination.
// Request
GET /conversations/conv-456/messages?limit=50&cursor=msg-100
Authorization: Bearer sk_live_...
// Response
{
"messages": [
{
"messageId": "msg-101",
"participantId": "user-123",
"content": "Hey, I need help",
"contentType": "text",
"timestamp": "2025-01-15T10:30:00Z",
"role": "user"
},
{
"messageId": "msg-102",
"participantId": "assistant",
"content": "I'd be happy to help...",
"contentType": "text",
"timestamp": "2025-01-15T10:30:01Z",
"role": "assistant"
}
],
"nextCursor": "msg-150",
"hasMore": true
}POST /conversations
Create a new conversation explicitly.
// Request
POST /conversations
Authorization: Bearer sk_live_...
{
"participantId": "user-123",
"metadata": {
"source": "mobile-app",
"department": "support"
}
}
// Response
{
"conversationId": "conv-789",
"createdAt": "2025-01-15T10:30:00Z"
}Routing Modes
The Messaging API channel supports the same routing modes as other channels. Configure this from the Channels page by adding a "Messaging API" channel.
Chatbot
AI auto-replies to every message. Your app receives the AI response in the API response body.
Passthrough
Messages are forwarded to your webhook URL. No AI. Your backend handles all replies by calling POST /messages.
Hybrid
AI replies first. If confidence is low, the message is also forwarded to your webhook so a human can take over.
Inbox Only
Messages are stored but no reply is generated. Pull messages with GET /conversations/:id/messages.
Real-Time Delivery
Receive messages in real-time through two mechanisms:
Webhooks
Configure a webhook URL on your Messaging API channel. Sampan POSTs every new message to your endpoint, signed with HMAC-SHA256.
AppSync Subscriptions
For web and mobile clients, subscribe to real-time updates via AppSync. Messages are published to a subscription keyed by conversationId.
Example: Building a Chat App
Here's how you'd use the Messaging Platform API to build a simple chat between two users:
// 1. User A starts a conversation
const { conversationId } = await createConversation('user-a');
// 2. User A sends a message
await sendMessage({
conversationId,
participantId: 'user-a',
content: 'Hey, are you available?'
});
// 3. Your webhook receives the message
// POST https://your-server.com/webhook
// { event: "message.created", data: { conversationId, participantId: "user-a", content: "Hey..." } }
// 4. Your server notifies User B (via your own push/websocket)
// User B sees the message in their app
// 5. User B replies through your API
await sendMessage({
conversationId,
participantId: 'user-b',
content: 'Yes, what do you need?'
});
// 6. Your webhook receives User B's message
// You forward it to User A's clientThe AI chatbot is optional. Set aiEnabled to false on your channel config if you want pure human-to-human messaging. Set it to true and use Hybrid mode to have AI assist when humans are unavailable.
Knowledge Base API
If your plan includes the Client Knowledge Base feature, you can manage your knowledge base content programmatically.
- POST /kb — Add content to your knowledge base
- PUT /kb/:id — Update existing content
- DELETE /kb/:id — Remove content
- GET /kb — List all knowledge base content
All KB modifications are tracked in an audit log visible in your dashboard.
