Documentation

Everything you need to integrate ClawCustomer into your website.

Quick Start

Get up and running with ClawCustomer in 3 simple steps.

Create a Project

Sign up at app.clawcustomer.com and create a new project. Configure your AI assistant's personality, language, and knowledge base.

Get Your API Key

Navigate to Settings → API Keys in your dashboard. Copy your public key (pk_...). This key is safe to use in client-side code.

Add the Embed Code

Paste this snippet before the closing </body> tag on your website:

HTML

<script src="https://cdn.clawcustomer.com/widget.js"></script>
<script>
  ClawCustomer("init", {
    projectId: "your-project-id",
    apiKey: "pk_your_api_key"
  });
</script>

That's it! The chat widget will appear in the bottom-right corner of your website.

Installation

Script Tag (Recommended)

The simplest way to add ClawCustomer. Just include the script tag and it handles everything automatically.

HTML

<script src="https://cdn.clawcustomer.com/widget.js"></script>
<script>
  ClawCustomer("init", {
    projectId: "your-project-id",
    apiKey: "pk_your_api_key"
  });
</script>

npm Package (Advanced)

For React, Vue, Angular, or other framework-based projects:

Shell

npm install @clawcustomer/widget

JavaScript

import ClawCustomer from '@clawcustomer/widget';

ClawCustomer("init", {
  projectId: "your-project-id",
  apiKey: "pk_your_api_key"
});

Configuration

Customize the widget behavior and appearance with the following options:

JavaScript

ClawCustomer("init", {
  projectId: "your-project-id",     // Required - Your project ID
  apiKey: "pk_xxx",                  // Required - Your public API key
  theme: "light",                    // "light" | "dark" | "auto"
  primaryColor: "#4f46e5",           // Brand color for the widget
  position: "bottom-right",          // "bottom-right" | "bottom-left"
  welcomeMessage: "Hi! How can I help?",
  placeholder: "Type your message...",
  language: "en"                     // "en" | "zh" | "es" | "fr" | "de"
});

Option	Type	Default	Description
`projectId`	string	—	Required. Your project ID from the dashboard.
`apiKey`	string	—	Required. Your public API key (`pk_...`).
`theme`	string	"light"	Widget color theme. `"auto"` follows the user's system preference.
`primaryColor`	string	"#4f46e5"	Brand color used for buttons and accents.
`position`	string	"bottom-right"	Widget position on the page.
`welcomeMessage`	string	"Hi! How can I help?"	Initial greeting message shown when the widget opens.
`placeholder`	string	"Type your message..."	Input field placeholder text.
`language`	string	"en"	UI language. Supported: `en`, `zh`, `es`, `fr`, `de`.

API Reference

The ClawCustomer function accepts a command string and optional arguments.

`ClawCustomer("init", config)`

Initialize the widget with your project configuration. Must be called before any other command.

JavaScript

ClawCustomer("init", {
  projectId: "your-project-id",
  apiKey: "pk_your_api_key",
  theme: "auto"
});

`ClawCustomer("destroy")`

Remove the widget from the page and clean up all event listeners.

JavaScript

ClawCustomer("destroy");

`ClawCustomer("open")`

Programmatically open the chat window.

JavaScript

// Open chat when user clicks a custom button
document.getElementById("help-btn").addEventListener("click", () => {
  ClawCustomer("open");
});

`ClawCustomer("close")`

Close the chat window programmatically.

`ClawCustomer("identify", userInfo)`

Associate the current session with a known user. Call this after your user logs in.

JavaScript

ClawCustomer("identify", {
  userId: "user_12345",
  name: "Jane Doe",
  email: "jane@example.com"
});

`ClawCustomer("send", message)`

Send a message programmatically on behalf of the user.

JavaScript

ClawCustomer("send", "I need help with my order #12345");

REST API

For server-side integration, use the REST API. All requests require authentication via Bearer token.

HTTP Header

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

Base URL: https://api.clawcustomer.com/api/v1

POST /api/v1/chat

Send a message and receive an AI response.

Request

curl -X POST https://api.clawcustomer.com/api/v1/chat \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "proj_abc123",
    "message": "How do I reset my password?",
    "sessionId": "sess_xyz789",
    "userId": "user_456"
  }'

Response

{
  "sessionId": "sess_xyz789",
  "messageId": "msg_001",
  "response": "To reset your password, go to Settings > Security...",
  "timestamp": "2024-01-15T10:30:00Z",
  "processingTime": 245,
  "confidence": 0.95
}

GET /api/v1/chat/history

Retrieve chat history for a session.

Request

curl https://api.clawcustomer.com/api/v1/chat/history?sessionId=sess_xyz789 \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "sessionId": "sess_xyz789",
  "messages": [
    {
      "id": "msg_001",
      "role": "user",
      "content": "How do I reset my password?",
      "timestamp": "2024-01-15T10:30:00Z"
    },
    {
      "id": "msg_002",
      "role": "assistant",
      "content": "To reset your password...",
      "timestamp": "2024-01-15T10:30:01Z"
    }
  ]
}

POST /api/v1/chat/end

End a chat session with an optional satisfaction score.

Request

curl -X POST https://api.clawcustomer.com/api/v1/chat/end \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "sess_xyz789",
    "satisfaction": 5
  }'

Events & Callbacks

Listen to widget lifecycle events by passing callbacks during initialization.

JavaScript

ClawCustomer("init", {
  projectId: "your-project-id",
  apiKey: "pk_your_api_key",

  onReady: () => {
    console.log("Widget loaded and ready");
  },

  onOpen: () => {
    console.log("Chat window opened");
  },

  onClose: () => {
    console.log("Chat window closed");
  },

  onMessage: (message) => {
    console.log("New message:", message.content);
    console.log("From:", message.role); // "user" | "assistant"
  },

  onError: (error) => {
    console.error("Widget error:", error.code, error.message);
  }
});

Event	Arguments	Description
`onReady`	—	Fired when the widget has fully loaded.
`onOpen`	—	Fired when the chat window is opened.
`onClose`	—	Fired when the chat window is closed.
`onMessage`	`{ role, content }`	Fired when a new message is sent or received.
`onError`	`{ code, message }`	Fired when an error occurs (network, auth, etc.).

Customization

Theme Color

Set primaryColor to match your brand.

JavaScript

ClawCustomer("init", {
  projectId: "your-project-id",
  apiKey: "pk_your_api_key",
  primaryColor: "#e11d48"  // Rose
});

Custom Avatar & Title

Personalize the chat header with your brand name and avatar.

JavaScript

ClawCustomer("init", {
  projectId: "your-project-id",
  apiKey: "pk_your_api_key",
  title: "Acme Support",
  avatarUrl: "https://example.com/avatar.png"
});

CSS Variable Overrides

The widget uses Shadow DOM for style isolation. You can override CSS custom properties from outside:

CSS

clawcustomer-widget {
  --claw-primary: #e11d48;
  --claw-font-family: "Inter", sans-serif;
  --claw-border-radius: 12px;
  --claw-shadow: 0 8px 30px rgba(0, 0, 0, 0.12);
  --claw-header-bg: #1e1b4b;
  --claw-header-text: #ffffff;
  --claw-bubble-user-bg: #e11d48;
  --claw-bubble-user-text: #ffffff;
  --claw-bubble-bot-bg: #f3f4f6;
  --claw-bubble-bot-text: #111827;
}

Security

API Key Permissions

Public keys (pk_...) are safe to embed in client-side code. They can only initiate chat sessions and send messages for the associated project. They cannot access your dashboard, manage projects, or read other users' data.

CORS Configuration

By default, the widget API accepts requests from any origin. You can restrict allowed origins in Settings → Security to limit API access to your domains only.

Data Encryption

All data is encrypted in transit (TLS 1.3) and at rest (AES-256). Chat messages are stored in isolated tenant databases with strict access controls.

GDPR Compliance

ClawCustomer is fully GDPR compliant. You can configure data retention policies, enable cookie consent banners, and export or delete user data via the dashboard or REST API.

FAQ

Does the widget affect page load speed?

No. The widget script is loaded asynchronously and deferred. It weighs ~18KB gzipped and initializes after the page has finished loading, so it has zero impact on your Core Web Vitals.

Can I use ClawCustomer with a single-page application (SPA)?

Yes. The widget persists across route changes. If you need to reinitialize on navigation, call ClawCustomer("destroy") followed by ClawCustomer("init", config).

What languages does the AI support?

The AI can respond in any language. The language config option only controls the widget UI labels (buttons, placeholder text). The AI automatically detects the user's language and responds accordingly.

How do I train the AI on my business data?

Upload documents, FAQs, and product information to your project's Knowledge Base in the dashboard. The AI uses this data to provide accurate, context-aware responses. You can also use the REST API to programmatically manage your knowledge base.

What happens when the AI can't answer a question?

You can configure escalation rules in your project settings. When the AI detects it can't help, it can hand off to a human agent via Telegram, email, or your existing support system.