OpenDialog Docs
opendialog.aiStart BuildingTalk to an expert
  • GETTING STARTED
    • Introduction
    • Getting ready
    • Billing and plans
    • Quick Start AI Agents
      • Quick Start AI Agent
      • The "Start from Scratch" AI Agent
        • Chat Management Conversation
        • Welcome Conversation
        • Topic Conversation
        • Global No Match Conversation
        • Supporting LLM Actions
        • Semantic Classifier: Query Classifier
      • A Process Handling AI Agent
  • STEP BY STEP GUIDES
    • AI Agent Creation Overview
    • Add a new topic of discussion
    • Use knowledge sources via RAG
    • Adding a structured conversation
    • Add a 3rd party integration
    • Test and tweak your AI Agent
    • Publish your AI Agent
  • CORE CONCEPTS
    • OpenDialog Approach
      • Designing Conversational AI Agents
    • OpenDialog Platform
      • Scenarios
        • Conversations
        • Scenes
        • Turns and intents
      • Language Services
      • OpenDialog Account Management
        • Creating and managing users
        • Deleting OpenDialog account
        • Account Security
    • OpenDialog Conversation Engine
    • Contexts and attributes
      • Contexts
      • Attributes
      • Attribute Management
      • Conditions and operators
      • Composite Attributes
  • CREATE AI APPLICATIONS
    • Designing your application
      • Conversation Design
        • Conversational Patterns
          • Introduction to conversational patterns
          • Building robust assistants
            • Contextual help
            • Restart
            • End chat
            • Contextual and Global No Match
            • Contextual FAQ
          • Openings
            • Anatomy of an opening
            • Transactional openings
            • Additional information
          • Authentication
            • Components
            • Example dialog
            • Using in OpenDialog
          • Information collection
            • Components
            • Example dialog
            • Using in OpenDialog
            • Additional information
          • Recommendations
            • Components
            • Example dialog
            • Additional information
          • Extended telling
            • Components
            • Example dialog
            • Additional information
          • Repair
            • Types of repair
            • User request not understood
            • Example dialog
            • Additional information
          • Transfer
            • Components
            • Example dialog
            • Additional information
          • Closing
            • Components
            • Example dialog
            • Using in OpenDialog
            • Additional information
        • Best practices
          • Use Case
          • Subject Matter Expertise
          • Business Goals
          • User needs
            • Primary research
            • Secondary research
            • Outcome: user profile
          • Assistant personality
          • Sample dialogs
          • Conversation structure
          • API Integration Capabilities
          • NLU modeling
          • Testing strategy
          • The team
            • What does a conversation designer do
          • Select resources
      • Message Design
        • Message editor
        • Constructing Messages
        • Message Conditions
        • Messages best practices
        • Subsequent Messages - Virtual Intents
        • Using Attributes in Messages
        • Using Markdown in messages
        • Message Types
          • Text Message
          • Image Message
          • Button Message
          • Date Picker Message
          • Audio Message
          • Form Message
          • Full Page Message
          • Conversation Handover message
          • Autocomplete Message
          • Address Autocomplete Message
          • List Message
          • Rich Message
          • Location Message
          • E-Sign Message
          • File Upload Message
          • Meta Messages
            • Progress Bar Message
          • Attribute Message
      • Webchat Interface design
        • Webchat Interface Settings
        • Webchat Controls
      • Accessibility
      • Inclusive design
    • Leveraging Generative AI
      • Language Services
        • Semantic Intent Classifier
          • OpenAI
          • Azure
          • Google Gemini
          • Output attributes
        • Retrieval Augmented Generation
        • Example-based intent classification [Deprecated]
      • Interpreters
        • Available interpreters
          • OpenDialog interpreter
          • Amazon Lex interpreter
          • Google Dialogflow
            • Google Dialogflow interpreter
            • Google Dialogflow Knowledge Base
          • OpenAI interpreter
        • Using a language service interpreter
        • Interpreter Orchestration
        • Troubleshooting interpreters
      • LLM Actions
        • OpenAI
        • Azure OpenAI
        • Output attributes
        • Using conversation history (memory) in LLM actions
        • LLM Action Analytics
    • 3rd party Integrations in your application
      • Webhook actions
      • Actions from library
        • Freshdesk Action
        • Send to Email Action
        • Set Attributes Action
      • Conversation Hand-off
        • Chatwoot
    • Previewing your application
    • Launching your application
    • Monitoring your application
    • Debugging your application
    • Translating your application
    • FAQ
    • Troubleshooting and Common Problems
  • Developing With OpenDialog
    • Integrating with OpenDialog
    • Actions
      • Webhook actions
      • LLM actions
    • WebChat
      • Chat API
      • WebChat authentication
      • User Tracking
      • Load Webchat within page Element
      • How to enable JavaScript in your browser
      • SDK
        • Methods
        • Events
        • Custom Components
    • External APIs
  • Release Notes
    • Version 3 Upgrade Guide
    • Release Notes
Powered by GitBook
On this page
  • What's Changed?
  • Schedule
  • API changes
  • Security Features (v3.0.0+)
  • Python Example: Managing the Anonymous-Auth Cookie
  1. Release Notes

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:

  1. API definition updates

  2. 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):

Old endpoint
New endpoint

/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

import requests

# 1) Start a session so cookies persist
session = requests.Session()

# 2) First call: receive anonymous-auth cookie
first_resp = session.post(
    "https://your-tenant.cloud.opendialog.ai/chat-api/message",
    json={
        ...
    }
)
first_resp.raise_for_status()

# Cookie 'opendialog_anonymous_authentication_token' is now stored

# 3) Subsequent calls auto-include the cookie
followup_resp = session.post(
    "https://your-tenant.cloud.opendialog.ai/chat-api/message",
    json={
        ...
    }
)
followup_resp.raise_for_status()

print("Bot replied:", followup_resp.json())

If you need to manually handle the cookie, you can grab it from the session as follows

token = session.cookies["opendialog_anonymous_authentication_token"]
resp = requests.post(
    "https://your-tenant.cloud.opendialog.ai/chat-api/message",
    json=payload,
    cookies={"opendialog_anonymous_authentication_token": token}
)

PreviousExternal APIsNextRelease Notes

Last updated 12 days ago

Read more about in the section of these docs.

Beginning with version 3.0.0, we’re introducing several optional security controls across all Chat API endpoints to enhance the security of user interactions with OpenDialog. See on the Webchat Interface Settings page for full details.

Chat API
Security Settings