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

REST API

Use the REST API to integrate Sampan's AI chatbot into your backend, mobile app, or any server-side application. Authenticate with a secret key (sk_) and interact with your knowledge base programmatically.

The REST API requires the API Access feature on your plan. Secret keys (sk_) are used for authentication.

Authentication

All API requests require a secret key passed in the x-api-key header. You can create secret keys from the Widget Keys page in your dashboard.

bash
curl https://api.sampan.club/api/v1/chat \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_your_secret_key_here" \
  -d '{"query": "Hello"}'

You can also use the Authorization: Bearer header as an alternative.

bash
curl https://api.sampan.club/api/v1/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_your_secret_key_here" \
  -d '{"query": "Hello"}'

Secret keys are shown only once at creation. Store them securely. Never expose them in client-side code.

Endpoints

POST /api/v1/chat

Send a message to the AI chatbot and receive a response based on your knowledge base.

json
// Request
POST /api/v1/chat
Content-Type: application/json
x-api-key: sk_your_secret_key_here

{
  "query": "What are your business hours?",
  "sessionId": "optional-session-id"
}

// Response
{
  "answer": "Our business hours are Monday to Friday, 9am to 5pm.",
  "sessionId": "session-1234567890-abc",
  "sources": [
    {
      "retrievedReferences": [
        {
          "content": "Business hours: Mon-Fri 9am-5pm...",
          "location": "faq/hours.md",
          "metadata": {
            "relevanceScore": 0.85,
            "title": "Business Hours"
          }
        }
      ]
    }
  ],
  "shouldEscalate": false,
  "suggestedFollowUps": [
    "Do you offer weekend support?",
    "How can I reach you after hours?"
  ]
}
GET /api/v1/config

Retrieve the widget configuration for your key. Useful for fetching bot name, colors, and settings.

json
// Request
GET /api/v1/config
x-api-key: sk_your_secret_key_here

// Response
{
  "widgetKey": "sk_a1b2c3d4",
  "widgetKeyId": "abc-123",
  "organisationId": "org-456",
  "botName": "Support Bot",
  "welcomeMessage": "Hi! How can I help you today?",
  "primaryColor": "#10b981",
  "position": "right",
  "logoUrl": null,
  "iconUrl": null,
  "whiteLabel": false
}

Session Management

Use the sessionId to maintain conversation context across multiple messages. If you don't provide a sessionId, a new session is created automatically. The response includes the sessionId — pass it back in subsequent requests to continue the conversation.

javascript
// First message — no sessionId
const res1 = await fetch('/api/v1/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'x-api-key': 'sk_...' },
  body: JSON.stringify({ query: 'What plans do you offer?' })
});
const data1 = await res1.json();
const sessionId = data1.sessionId;

// Follow-up — pass sessionId for context
const res2 = await fetch('/api/v1/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'x-api-key': 'sk_...' },
  body: JSON.stringify({ query: 'Which one is best for startups?', sessionId })
});

Public vs Secret Keys

Public Keys (wk_)

Designed for browser-based widgets. Domain restrictions are enforced — the key only works from your configured domains. The full key is stored and visible in your dashboard.

Secret Keys (sk_)

Designed for server-to-server integrations. No domain restrictions. The full key is shown only once at creation — only a hash is stored. Sources are included in the response so your backend can process them.

Rate Limits & Usage

API requests count toward your plan's monthly conversation limit. Each unique session counts as one conversation. If you exceed your limit and overage hard stop is enabled, requests will return a 429 status.

Error Responses

json
// 401 — Invalid or missing API key
{ "error": "Invalid API key" }

// 403 — Feature not available on your plan
{ "error": "REST API access is not available on your current plan. Please upgrade." }

// 429 — Rate limit or quota exceeded
{ "error": "Usage limit exceeded" }

// 500 — Internal server error
{ "error": "Internal server error" }

Ready to transform your customer experience?

Join businesses already using Sampan to serve customers 24/7 and boost revenue with AI.

sampan.club

AI-powered customer service for businesses.

SAMPAN TECH
202603046389 (003825593-A)

Product

© 2026 SAMPAN TECH, trading as Sampan Club (sampan.club). All rights reserved.