Webchat Sessions API

Overview

The Webchat Sessions API allows your server to create customer webchat sessions and refresh session tokens on behalf of your users. This is a server-to-server API designed for backend integrations where your application manages webchat sessions programmatically.

Prerequisites

To use the APIs, you need to have a token. Tokens can be generated by an admin at the setting section in Filum CX platform. Ensure you have the necessary permissions to access the admin settings for token generation.

APIs

Access the APIs via the endpoint: https://webchat.filum.ai/

POST /external/sessions

Summary

Create a webchat session for a customer. If the customer already has an active session (matched by user ID, phone, or email), the existing session is reused. Otherwise, a new session and conversation are created.

Header Parameters

Name	Description	Required	Schema
authorization	The authorization token to validate the request. The value should be in the format Bearer <your_api_token>	Yes	string
organization-id	The unique identifier of your organization	Yes	string
auth-type	The type of authorization used for the request. Must be token	Yes	string
content-type	Must be application/json	Yes	string

Request Body

Field	Type/Format	Required	Description
organizationId	string	Yes	The unique identifier of the organization
installedSourceId	integer	Yes	The ID of the installed source (webchat channel)
user	object	No	Information about the customer
user.id	string	No	The unique identifier of the customer in your system. If not provided, a temporary ID is generated (Webchat-<uuid>)
user.name	string	No	The name of the customer
user.email	string	No	The email of the customer
user.phone	string	No	The phone number of the customer

Request samples

{
  "organizationId": "org_12345",
  "installedSourceId": 1,
  "user": {
    "id": "customer_abc123",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "phone": "+84901234567"
  }
}

Responses

Code	Description	Content type
201	Successful Response	application/json
401	Unauthorized	application/json
422	Validation Error	application/json
429	Too Many Requests	application/json

201 Successful Response

Field	Type/Format	Required	Description
userId	string	Yes	The user ID for the session (provided or auto-generated)
sessionId	string	Yes	The unique identifier of the session
sessionToken	string	Yes	A JWT token for the session (expires in 1 hour)
sessionTokenExpiration	integer	Yes	The expiration timestamp of the session token (Unix epoch in seconds)
websocketUrl	string	Yes	The WebSocket URL for real-time messaging
conversationId	string	Yes	The unique identifier of the conversation

Response samples

{
  "userId": "customer_abc123",
  "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "sessionTokenExpiration": 1705315800,
  "websocketUrl": "wss://webchat-ws.filum.ai/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "conversationId": "507f1f77bcf86cd799439011"
}

---

POST /external/sessions/refresh

Summary

Refresh an existing session token. This extends the session expiration and returns a new JWT token. Use this to keep a session alive without creating a new one.

Header Parameters

Name	Description	Required	Schema
authorization	The authorization token to validate the request. The value should be in the format Bearer <your_api_token>	Yes	string
organization-id	The unique identifier of your organization	Yes	string
auth-type	The type of authorization used for the request. Must be token	Yes	string
content-type	Must be application/json	Yes	string

Request Body

Field	Type/Format	Required	Description
sessionId	string	Yes	The unique identifier of the session to refresh

Request samples

{
  "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Responses

Code	Description	Content type
200	Successful Response	application/json
401	Unauthorized	application/json
404	Session Not Found	application/json
422	Validation Error	application/json
429	Too Many Requests	application/json

200 Successful Response

Field	Type/Format	Required	Description
sessionToken	string	Yes	A new JWT token for the session (expires in 1 hour)
sessionTokenExpiration	integer	Yes	The expiration timestamp of the new session token (Unix epoch in seconds)

Response samples

{
  "sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "sessionTokenExpiration": 1705319400
}

Usage Examples

Example 1: Create a session for a known customer

curl -X POST "https://webchat.filum.ai/external/sessions" \
  -H "authorization: Bearer your_api_token_here" \
  -H "organization-id: your_organization_id_here" \
  -H "auth-type: token" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "org_12345",
    "installedSourceId": 1,
    "user": {
      "id": "customer_abc123",
      "name": "John Doe",
      "email": "john.doe@example.com",
      "phone": "+84901234567"
    }
  }'

Example 2: Create a session for an anonymous visitor

curl -X POST "https://webchat.filum.ai/external/sessions" \
  -H "authorization: Bearer your_api_token_here" \
  -H "organization-id: your_organization_id_here" \
  -H "auth-type: token" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "org_12345",
    "installedSourceId": 1
  }'

Example 3: Refresh a session token

curl -X POST "https://webchat.filum.ai/external/sessions/refresh" \
  -H "authorization: Bearer your_api_token_here" \
  -H "organization-id: your_organization_id_here" \
  -H "auth-type: token" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

Rate Limiting

The API endpoints have generous rate limits designed for server-to-server usage:

• Per second: 20 requests (configurable via EXTERNAL_WEBCHAT_PER_SEC_LIMIT)
• Per minute: 1,200 requests (configurable via EXTERNAL_WEBCHAT_PER_MIN_LIMIT)

If you exceed these limits, you will receive a 429 Too Many Requests response. Please implement appropriate retry logic with exponential backoff in your integration.

Error Responses

401 Unauthorized

Returned when the authorization token is missing, invalid, or the token does not have the required permissions.

{
  "message": "Unauthorized",
  "statusCode": 401
}

404 Not Found

Returned when the session ID does not exist (refresh endpoint only).

{
  "message": "Session not found",
  "statusCode": 404
}

422 Validation Error

Returned when the request body is missing required fields or contains invalid data.

{
  "message": ["organizationId should not be empty", "organizationId must be a string"],
  "error": "Bad Request",
  "statusCode": 400
}

429 Too Many Requests

{
  "statusCode": 429,
  "message": "ThrottlerException: Too Many Requests"
}