Druid Generic Chat

The Druid Generic Chat channel provides a REST API-based integration that connects your proprietary web chat interface directly to the Druid Conversational Engine.

The Custom Web Chat channel is the preferred choice for organizations that want to leverage the Druid Conversational Engine while retaining complete ownership of the web chat interface and overall user experience.

Unlike the standard Druid Web Chat channel, which includes a ready-to-use chat widget and user interface, the Druid Generic Chat channel does not provide any front-end components. Instead, it exposes a set of REST messaging endpoints that enable your application to exchange text messages with a Druid AI Agent while giving you complete control over the user experience.

Interaction Mechanisms

The Druid Generic Chat channel supports two distinct communication mechanisms to facilitate message exchanges between your custom front-end interface and the Conversational Engine. Depending on your system design and responsiveness criteria, you can implement either a synchronous approach or an asynchronous polling cycle to manage the user experience.

Synchronous Request-Response (Default)

In this mode, when a user sends a message through your proprietary chat UI, your backend client API forwards this input to Druid by calling the message delivery REST API (/messages). Your client API holds the HTTPS connection open with Druid while the Flow Engine processes the request. Once ready, all generated AI Agent replies are delivered back to your client API in the synchronous response payload, which then routes them back to the front-end interface.

Long Polling Mechanism (Asynchronous)

Long polling removes processing delays from the response delivery. When your backend client API transmits a user message to Druid via the REST API, Druid acknowledges receipt immediately with a fast confirmation payload and closes that initial connection.

Simultaneously, a background routine within your client API continuously requests updates from the dedicated Druid long polling endpoint (/getMessages). Druid holds this background connection open until a new message or event is generated by the Flow Engine. As soon as a response is ready, Druid delivers it to your client API, which pushes it to the custom UI. Your client API then immediately opens a new poll request to await subsequent messages.

The following sequence outlines how your backend client API handles communication between your custom front-end interface and Druid when using the long polling asynchronous model:

1. Session Initialization — A user opens your custom chat UI. Your backend client API initiates the session by calling the Druid Authorization API, authenticates the session, and receives a unique conversation token.
2. Fetch Welcome Message — Your client API immediately opens its first background long polling request using the /getMessages endpoint. Druid evaluates the start flow step and returns the initial welcome message payload, which your client API delivers to the UI.
3. Transmit User Input — When the user types and sends a message, your custom UI hands it to your backend client API, which forwards the text string to the Druid message endpoint. Druid responds to your client API with a fast confirmation receipt instead of making it wait for the full engine turn.
4. Poll for AI Agent Responses — Independent of the message submission, your backend client API maintains its background loop checking the long polling endpoint (/getMessages). Druid returns AI Agent responses one by one as they clear the processing engine. Your client API receives these payloads and pushes them directly to the custom UI.
5. Session Closure — When the user closes the chat or the session times out, your backend client API submits a termination signal to Druid, ending the active long polling loop and freeing up system resources.

Channel Configuration

The Druid Generic Chat channel is active by default in Druid.

To configure the channel:

1. In the Druid Portal, go to your AI Agent Settings, and click the Channels tab.
2. Search for 'Druid Generic Chat' and click on the card.
3. Copy the generated Authorize URL and AI Agent URL.
4. If your system architecture requires asynchronous delivery, toggle the Enable long polling option and copy the corresponding long poll endpoint.

During session execution, Druid automatically populates the following system fields:

• [[ChatUser]].ChannelId = "GenericChat"
• [[ChatUser]].UserId - Stores the unique client user identification string.

Druid API Reference

Use these specifications to connect your proprietary interface application layer to the Druid messaging engine.

Authorize

Establishes an anonymous session and provides the short-lived access token required for subsequent interactions.

Syntax

POST: *.druidplatform.com/api/services/app/Chat/AuthorizeAnonymousAsync

Request Body

{
   "botId": "<bot_id>",
   "queryString": "phone=<phone>",
   "channelId": "GenericChat"
}

Response

{
   "botId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "userId": "string",
   "conversationId": "string",
   "token": "string"
}

The returned bearer authorization token remains valid for exactly 1 hour from generation time.

Send Messages (Create Activity)

Transmits the text written by the user to the Druid messaging layer.

Syntax

POST: *.druidplatform.com/api/generic-chat/{botId}/messages

Request Header

In the request header, map the Authorize key to the bearer token obtained from the Authorize API. Use the Druid-specific CONCAT function for the Authorize key value with the following syntax:

CONCAT('Bearer ',[[Entity]].StringField)

Here, [[Entity]].StringField represents the field that stores the token obtained from the Authorize API.

Request Body

{
    "type": "message",
    "channelId": "GenericChat",
    "conversation": {
            "id": "<conversationId>"
    },
    "from": {
            "id": "<userId>"
    },
    "text": "<user says>",
    "timeout": 50
 }

The timeout parameter enables you to specify a duration in seconds for the system to wait for a response from the Flow Engine. If the Flow Engine doesn't respond within the configured timeout period, the system will log an error in the Conversation History.

Response

{
    "type": "message",
    "channelId": "GenericChat",
    "conversation": {
            "id": "<conversationId>"
    },
    "to": {
            "id": "<userId>"
    },
    "text": "<AI Agent response>",
}

Get Messages (Long Polling)

Retrieves messages asynchronously from the Druid AI Agent when the background long polling mechanism is enabled

Syntax

POST *.druidplatform.com/api/generic-chat/{botId}/messages/getMessages

Request Header

In the request header, map the Authorize key to the bearer token obtained from the Authorize API. Use the Druid-specific CONCAT function for the Authorize key value with the following syntax:

CONCAT('Bearer ',[[Entity]].StringField)

Here, [[Entity]].StringField represents the field that stores the token obtained from the Authorize API.

Request Body

{ 
  "conversationId": "your-conversation-id", 
  "mergedResponse": true 
} 

Parameters

Response

The response structure for getMessages is identical to the Responds with Message sections described for SendMessages API response, containing the AI Agent response or an event.