Group Chats

On channels for Microsoft Teams and Slack, it is possible to make skills and digital assistants available for group chats, where multiple human participants can collaborate with a digital assistant in the same conversation.

Group chats are good for situations where you need a skill to perform actions or provide information for a group of human participants. In a group chat:

  • All aspects of the conversation are visible to all participants.
  • The skill only responds to messages in which the user includes a mention of the Microsoft bot or Slack app that represents the skill. This means that the human participants in a group chat can exchange messages among themselves without involving the skill. For example, they may want to have a discussion to agree on what to request of the skill before they make that request.
  • By default, the skill will not mediate between users. It will respond to input in the order received as if it was all coming from the same person. For example, if one user contradicts another user, the bot will not try to reconcile the two, unless some logic has been programmed in a custom component to do so (but it would probably need to have logged in users that the bot could explicitly track).
  • Any query made to a skill within a group chat is based on the identity (and, in the case of skills that require authentication, the corresponding credentials) of the user in the group chat who made the query.

You can also set up the skill to require all participants in a group chat to be authenticated.

For the group chat to work, you need to set up a Microsoft Teams or Slack channel.

If you are using a Microsoft Teams channel, make sure that you have selected the appropriate bot scopes to enable group chat. You can select Team and/or Group Chat (the latter of which is a user-defined group).

If you are using Slack as the channel, make sure that the Slack app has the following event subscriptions:

  • message.im
  • app_mention
  • message.mpim
  • message.channels

Once a channel is set up for the skill or digital assistant to be used in the group chat, users can add the corresponding Microsoft bot or Slack app to a group. In the conversation, they can invoke the bot or app with a user mention.

User Authorization in Group Chats

In skills that you target for group chats, you may wish to require authorization for users to send messages. Since multiple users may access the skill in a session, you need to configure the skill to properly handle authorization for each user, not just the user who first encounters the authorization state. You do this by using:

  • The Requires Authorization property on states where you want to enforce authorization. This ensures that a user can't enter a message in the chat when it is at such a state until that user is authorized.
  • The Authorize User event to direct unauthorized users to the appropriate authorization state when they try to enter a message in the chat at a secured state.
  • The skill.system.event.value.authorizeUser.requestedState variable to identify the state at which an unauthorized user enter a message in the chat (and, therefore, the state where they should be redirected after successful authorization).
  • The system.message.channelConversation.groupConversation Boolean property, which you can refer to when you need to determine whether the conversation is a group chat.

Enforce User Authorization for Group Chats

Here are the general steps for enforcing authorization for each user in a group chat:

  1. Assuming that you will want to enforce authentication for the majority of the skill's states, configure the skill as a whole to require authorization by default. To do so:
    1. Click icon to open the side menu to open the side menu, select Development > Skills, and select your skill.
    2. In the skill’s left navigation, click the Settings icon.
    3. Click the Configuration tab.
    4. Set the Requires Authorization property to true.

    Doing this sets the default value for the Requires Authorization property for all of the states in the dialog flow. This value can be overridden on individual states.

  2. For any states that do not require authorization, set the Requires Authorization property to false. For example:

    Note:

    Alternatively, you can set the skill's Requires Authorization property to false and then set the Requires Authorization property to individual states to true.
  3. Add an OAuth Account Link or OAuth 2.0 Account Link component in the dialog flow for user authentication.

    Use user-scoped variables to store the access token and authenticated user ID. Otherwise, the authorization info each user who joins the chat would override the authorization info the preceding user who joined the chat.

    For the pass transition, use the skill.system.event.value.authorizeUser.requestedState system variable to return the user to the state where they tried to enter the conversation.

  4. Add the states for authorization failure. For example, you might have separate states for the following cases:
    • Where the failed authorization happens in a group chat. In this case, the user might not be able to authenticate, but the conversation can continue with the other participants.
    • Where the failed authorization happens in an individual chat, in which case the conversation can simply end.

      Note:

      For this case, you can use the ephemeral custom channel property to display the message only to the user who is triggering that response.
      responseItems:
        - type: "text"
          text: "Sorry ${profile.firstName}, you are not authorized to use this skill"
          channelCustomProperties:
            - channel: "slack"
              properties:
                ephemeral: true
  5. In the Event Mappings section of the flow's configuration, map the Authorize User event to the user authentication state.

    This event is triggered when a not-yet-authorized user tries to join the conversation and reaches a state that requires authorization.

Enable Messages Without User Mention in Slack Group Chats

It is possible to configure Slack channels to allow messages to be sent to the Slack app without user mentions of the Slack app. This behavior could be particularly useful for Slack channels where there are many users and they don't all know that they would would need a user mention for the Slack app to respond. A user support channel is one such example.

To enable messages without user mention to be passed to the digital assistant in Slack group chats:

  • When creating the channel or later modifying the channel's configuration, set the Allow Messages Without App Mention in Group Chat switch to ON.

Enable Users to Stop Messages from Being Sent to the Slack App

In Slack channels where you have enabled messages without a user mention of the Slack App to be sent to the digital assistant, there may be cases where the user wants to stop those messages from being sent to the digital assistant. In this case, you can initiate "ambient mode" to stop the messages from being sent to the digital assistant through the Slack app. To do so, you specify a system.startAmbientMode postback action in the dialog flow definition.

The postback for initiating ambient mode might looking something like the following:

responseItems:
  - type: "text"
    text: "Do you want to stop chatting with the skill?"
    name: "stopMessages"
    actions:
      - label: "Stop chatting with the skill"
        type: "postback"
        payload:
          action: "system.startAmbientMode"
        name: "stop"

Once the user selects this option, the user's following messages will not be sent to the digital assistant until the user once again enters a user mention of the Slack app in a message.

Similarly, you could add a system.stopAmbientMode postback action in the dialog flow definition to end ambient mode.

What Users Need to Know About Group Chats

When you create a skill that is intended to work in a group chat, you should make sure that users of the skill are aware of the following:

  • To involve the skill (or digital assistant) in the group chat, you address the corresponding Microsoft Teams bot or Slack app with a user mention (@bot_name).

    Note:

    For Slack channels, you also have the option to send messages to the Slack app without a user mention. See Enable Messages Without User Mention in Slack Group Chats.
  • For every message that you enter that you expect a response from the bot, you need to include the user mention of the bot.
  • If your message is intended only for the other human participants, don't include a user mention for the bot. The bot will ignore such messages.
  • In Slack group chats, the chats need to be held in the thread where the bot was first introduced in the conversation. If someone responds outside the thread of the conversation, it creates a new conversation that is independent of the previous one.
  • When a participant in the group chat makes a request of the bot, the bot is aware of which user made the request. Therefore, where appropriate, the response to the request is based on the requester's identity and credentials. If a different participant then makes a request, the response to that request is based on that second participant's identity and credentials.
  • All users that have successfully joined a group chat can see all of the bot's responses. It is the responsibility of the participants in the group chat to not elicit information from the bot that other participants aren't supposed to see.