Bot Response Templates

Mapping JSON objects to Nimbus Parameters

By using Response Templates you can make sure to map the response your Bots get to map them properly in your Workflows. Bot Response Templates are part of the Nimbus Virtual User configuration.

Configuring Bot Response Templates

Field Description
Name Name of the Bot Response Template as it appears in Nimbus lists and selections.
Organization Unit Determines where the Bot Response Template will be available for selection.
Description Description of the Bot Response Template, used in Nimbus listings and UI areas.

BEFORE YOU START:

  • JSON Mapping: For the mappings to work you need to configure and inspect the JSON output of your Bots and their associated API. 
    💡 We have prepared an example below to illustrate the “M365 CoPilot Direct Line” case.
  • Application in Nimbus: The entire set of each Bot choice, Request- and Response Template is collected within a Virtual User configuration. The mapping is essential for the “Add Virtual User” Conversation Handling Activity to function as intended within your Workflows.
 

System Field Mapping

This section allows to map generated Bot answers to Nimbus variables.

☝IMPORTANT: All mappings below must be formatted in JSONPath syntax. Other formats or syntax errors will be rejected.

 
Field Description
Answer Raw

Identifies where in the response the raw (unformatted) answer value from the Bot can be found. 

✅ Necessary related action: Nimbus will use this answer for “Text to Speech” interpretation as input for the “Add Virtual User” Conversation Handling Activity


☝ Mandatory: Without this mapping there will be no audible dialogue coming from the bot.

💡This field holds the raw response generated by Bots, prior to any formatting or refinement. The goal is to allow easier text parsing for speech processing.

Exit

Identifies where in the response the exit value from the Bot can be found. 

✅ Necessary related action: Nimbus will take any value for answer validation within the “Add Virtual User” Conversation Handling Activity. The value can either be a raw answer message text or a trigger event response with a specific, curated value


☝ Mandatory: Without this mapping the “Add Virtual User” Conversation Handling Activity will get no (proper) answer to validate (using Regular Expressions). 

💡 An example JSON response explaining the mapping and validation can be found below.

Answer Formatted 

(optional)

Identifies where in the response the formatted answer value can be found.


💡Formatted answers can include HTML adjustments for readability, making it more User-friendly compared to the raw answer, but also harder to parse in further processing.

Custom Field Mapping

Field Description
Custom Parameter

Allows to map Nimbus Custom Parameters to the JSON response path.

✅ Precondition: You need to have an Organization Unit specified above for this list to show any Parameters 


💡Examples: 

$['text']
$['value']
$['locale']
$['choice']
etc ... 

Examples

Copilot - JSON Examples

Example for Copilot DirectLine - JSON Examples

The following JSON is returned from M365 CoPilot Direct Line 3.0, which is the default configuration of external Bots in Nimbus.

Message JSON

{
	"type": "message",
	"id": "5ZASDrgTOO0GtNlVtdgEE2-uk|0000021",
	"timestamp": "2025-05-20T20:31:01.9981516Z",
	"serviceUrl": "https://directline.botframework.com/",
	"channelId": "directline",
	"from": {
		"id": "user1"
	},
	"conversation": {
		"id": "5ZASDrgTOO0GtNlVtdgEE2-uk"
	},
	"locale": "en-EN",
	"text": "hello, bot"
}

🧠Important to note in this response is the value written into text. When you use this value in your Bot Response Templates, make sure to anticipate and parse longer text using Regular Expressions.

 
 

Event JSON

{
  "type": "event",
  "id": "IG7NO2Am5RlIHU0Ufa3pEr-eu|0000005",
  "timestamp": "2025-07-04T11:26:07.9037389Z",
  "channelId": "directline",
  "from": {
	"id": "ca1f129e-77d9-1f5a-e4d4-83bdb379b763",
	"name": "Agent 1",
	"role": "bot"
  },
  "conversation": {
	"id": "IG7NO2Am5RlIHU0Ufa3pEr-eu"
  },
  "membersAdded": [],
  "membersRemoved": [],
  "reactionsAdded": [],
  "reactionsRemoved": [],
  "locale": "en-EN",
  "attachments": [],
  "entities": [],
  "channelData": "{\"data\":\"mydata\",\"event\":\"mycustomevent\",\"exit\":false,\"topic\":null}",
  "replyToId": "IG7NO2Am5RlIHU0Ufa3pEr-eu|0000000",
  "value": "Handover",
  "name": "Exit",
  "listenFor": [],
  "textHighlights": []
}

🧠Important to note in this response is name “Exit” and the value “Handover”. Note that Nimbus is only interested in the value by parsing the field contents using Regular Expressions. The “Exit” field name is just easier to remember the mapping.

 
 

Copilot - Custom and System Field Mapping

Example: Copilot DirectLine - System Field Mapping 

💡In the following we want to focus our attention to the values of “text” and “value” of the Copilot API JSON response. 

As Nimbus identifies parameter with a $-sign, you can map the response as follows:

  1. Into the field Answer Raw map your type: $['text'].
     
  2. Using “Copilot” Topics: 
    1. If are not working with Topics in Copilot, map your bot response $['text'] "hello, bot" in our example above – to the Exit field in Nimbus
      ☝Note: that this raw text can be quite long and contain a lot of “extra fluff", so your Regular Expressions need to be complex enough to catch the response you are looking for.
    2. If you are working with Topics in Copilot, map the Exit to $['value'] - “Handover” in our example aboveto the Exit field in Nimbus
      💡Good to know: Copilot topics trigger controlled responses can be followed with an event activity. The event consists of a name – e.g. “Exit” in our example above – and a value . Nimbus is exclusively interested in the value portion, the name 
  3. The “Exit” field will use any values, e.g. $['value'] or $['text'] for the “Exit” condition check in your Conversation Handling Activities  > “Add Virtual User” activity. Regular Regular Expressions can be used to find the necessary words in a response, e.g. our “Handover” phrase.
Exit validation via Regex within the “Add Virtual User” activity

Example: Copilot DirectLine - Custom Field Mapping

💡This part is optional, depending if you want to continue using the bot response for other purposes, e.g. for easier referencing in Nimbus Workflows or as Conversation Context.

  1. Map the $['text'] field to a Custom Parameter for later usage, e.g. within your Flow Actions.
  2. You can also map $['value'] from your Event activity if you want to work with the topic.
  3. Repeat this for any other JSON field / value pairs you want to map to parameters.
Example of mapping API JSON response text and values to Nimbus Parameter

Table of Contents