Customer API Integration Guide

Customer API Integration Guide

The Helpium Customer API lets you programmatically interact with the chat widget, identify customers, and manage conversations from your application.

Authentication

All Customer API requests require your workspace's API key sent as a header:

X-API-Key: your_widget_key_here

You can find your API key in Settings → Channels → Widget.

Base URL

All endpoints are prefixed with /api/customer. For example:

GET https://your-workspace.helpium.io/api/customer/widget/settings

Available Endpoints

Widget Settings

GET /api/customer/widget/settings

Returns your widget configuration including colors, position, greeting message, and business hours status.

Search Articles

POST /api/customer/search
Body: { "query": "how do I reset my password" }

Searches your knowledge base using AI-powered semantic search. Returns the most relevant articles.

AI Answer

POST /api/customer/search/answer
Body: { "query": "how do I reset my password" }

Returns an AI-generated answer based on your knowledge base articles.

Create Conversation

POST /api/customer/conversations
Body: { "message": "I need help with billing" }

Creates a new conversation and returns a widget token for subsequent messages.

Send Message

POST /api/customer/conversations/{token}/messages
Body: { "body": "Can you check my invoice?" }

Sends a message in an existing conversation.

Identify Customer

POST /api/customer/tracking/identify
Body: {
    "email": "customer@example.com",
    "name": "Jane Smith",
    "widget_token": "existing_conversation_token"
}

Links a customer identity to their conversations. This enables personalized support and conversation history across sessions.

Customer Identification with Bearer Tokens

For authenticated users in your app, you can pass a Sanctum bearer token during identification:

Helpium.identify({
    email: user.email,
    name: user.name,
    bearerToken: sanctumToken,
});

This enables AI Actions that need to access your application's API on behalf of the customer. The token is stored securely and sent as an Authorization: Bearer header when the AI calls your endpoints.

Rate Limits

API requests are rate-limited per workspace. See the API Rate Limits and Usage article for details.

Error Handling

All API errors return a consistent JSON format:

{
    "error": {
        "message": "Description of the error",
        "status": 422,
        "code": "invalid_input"
    }
}

Common error codes: unauthenticated (401), not_found (404), invalid_input (422), too_many_requests (429).