Docs>Developer>Webchat API

Webchat API Reference

API Reference

Overview

The VersanaCX Webchat API powers our embeddable chat widget, providing real-time messaging, configuration retrieval, and session management. You can use these endpoints to build a headless, custom integration or programmatically interact with a tenant's widget configuration.

Authentication

The Webchat API employs a two-tiered authentication system depending on the endpoint's purpose:

  • Public Key (pk): Used for initializing the widget and retrieving basic configuration. This is exposed safely in your frontend code.
  • Session Token: Returned upon successful initialization and required for all subsequent conversational actions (fetching messages, sending replies). Treat this token securely as it maps directly to an active visitor session.

Endpoints

GET
/webchat/config

Returns the widget configuration including branding, availability status, and triggers. No active session is required. Cached for 60s.

Query Parameters

  • pk (string, required): Your tenant's public key.

Example Response

{
  "branding": {
    "primaryColor": "#10A37F",
    "position": "bottom-right"
  },
  "isAvailable": true,
  "availabilityMode": "business_hours"
}
POST
/webchat/start

Initializes a new webchat session or resumes an existing one if a visitor token is provided.

Body Parameters

  • publicKey (string, required): Your tenant's public key.
  • visitorToken (string, optional): Rehydrates a previous visitor's session.

Example Response

{
  "sessionToken": "sess_12345abcde",
  "visitorToken": "vis_98765vwxyz"
}
GET
/webchat/messages

Fetch message history for the active session. Supports cursor-based pagination.

Query Parameters

  • sessionToken (string, required): The active session token.
  • afterCreatedAt (string, optional): Fetch messages created after this ISO timestamp.
  • afterId (string, optional): Used alongside afterCreatedAt for exact cursor pagination.
POST
/webchat/send-message

Sends a new message from the visitor to the tenant's inbox.

Body Parameters

  • sessionToken (string, required): The active session token.
  • message (string, required): The plaintext message body.

Example Response

{
  "success": true,
  "messageId": "msg_0011223344"
}

Rate Limits

To protect the integrity and availability of the VersanaCX platform, the following rate limits are strictly enforced on all public webchat APIs:

EndpointLimitWindow / Scope
/webchat/start10 requestsPer hour, per IP Address
/webchat/send-message60 requestsPer hour, per IP Address
/webchat/send-message30 requestsPer minute, per Session Token

Widget Embed

If you prefer not to build a custom UI, you can embed our pre-built React widget directly into your application using a simple script tag. Simply replace YOUR_PUBLIC_KEY with your actual tenant key found in the Dashboard Settings.

<!-- Place this before the closing </body> tag -->
<script src="https://cdn.versanacx.com/widget.js" data-pk="YOUR_PUBLIC_KEY" defer></script>

Availability Modes

The /webchat/config endpoint returns an isAvailable boolean flag that represents whether the chat should accept incoming conversations. This flag is dynamically computed based on the tenant's chosen Availability Mode:

  • Always Available (always): The widget remains online 24/7. isAvailable is consistently true.
  • Business Hours (business_hours): The widget automatically toggles availability based on the timezone-aware schedule configured in the dashboard.
  • Offline (offline): The widget is forcibly taken offline. isAvailable will return false, usually prompting the widget to switch to a contact form or hide entirely.