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
- Assistant needs to be set up on your Tenant first in order run your configured call templates. 🔍 Refer to Use Case - Setting up Assistant.
- Users need the Assistant App installed on their system to execute triggers defined within the templates described on this page.
- Each service using call templates needs a Enterprise Routing license. This will enable Context Tab in the Service Settings.
- Each user needs to be Assistant licensed in the User Administration . 🔍 This is also covered in Use Case - Setting up Assistant .
- Head to Tenant Administration >"Data Privacy" section and enable "Show User Time in State".
🤔 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 |
|
| 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 |
|
| 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 |
|
| 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:
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:
|
| 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) | ✅ | ✅ | ✅ |
💡 Note: Caller 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 serviceTo assign templates that trigger on service call:
🤔 What is Conversation Context and how is it different to Templates?
| |
Install Assistant and test the call
- Install Assistant on any machine of your choice.
- Start up Assistant on that machine. 💡 We recommend putting the App on autostart.
- Log in with the Nimbus user configured in the previous step.
- Make a direct call to the user and see if the templates are triggered.