Start Multiple DRUID Conversations

You can initiate multiple DRUID conversations simultaneously using the API endpoint /api/Druid/{botId}/StartFlowBulk. This feature is particularly useful when you need to start conversations with multiple users in a single API call.

Prerequisites

Contact DRUID Support to activate the Druid Endpoints service on your tenant and to generate a token.
Ensure that you have a DRUID Portal admin user account.

StartFlow API

The StartFlowFlow API starts a DRUID flow multiple times and transmits any specified data within the conversation context through the request body.

Important! The bot triggers the flow on the specified channel only when the user has initiated a conversation with the bot on that same channel.

Syntax

POST *.https://druidendpoints.druidplatform.com/api/Druid/{botId}/StartFlowBulk

To get the bot ID, select the desired bot and from the browser get the bot ID. It is placed between edit/ and /botdetails.

Authorization

To authenticate your request for DRUID Endpoints, ensure inclusion of the Bearer token. Obtain the token by generating a permanent token or utilizing the authentication endpoint. Refer to Webhooks for detailed instructions.

Remember to include the bearer token in the Authorization section of your request.

Request Body

Copy

{
  "items": [
    {
      "channelId": "string",
      "targetUserMasterId": "string",
      "targetConversationId": "string",
      "targetTenantUserId": "string",
      "entityContextData": "string",
      "flowUtterance": "string",
      "flowId": "string",
      "conversationLanguage": "string"
    },
    {
      "channelId": "string",
      "targetUserMasterId": "string",
      "targetConversationId": "string",
      "targetTenantUserId": "string",
      "entityContextData": "string",
      "flowUtterance": "string",
      "flowId": "string",
      "conversationLanguage": "string"
    }
  ]
}

Note: The request limit is 10,000 items. This means you can initiate up to 10,000 DRUID conversations simultaneously using the API.

Parameter	Data Type	Mandatory	Description
channelId	String	Yes	The ID of the channel where the bot initiates the conversation. Ensure to provide the name exactly as it is stored in [[ChatUser]].ChannelId.
targetConversationId	String	One of them is mandatory.	Enables you to start both authenticated and non-authenticated conversations. Hint: We recommend you to use it in the callback from a third-party application that has been initially started from a DRUID conversation. E.g., from DRUID you start an UiPath robot that will notify DRUID when the job/task has been completed.
targetUserMasterId	String		The unique identifier of an authenticated DRUID Portal user. Use it when you want to start a flow to a specific authenticated user. To get the Master User ID of a user, in the DRUID Portal, from the Administration menu, click Users, then select to edit the specific user. From the User Information tab, scroll-down and get the Master Id.
targetTenantUserId	String		The TenantUserId is a system entity field that is used by the system in the backend. You can retrieve it from [[ChatUser]].TenantUserId.
entityContextData	String	Yes	In the "entityContextData" object enter provide the data you want to send within the conversation context. Note: Ensure that the property names provided in 'contextData' match exactly with the DRUID entity field names. Additionally, be mindful of the bot's informational model. The property names in 'contextData' do not need to match exactly the referred entity name behind the field of type entity / entity list. For a clearer understanding of how the request should be structured, refer to the two examples provided below.
flowUtterance	String	One of them is mandatory.	The flow utterance. Note: Use flowUtterance instead of the flowId as it is much easier to identify a flow by utterance than by ID (assuming that the flow utterance is unique). If you move your bot from a testing environment to PROD, the flow ID will change while the flow utterance remains unchanged.
flowId	String	One of them is mandatory.	The flow ID.
conversationLanguage	String	No	Specify the language to start the conversation. Use the same language codes as [[ChatUser]].Language, like "en-US" for English (United States). Important! If the language is not one of the bot languages, the language code is incorrect, or not specified, the conversation will begin in the language the user used to interact with the bot on that channel.

Response

The request is put on a DRUID waiting queue and will be executed only when the conversation reaches the "Idle" mode.

Copy

{
    "message": "Druid Endpoint: StartFlow attempt successfully queued for execution",
    "isError": false
}

Error codes

401 - the access token is invalid.
404 - The syntax of the call is incorrect.
500 — Internal server error or a parameter in the contextData does not exist in DRUID. The response provides you with the error details.

Example: Starting conversations without sending data within the conversation context

In this example:

The bot id is 56ca1234-c5ea-480c-a8db-08d8d4b.
We will start the conversation with Id 12AA4SifAA2vBBB9BBBpw-eu in the WhatsApp Meta channel and the conversation with Id 33BB4SifFF2vCCC9BBBpw-eu in the MS Teams channel.
The entity [[Client]] is present within the conversation context.
The flow utterance is "update account".

Copy

Request

{
  "items": [
    {
    "botId": "56ca1234-c5ea-480c-a8db-08d8d4b",
    "channel": "meta-whatsapp",
    "targetConversationId": "12AA4SifAA2vBBB9BBBpw-eu",
    "entityContextData": {},
    "flowUtterance": "update account"
    },
    {
    "botId": "56ca1234-c5ea-480c-a8db-08d8d4b",
    "channel": "msteams",
    "targetConversationId": "33BB4SifFF2vCCC9BBBpw-eu",
    "entityContextData": {},
    "flowUtterance": "update account"
    }
  ]
}

Example: Starting conversations and sending data within the conversation context

In this example:

The bot id is 56ca1234-c5ea-480c-a8db-08d8d4b.
We will start conversations with the targetTenantUserId 3fa85f64-5717-4562-b3fc-2c963f66afa6 and the targetTenantUserId 5fa85f64-1983-4562-b3fc-2c963f88afa8 the in the MS Teams channel.
We will send a collection of contracts within the conversation context. In DRUID we have the entity [[Client]] which has:

two scalar fields: [[Client]].Name and [[Client]].Age.
a field of type entity, [[Client]].PageInfo referencing the system entity [[PageInfo]] that stores client-side page information from web views.
a field of type entity list, [[Client]].Contracts that stores a collection of contracts.

The flow utterance is "add contracts".

Copy

Request Body

{
  "items": [
{
    "botId": "56ca1234-c5ea-480c-a8db-08d8d4b",
    "channelId": "msteams",
    "targetTenantUserId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "entityContextData": {
        "Client": {
            "Name": "John Doe",
            "Age": 25,
            "PageInfo": {
                "NumberOfRecords": 10,
                "PageStartIndex": 0
            },
            "Contract": [
                {
                    "CNumber": 1,
                    "Title": "Cession"
                },
                {
                    "CNumber": 2,
                    "Title": "Loan"
                }
            ]
        }
    },
    "flowUtterance": "add contracts"
},
{
    "botId": "56ca1234-c5ea-480c-a8db-08d8d4b",
    "channelId": "msteams",
    "targetTenantUserId": "5fa85f64-1983-4562-b3fc-2c963f88afa8",
    "entityContextData": {
        "Client": {
            "Name": "Jane Doe",
            "Age": 32,
            "PageInfo": {
                "NumberOfRecords": 10,
                "PageStartIndex": 0
            },
            "Contract": [
                {
                    "CNumber": 1,
                    "Title": "Car Leasing"
                },
                {
                    "CNumber": 2,
                    "Title": "Casco"
                }
            ]
        }
    },
    "flowUtterance": "add contracts"
}
  ]
}