Assistant Configuration

The Assistant configuration allows to define direct- or service call templates. These templates either trigger when Nimbus users are being called directly (peer to peer) or via a service respectively.

💡 Call templates can be seen as "instruction" for Assistant to perform certain actions in specific order, such as:

  • Call external system's APIs – e.g. for caller lookup or for creating an incident ticket by sending Body, Header and Authorization requests to a ticketing system.
  • Open a website with context in your default browser – e.g. to show external caller information or have certain intranet pages readily at hand.
  • Open applications on the client PC, e.g. open a text editor or run a PowerShell script file with specific caller input parameters.

PRECONDITIONS

Enterprise Routing Note that Assistant templates are Enterprise Routing Nimbus Features. You may see and edit templates as administrators


🤔 Why are the privacy settings required?

Assistant requires detailed User State change events and their timestamps to display a detailed Nimbus-Availability (read: not just the the MS Teams presence). User state tracking is also required to use Not Available Reasons feature as each reason is tracked with a duration.


🤔 How does a Service / User Call Template differ from Nimbus Conversation Context?

Context is opening a specific browser URL for your service users (Agents) as soon as a call is distributed to them. Call Templates are far more conditionally versatile, allowing to interact with external systems via specific web requests (HTTP methods). This can also happen in the background and at specific points of a call, e.g. already when ringing. Templates can also be assigned user-specific to handle tasks in a specific order, e.g. by executing actions with parameters you specify in the template itself. This is described in further detail below.

 

The Assistant Templates

Service Call Templates are HTTP data handling requests methods sent out during specific trigger events. As their name implies they trigger on incoming service calls.

Configuring Service Call Templates

An Assistant service call template consists of the following elements:

Item Description
Name Name of your template as it appears in lists and selections
Organization Units

Determines where this template will be visible.

💡 Depending on how deep in the OU structure you place the template, services from different Organization Units may (not) see or use this template.

💡 You can assign multiple templates to a service, so a mixture of OU-specific templates an "general" tenant wide ones is possible.

Description Description of your template, appears in the list of templates.

Triggers

Item Description
Trigger Event
  • On Ringing - Performs the actions when the call is ringing
  • On Accepted - Performs the actions after you accepted the call.
Call Type

Nimbus only

💡 Option is currently locked on this default.

Call Origin

💡 These are "OR" concatenated, meaning that only one condition will need to apply to trigger the actions.

Inbound Internal Teams calls Calls from within the same tenant (e.g. your company domain).
Inbound External Teams calls Calls from outside your company domain.
Inbound PSTN calls Calls made via phone number (e.g. cellular or landline).
Outbound Service Calls Outbound Service Call / Call On Behalf, initiated by any Agent of that service.

✅ To take effect, the Service Call template needs to be applied in the Service Settings > Context tab.

Direct Call Templates are HTTP data handling requests methods sent out during specific trigger events. As their name implies they trigger on incoming direct calls to users.

Configuring Direct Call Templates

An Assistant direct call template consists of the following elements:

Item Description
Name Name of your template as it appears in lists and selections
Organization Units

Determines where this template will be visible.

💡 Depending on how deep in the OU structure you place the template, users from different Organization Units may (not) see or use this template.

💡 You can assign multiple templates to a user, so a mixture of OU-specific templates an "general" tenant wide ones is possible.

Description Description of your template, appears in the list of templates.

Triggers

Item Description
Trigger Event
  • On Ringing - Performs the actions when the call is ringing
  • On Accepted - Performs the actions after you accepted the call.
Call Type

Peer to Peer

💡 Option is currently locked on this default.

Call Origin

💡 These are "OR" concatenated, meaning that only one condition will need to apply to trigger the actions.

Inbound Internal Teams calls Calls from within the same tenant (e.g. your company domain)
Inbound External Teams calls Calls from outside your company domain.
Inbound PSTN calls Calls made via phone number.

✅ To take effect, the Direct Call template needs to be applied to individual users via the Assistant tab.

Creating Template actions

Template Actions

Each template type can consist of one or multiple data handling actions (HTTP Requests with header and body) which get executed in order.

Web Request action

General

Item Description
Name  Name of the action (as shown in listings)
Trigger ID Randomly generated ID, not changeable.
HTTP Method

The HTTP request method (GET, POST, POST-multipart/form-data, PUT, DELETE, PATCH)

💡 Only available when "Open in default browser is not selected".

Open in Default Browser

Opens the "URL" specified in your default browser as a tab. 

💡 Will ignore the HTTP Method setting and disable tabs accordingly.

URL (required)

URL to call or open depending on the options chosen above. 

🔍 Allows to include Custom Parameters as well as System Fields and Parameters as part of the URL.

BodyRequest (bodyForm)

✅ Enabled when HTTP Method "POST-multipart/form-data" is selected.

🔍 Allows to include Custom Parameters as well as System Fields and Parameters as part of the URL.

 
 

Headers

Key / Value header pairs for your request (specified in the "General" Tab).

Header Description
Key e.g. "Service UPN"
Value e.g. "$(Service.Upn)"

You can add Parameters and Context / System Fields to be part of this request header.

 
 

Authorization

Authentication details sent alongside with your request.

Item Description
Authentication
  • None
  • Basic
  • Scopes
  • Use Agent Token
Username / Password For basic authentication
Scopes 🔍 Uses -Scopes: See official microsoft documentation: https://learn.microsoft.com/en-us/azure/active-directory/roles/assign-roles-different-scopes
Use Agent Token 🔍 Use Agent Token: Allows to query Graph API with the token acquired for Nimbus Assistant, based on the Required App Permissions for the Assistant app (delegated permissions). Refer to our Use Case - Retrieving Microsoft Entra ID fields via Agent token for a usage example.
 
 

Response

Item Description
Wait  for response Waits for a response from the web request.
Wait Timeout

hh:mm:ss

Timeout to wait before the next action trigger starts.

 
 

Application action

General

Item Description
Name  Name of the action (as shown in listings)
Trigger ID Randomly generated ID, not changeable.
Path (required) URL to local script, batch file or application. ☝ UNC network paths are not supported.
Parameters 🔍 Allows to include Custom Parameters as well as System Fields and Parameters to be passed to the app specified in the path.
 
 

Response

Item Description
Wait for response Waits for a response from the application
Wait Timeout

hh:mm:ss

Timeout to wait before the next action trigger starts.

 
 

💡 Note that either action can be sorted in their order of execution via the handles. However, certain requests may create dependencies on each other which will cause a warning.

USING PARAMETERS IN YOUR TEMPLATE ACTIONS

The following parameters are supported within any action template:

Parameter Value Body URL Header Service Call Templates Direct Call Templates
Caller Display Name  $(Caller.DisplayName)

Supports these parameters the following action types:

  • Web Request action
  • Application action

Additionally you can add and mix your own custom Parameters and Context / System Fields into your request.

The parameters also work in Attendant - Service Transfer and Workflow-transfer scenarios. In these cases, the "Caller" name persists but the target "User." type parameters get updated.

🔍 Refer to Use Case - Chaining of Assistant requests for a hands-on example.

Supports these parameters the following action types:

  • Web Request action
  • Application action
Caller Id  $(Caller.Id)
Caller Tel Number  $(Caller.TelNumber)
Random Guid  $(Random.Guid)
User Display Name  $(User.DisplayName)
User Email  $(User.Email)
User Id  $(User.Id)
User Upn $(User.Upn)
Service UPN $(Service.Upn)

💡 NoteCaller refers to the customer side, User is the Agent/Member of the service.

 

Seeing it in Action

Enable Assistant and assign templates to users

Precondition: The Assistant license needs to assigned to a user for the settings to become visible. → See User Administration.

With the user license granted the Assistant-tab will become visible.

Assistant Context and Templates

Allows to assign Direct Call Templates to the user. Template actions trigger only on direct calls to this user in particular.

Element

 Description

Direct Call Templates

✅ Requires one or several configured Direct Call Templates to assign.

By clicking "+Add", template items under the same Organization Units (or higher) can be assigned to this user.

💡 Note that the templates will be called in the order they were added to the list. You can drag and drop template items to change the order.

🤔 Can I also assign Templates to Services?

Yes Service Call Templates are similar in design to Direct Call templates, but are configured separatedly and applied on service level.

Show me how to assign templates to a service

To assign templates that trigger on service call:

 

  1. You need define separate Service Call Templates first.
  2. Assign these service templates via the Service Settings > Context tab. → They will now trigger on a service call, in addition to any individual user templates.
 
 

🤔 What is Conversation Context and how is it different to Templates?

  • Conversation Context can be seen as "common ground" URLs to be opened for all service users within the Nimbus portal or Assistant. Context is applied via Extension Service Settings.
  • Compared to Context, Call Templates allow for more control and can also execute sequential actions in the background, invisible to users (e.g. to perform a ticket-creation while triggering a status update).
  • Context has no functional reliance or dependency to either service or direct call templates. Both features can be used in combination or standalone. ☝ However, be aware that your users might get duplicate websites opened when they are defined as context / templates and assigned on both service and user level.

Install Assistant and test the call

  1. Install Assistant on any machine of your choice. 
  2. Start up Assistant on that machine. 💡 We recommend putting the App on autostart.
  3. Log in with the Nimbus user configured in the previous step.
  4. Make a direct call to the user and see if the templates are triggered.