Version 3 Upgrade Guide
The latest release of OpenDialog introduces new security features and updates several Webchat API endpoints that may require action on your part. This page outlines what’s changed and helps you decide if you need to do anything.
What's Changed?
The changes fall into two categories:
API definition updates
Configurable security features you can enable for existing scenarios
NB: If you use the OpenDialog Webchat widget or the ChatUI SDK, no changes are required. Only custom applications that call the OpenDialog Chat API directly will be affected.
Schedule
We've split the updates into two separate releases to allow customers time to update their applications in line with the new requirements:
2.17.0 “Jabbah” — 22 May 2025
Supports both old and new API endpoints
Does not include security features
3.0.0 “Jishui” — 12 June 2025
Removes old-style Chat API endpoints
Enforces new required headers (see below)
API changes
Note: Only direct Chat API integrations are affected. Webchat embeds and ChatUI SDK users can ignore these changes.
1. Updated endpoint names
You must update your application calls as follows (request bodies and parameters are unchanged):
/incoming/chatApi
/chat-api/message
/chatApi-config
/chat-api/configuration
/user/{user_id}/history
/chat-api/history
/user/{user_id}/history/file
/chat-api/transcript
2. New required headers
All Chat API calls now require two headers. Missing headers will trigger HTTP 422 responses with error details.
OPENDIALOG-USER-ID
OPENDIALOG-SCENARIO-ID
(The request body stays the same; for /chat-api/message
you still need selected_scenario
, author
and user_id
in the JSON.)
3. Mandatory authorization header
Starting in 3.0.0, every Chat API endpoint must include the same authorization header used by /incoming/chatApi
. By default (unless you enable additional security options), this is your appKey
as documented in the Chat API guide.
Security Features (v3.0.0+)
Note:
Existing scenarios must opt in per feature.
New scenarios have these enabled by default.
This guide is split by integration type. If you’re unsure which applies, contact support.
1. Embedded Webchat Widget
If you embed via the snippet on the Webchat Interface Settings page:
CORS When enabled, whitelist all page URLs hosting the widget by adding them in the security settings tab in Webchat interface settings
Anonymous auth & CSRF Handled automatically by the widget; no action needed.
2. ChatUI SDK
For applications built with the OpenDialog ChatUI SDK:
CORS (Cross-Origin Resource Sharing) Whitelist your page URLs when CORS protection is turned on by adding them in the security settings tab in Webchat interface settings
CSRF (Cross-Site Request Fogery)
Requires browser-accessible cookies.
You must map a custom domain to your OpenDialog tenant. To set this up, please coordinate DNS + tenant mapping with OpenDialog support
We recommend leaving CSRF off during development whilst any custom domain mapping is set up
3. Direct Chat API Integration
If you call the Chat API directly, update your code as follows:
Anonymous Authentication
On first request, the API returns a per-user JWT in a cookie named
opendialog_anonymous_authentication_token
.All subsequent requests must include that cookie.
Anti-CSRF
CSRF is a browser-only threat. Disable it in your scenario settings if you aren’t in a browser context.
CORS
Browser-only protection. Ignore for server-to-server integrations.
Python Example: Managing the Anonymous-Auth Cookie
If you need to manually handle the cookie, you can grab it from the session as follows
Last updated