Microsoft Teams: Self-Service Assistant Bot

On this page

The Self-Service Assistant bot is a Microsoft Teams application hosted by Alloy Software. It is published in the Microsoft Teams store and talks to your Alloy Navigator API. Through the bot, people create and update tickets and approve or reject approval requests. What users do with the bot is described in Self-Service Assistant in Microsoft Teams.

The bot identifies a Teams user by matching the e-mail address of their Teams account to the primary e-mail address of a person in Alloy Navigator. Once the bot is added to Teams and connected to your API, Self Service Portal customers can therefore use it without any further setup.

The only part of the bot that ships with Alloy Navigator is one configuration record, TeamsBot, kept in the list of mobile applications. The record is not a mobile app; it only shares that list. You edit it in the Admin Center or in the Settings App. A new 2026.1 database created with the Default Workflow contains the record; see The record in the supplied configuration.

Before you begin

  • The Alloy Navigator API must be installed, reachable from the internet, and configured for access-token authentication. See API Settings.
  • Have the API URL at hand. The Web Configuration tool shows it, and the same value is stored in the API Link system macro, which you find in the Settings App under Workflow and Business Logic > Advanced > System Macros > Links. For system macros, see Macros Reference.
  • Have an Application account: the bot asks for its Application ID and secret when you connect it. The product generates both when the account is created, in the Admin Center on the Applications tab of Accounts and Roles or in the Settings App. See API Applications.
  • Adding the bot to Teams is done by a Microsoft 365 administrator. Allowing the bot in the Microsoft Teams admin center requires the Teams Administrator role.
  • The administrator who connects the bot to your API needs a person record in Alloy Navigator whose primary e-mail address is the e-mail address of their Teams account. One person can both add and connect the bot.

In the Admin Center

Edit the TeamsBot record

  1. Go to Services and Integrations > Mobile Applications.
  2. Open the TeamsBot registration.
  3. Change the configuration as described in The TeamsBot record, and save your changes.

The Mobile Applications page has no New command. To add a registration, select one existing registration and click Copy Item.

In the Settings App

Edit the TeamsBot record

  1. Go to Services > Mobile Applications.
  2. Select TeamsBot and click Edit. The Mobile Application [TeamsBot] dialog opens with these fields:
    • Application ID: the name of the record, TeamsBot.
    • Configuration: the XML document described in The TeamsBot record.
    • URL Mask: an optional mask. The API selects a mobile application configuration by its application name and this optional URL mask.
  3. Change the Configuration: text and save the dialog.

The list also offers New, Delete, Copy Item, and Export Selected Settings….

Back up and restore the record

  • To back up the record, select TeamsBot in the list and click Export Selected Settings….
  • To restore or add the record, choose Import Settings… from the main menu. Mobile application records travel in the export section Mobile Applications Configurations.

IMPORTANT: A manual Import Settings… replaces the TeamsBot configuration with the one in the file, so your changes to the portal URL, the command switches, and the messages are lost. Export the record before you import, and redo your changes afterwards. For every other mobile application record, the same import keeps your changes and adds only elements the stored configuration does not have yet.

A manual import adds a record that the database does not hold yet as it is in the file.

Only a manual import and an upgrade merge mobile application configurations. A first-time import, an import of a complete configuration pack, and a restore write every incoming mobile application configuration as it is in the file, the TeamsBot configuration included.

If the stored configuration is not well-formed XML, a manual import stops with the message The XML file 'Navigator Mobile Configuration' has invalid structure.

The TeamsBot record during an upgrade

An upgrade import merges the TeamsBot record like the other mobile application records, so it keeps your changes. If the stored configuration is not well-formed XML, the upgrade import keeps the stored configuration without a message.

The TeamsBot record

The Configuration of the TeamsBot record is an XML document. It names the URL of your portal and switches the bot's commands on or off. Each command group and each command carries an Enabled flag and a message.

Element What it sets
Portal The URL of your Self Service Portal. Set it to your portal's address.
Tickets The ticket commands as a group. It holds CreateAction, the command that creates a ticket, and UpdateAction, the command that updates one.
ApprovalRequests The approval commands as a group. It holds ApproveAction and RejectAction.
CreateAction, UpdateAction, ApproveAction, RejectAction Each names, by its ID, the workflow action the command runs.

The Enabled flag of a group switches the whole group of commands on or off; the flag of a command switches that command.

The record in the supplied configuration

A new 2026.1 database created with the Default Workflow (see Default Workflow Configuration) contains the TeamsBot record with these values. An upgraded database need not have the TeamsBot record, and an administrator may have changed its values.

  • The Portal URL is set to https://www.example.com/hd in the supplied configuration. This is a placeholder: replace it with your portal's address.
  • All four commands are turned on in the supplied configuration, and each names a workflow action of the Self Service Portal. For these actions and their forms, see Self-Service Assistant in Microsoft Teams.
  • The message of the Tickets group is set to Ticket commands are not available. Visit Self Service Portal instead., with Self Service Portal linked to the same placeholder address.
  • The message of the ApprovalRequests group is set to Approval commands are not available.
  • The message of each command is set to This command is not available.

In Microsoft Teams

A Microsoft 365 administrator adds the Self-Service Assistant bot to Microsoft Teams from the Microsoft Teams store and initializes it once for your organization. An administrator then connects the bot to your API in a chat with the bot. You type the configuration commands in a private chat with the bot, in any letter case.

Allow the bot in your organization

People can add the bot only if your organization allows it. This is done in the Microsoft Teams admin center and requires the Teams Administrator role.

  1. In the Microsoft Teams admin center, go to Teams apps > Manage apps and find the bot.
  2. Make sure the bot is allowed.
  3. Make the bot available to the people who will use it: the administrator who connects it and your Self Service Portal customers.

For the current screens, see Microsoft's Manage your apps in the Microsoft Teams admin center and, for setting who can use an app, App centric management. If you cannot find the bot in the Microsoft Teams store, contact Alloy Software Support.

Initialize the bot

A Microsoft 365 administrator does this once for the organization.

  1. In Microsoft Teams, select Apps, search for the Self-Service Assistant bot, select it, and select Add. The bot opens a private chat.
  2. In the chat with the bot, type init. The bot replies with an access token and a refresh token, which give access to your organization's bot configuration.
  3. Send the access token to the administrator who connects the bot to your API.
  4. Keep the refresh token in a safe place, separately from the access token. You need it to get a new pair of tokens if the access token is lost or compromised.

Connect the bot to your API

Have at hand the access token, the API URL, and the Application ID and secret of the Application account (see Before you begin).

  1. If the bot is not in your Teams yet, add it for yourself: select Apps, search for the bot, and select Add.
  2. In a private chat with the bot, type add config (short form ac). The bot replies with a configuration card.
  3. In the card, enter:
    • the API URL;
    • the Application ID of the Application account;
    • the secret of the Application account;
    • the access token you received from the Microsoft 365 administrator.
  4. Click OK.

Self Service Portal customers can then use the bot without further setup: the bot matches the e-mail address of their Teams account to their primary e-mail address in Alloy Navigator.

Your organization has one bot configuration. To change it later, type edit config (short form ec) in the chat with the bot. To get a new pair of tokens, type change tokens (short form cht); the bot asks for the current refresh token first.

If the bot does not recognize an account

  • If the bot replies that it cannot find a user with your e-mail address, make sure a person record exists in Alloy Navigator and that its primary e-mail address is the e-mail address of the Teams account. If needed, add that address to the person record and make it primary.
  • If the bot replies that the Teams account has no e-mail address, a Microsoft 365 administrator adds an e-mail address to that Microsoft 365 account.