Bot messages with AI-generated content

AI labels, citations, feedback buttons, and sensitivity labels in your bot’s messages improve user engagement and foster transparency and trust.

• AI label enables users to identify that the message was generated using AI.
• Citations enables users to refer to the source of the bot message through in-text citations and references.
• Feedback buttons enables users to provide positive or negative feedback to the bot messages.
• Sensitivity label enables users to understand the confidentiality of the bot message.

The following screenshots show how bot messages can be enhanced with AI labels, citations, feedback buttons, and sensitivity labels:

Before

After

Note

• AI label, citations, feedback buttons, and sensitivity labels are available in public developer preview for one-on-one and group chats, but aren't supported in channels.
• AI label, citations, feedback buttons, and sensitivity labels are available only in Teams web and desktop clients.
• AI label, citations, feedback buttons, and sensitivity labels are available in Government Community Cloud (GCC), GCC High, and Department of Defense (DOD) environments.

AI label

An AI label added to your bot message specifies that the message is generated by AI. AI bots use Large Language Models (LLMs) that are generally reliable, however, adding an AI label prevents confusion about the source of the information.

Add AI label

For a bot built using Teams AI library, an AI label is automatically enabled for all AI-powered bot messages in the ai module within the PredictedSayCommand action. For more information, see AIEntity interface.

If you're using Microsoft Bot Framework SDK to build your bot, include additionalType under the entities array of the message entity object. Following is an example code snippet:

await context.sendActivity({
  type: ActivityTypes.Message,
  text: `Hey! I'm a friendly AI bot. This message is generated by AI.`,
  entities: [
    {
     type: "https://schema.org/Message",
     "@type": "Message",
     "@context": "https://schema.org",
     additionalType: ["AIGeneratedContent"], // Enables AI label
    }
  ]
});

Property	Type	Required	Description
additionalType	Array	Yes	Enables the AI label in the bot message. The only allowed value is AIGeneratedContent.

After an AI label is added, your bot’s message displays an AI generated label next to the bot’s name with a hover-over disclaimer stating, AI-generated content may be incorrect. The AI label and disclaimer can't be customized for AI-powered bots.

Note

The AI generated label is available only when you send a new message using SendActivity. If you update a message using UpdateActivity, the Edited label is added.

Error handling

Error code	Description
400	Multiple root message entities found under entities array
400	Error parsing message entity from entities array

Citations

It's important to cite the sources of the bot message to help users ask follow-up questions or conduct independent research. Cite data sources, such as files, messages, emails, and work items, to provide valuable insights to users. Citations are important for bots using techniques such as Retrieval Augmented Generation (RAG).

Citations to your bot message include in-text citations, details to citation reference, and sensitivity labels for the content referenced.

• In-text citations denote the citation numbers added to the bot message in the [#] format, each corresponding to a reference. A citation can be inserted anywhere within the text.
• Details to citation reference include the title, keywords, an abstract, hyperlink, and sensitivity information. References appear as pop-up windows for each in-text citation.
• Sensitivity labels to citations indicate the confidentiality of the citation content referenced and aren't added automatically. To add sensitivity labels for citations, see add sensitivity label.

Note

• A maximum of 10 citations are displayed in a message.
• Adaptive Cards aren't rendered in the citation pop-up window. However, Adaptive Cards can be rendered in the bot's message.

Add citations

For bots built using Teams AI library, citations are added to an AI bot message automatically through PredictedSayCommand action. You can also modify the PredictedSayCommand action to add citations to your bot message. For more information, see ClientCitation interface.

If you're using Bot Framework SDK to build your bot, include citation under the entities array. Following is an example code snippet:

await context.sendActivity({
  type: ActivityTypes.Message,
  text: `Hey I'm a friendly AI bot. This message is generated through AI [1]`, // cite with [1],
  entities: [
  {
    type: "https://schema.org/Message",
    "@type": "Message",
    "@context": "https://schema.org",
    citation: [
    {
      "@type": "Claim",
      position: 1, // Required. Must match the [1] in the text above
      appearance: {
        "@type": "DigitalDocument",
        name: "AI bot", // Title
        url: "https://example.com/claim-1", // Hyperlink on the title
        abstract: "Excerpt description", // Appears in the citation pop-up window
        keywords: ["keyword 1", "keyword 2", "keyword 3"], // Appears in the citation pop-up window
        },
      },
    ],
  },
],
})

Property	Type	Required	Description
citation	Object	Yes	Details of the citation.
citation.@type	String	Yes	Object of the citation. The only allowed value is Claim.
citation.position	Integer	Yes	Displays the citation number. The values are limited to less than eight.
citation.appearance	Object	Yes	Information about the appearance of the citation.
citation.appearance.@type	String	Yes	Object of the citation appearance. The only allowed value is DigitalDocument.
citation.appearance.name	String	Yes	Title of the referenced content.
citation.appearance.url	String	No	URL of the referenced content.
citation.appearance.abstract	String	No	Extract of the referenced content and is limited to less than 1,000 characters.
citation.appearance.keywords	Array	No	Keywords from the referenced content. You can't add more than three keywords.

After you enable citations, the bot message includes in-text citations and references. The in-text citations display the reference details when users hover over the citation.

Error handling

Error code	Description
400	Multiple root message entities found under entities array
400	Error parsing message entity from entities array
400	Bot message with more than 10 citations
400	The appearance object is empty
400	Error while parsing citation entity with ID: X

Feedback buttons

Feedback buttons in bot messages are crucial for measuring user engagement, identifying errors, and gaining insights into your bot's performance. These insights can lead to targeted and effective enhancements of your bot’s conversational capabilities. Enable feedback buttons to allow users to like or dislike messages and provide detailed feedback.

When the user selects a feedback button, a respective feedback form appears based on the user's selection.

Feedback buttons are located at the footer of the bot’s message, and include a 👍 (thumbs up) and a 👎 (thumbs down) button for the user to choose from. You can collect feedback on bot responses from one-on-one and group chats.

Add feedback buttons

For a bot built using Teams AI library, Teams enables feedback buttons to all bot messages when enable_feedback_loop is set to true in the ai module.

export const app = new Application<ApplicationTurnState>({
    ai: {
        planner: planner,
        enable_feedback_loop: true
    },

For more information, see the const app variable.

After you enable feedback buttons, all SAY commands from the bot have feedbackLoopEnabled automatically set to true in the channelData object.

To enable feedback buttons in a bot built using Bot Framework SDK, add a channelData object in your bot message and set the value of feedbackLoopEnabled to true.

await context.sendActivity({
  type: ActivityTypes.Message,
  text: `Hey! I'm a friendly AI bot!`,
  channelData: {
    feedbackLoopEnabled: true // Enable feedback buttons
  },
});

Property	Type	Required	Description
feedbackLoopEnabled	Boolean	Yes	Enables feedback buttons in the bot's message

Handle feedback

The bot receives the user's input, received in the feedback form, through a bot invoke flow.

For a bot built using Teams AI library, the bot invoke received is automatically handled. To handle feedback, use the app.feedbackLoop method to register a feedback loop handler called when the user provides feedback.

app.feedbackLoop(async (context, state, feedbackLoopData) => {
  // custom logic here...
});

For more information, see the asynchronous callback function.

For a bot built using Bot Framework SDK, you must have an onInvokeActivity handler to process the feedback. Ensure that you return a status code 200 with an empty JSON object as a response.

The following code snippet shows how to handle feedback received in a bot invoke and return a response with the status code 200:

public async onInvokeActivity(context: TurnContext): Promise<InvokeResponse> {
    try {
      switch (context.activity.name) {
        case "message/submitAction":
           console.log('Your feedback is ' + JSON.stringify(context.activity.value))
           // Your feedback is {"actionName":"feedback","actionValue":{"reaction":"like","feedback":"{\"feedbackText\":\"This is my feedback.\"}"}}
           return CreateInvokeResponse(200, {});
        default:
          return {
            status: 200,
            body: `Unknown invoke activity handled as default- ${context.activity.name}`,
          };
      }
    } catch (err) {
      console.log(`Error in onInvokeActivity: ${err}`);
      return {
        status: 500,
        body: `Invoke activity received- ${context.activity.name}`,
      };
    }
  }

 export const CreateInvokeResponse = (
  status: number,
  body?: unknown
 ): InvokeResponse => {
    return { status, body };
 };

It’s important to store feedback after you receive it. Hence, ensure that you store the message IDs and the content of the messages that your bot sends and receives. When your bot receives an invoke containing feedback, match the message ID of the bot’s message with the corresponding feedback.

Note

Teams neither stores nor processes feedback, nor does it provide an API or a storage mechanism.

If a user uninstalls your bot and still has access to the bot chat, Teams removes the feedback buttons from the bot messages to prevent the user from providing feedback to the bot.

Error handling

Error code	Description
400	message/submitAction invoke response isn't empty.

Sensitivity label

Bot responses might contain information that's confidential or only accessible to certain individuals within the organization. You must add a sensitivity label to help users identify the confidentiality of a message, enabling them to exercise caution when sharing the message.

Note

Add a sensitivity label to your bot's messages only when they contain sensitive information.

Add sensitivity label

For bots built using Teams AI library, sensitivity labels can be added through PredictedSayCommand action. For more information, see SensitivityUsageInfo interface.

For bots built using Bot Framework SDK, add a sensitivity label to your bot message by modifying the message to include usageInfo in the entities object.

The following code snippet shows how to add sensitivity labels to both bot messages and citation reference:

Bot message

await context.sendActivity({
  type: ActivityTypes.Message,
  text: `Hey, I'm a friendly AI bot. This message is generated through AI [1]`,
  entities: [
    {
      type: "https://schema.org/Message",
      "@type": "Message",
      "@context": "https://schema.org",
      usageInfo: {
        "@type": "CreativeWork",
        name: "Sensitivity title",
        description: "Sensitivity description",
      },
    },
  ],
});

Citation reference

await context.sendActivity({
  type: ActivityTypes.Message,
  text: `Hey, I'm a friendly AI bot. This message is generated through AI [1]`,
  entities: [
    {
      type: "https://schema.org/Message",
      "@type": "Message",
      "@context": "https://schema.org",
      usageInfo: {
        "@type": "CreativeWork",
        name: "Sensitivity title",
        description: "Sensitivity description",
      },
      citation: [
        {
          "@type": "Claim",
          position: 1,
          appearance: {
            "@type": "DigitalDocument",
            name: "AI bot",
            url: "https://example.com/claim-1",
            usageInfo: {
              "@type": "CreativeWork",
              "@id": "sensitivity1",
              name: "Sensitivity title",
              description: "Sensitivity description",
            },
          },
        },
      ],
    },
  ],
});

Property	Type	Required	Description
usageInfo.@type	String	Yes	Enables the sensitivity label in the bot message.
citation.usageInfo.@id	String	Yes	Enables the sensitivity label in the citation reference. It's required when adding sensitivity label to citation reference.
usageInfo.name	String	Yes	Specifies the title of the sensitivity label.
usageInfo.description	String	No	Specifies the pop-up window message that appears when a user hovers over the sensitivity label.

After the sensitivity label is added, your bot message contains a shield icon. Users can hover over the icon to find a disclaimer on the sensitivity of the message.

Error handling

Error code	Description
400	Multiple root message entities found under entities array
400	Error parsing message entity from entities array
400	Citation level usageInfo.@id value doesn't match the message level usageInfo.@id in at least one instance
400	There are multiple citation-level usageInfo properties with the same @id, but their name and description properties are different.

Modify PredictedSayCommand

For a bot built using Teams AI library, the PredictedSayCommand provides control on how AI label, citations, feedback buttons, and sensitivity labels are added to the bot's activity. Following is the code snippet to modify PredictedSayCommand:

app.ai.action<PredictedSayCommand>(AI.SayCommandActionName, async (context, state, data, action) => {
  // custom logic here...
  await context.sendActivity(data.content);
  return "";
});

For more information about PredictedSayCommand, see PredictedSayCommand interface.

Code sample

Sample name	Description	Node.js	C#
Teams conversation bot	This sample app displays the AI label, citations, feedback buttons, and sensitivity labels in messages.	View
TeamsAzureOpenAI	This conversational bot uses Teams AI library and contains the AI label, feedback buttons, sensitivity label, and citations in its generated messages.		View

See also

• Bot activity handlers
• Format your bot messages
• Get started with Teams AI library
• Streaming UX in bots