How to make your Teams bots richer with markdown

Microsoft Teams comes with excellent lowcode/nocode tool for bots: Power Virtual Agents. Project Oakdale, which is now in preview, brought these bots directly to Teams licensed users to create bots that help tackle , for example, overload on people answering routine questions.

When you are creating the bot dialogue it is easy to use richer text formatting directly in the message:

However, if you try to use these with variable, like a value returned from your backend, database, CDS lite or just from a list, you are quite out of luck. You can not use a variable for displaying a link or use bolded text, for example, to display something you returned from the backend systems (I like to use remaining vacation days or saldo hours as example). So this means your output isn’t as beautified as users would like to see.

And if you have heard about the markdown syntax and used included directly in bot’s messages you have already found out it doesn’t work and might have skipped the whole idea of richening the text.

What markdown syntax is really supported in Teams?

There is a great reference in Microsoft Docs article for markdown – the article is related to Power Automate Approvals but it can start a guide for syntax on Power Automate as well. However with Power Virtual Agents you can use markdown more versatile than in Approvals. I updated the table here with PVA supported syntaxes:

Power Automate ❤ Markdown

You can use markdown in several places in Teams Power Automate actions and in Adaptive cards. Most likely all/many these are supported throughout Teams and not just in Power Virtual Agents. Just refer the table from this article to Markdown supported in Power Automate Approvals!

The trick is a simple one, but goes beyond nocode. You have to enter the world of Power Automate and lowcode. Don’t worry: it is not difficult and with these few simple examples you can enrich your bots to the next level.

For those already experienced: you need to return variables from Power Automate Flow back to Power Virtual Agents with markdown included and then include that variable in Power Virtual Agent’s dialogue message.

So first you need to create a Flow that helps you to define the returning variable.

Let’s bold the text first.

Create a new flow and first’ thing you do you rename it to something you remember and it fits the purpose of the Flow.

Add a input variable (text). In this case we call it the text to bold.

Then add return value to Power Virtual Agents, again of the type text:

For the “Enter a value to respond” you type double-asterisks, pick the TexttoBold from Dynamic content menu (on the right, blue label) and then add double asterisks after it like in this picture:

Save you Flow and return back to the Power virtual Agents by choosing Close.

Hit the + sign again and Call to Action and choose your Flow from the list. Test it with your Display name as input and put the output to the message.

The last message is showing the following, for example

When we hit Test bot and activate the topic we can now see our own name bolded.

And just to prove why you need to use Flow to define the markdown you can try by adding markdown to the message box.

And you get the result:

Yes – it was proved. Let’s explore a two more easy ones:

This time I do a bit more different Flow, I don’t want to create a Flow for all markdowns so I add a input what I want to do:

Of course adding ALL possible combinations would require a few more entries to the switch so I just leave this as example. Markdown syntax is done as following

**TEXT**Bolded text
_TEXT_Italic
**_TEXT_**Bolded and italic

Of course this kind of Flow only works if you get the action to variable.. For simplicity it might be easier to to use a single-action Flows. They are simpler to do as well.

Ok – the basic markdown syntax works.

Power Virtual Agents have a quite limited support for markdown syntax. Not everything works there at this point.

Some things that I have found not to work are:

  • strikethrough
  • video preview

Creating a link with markdown

Creating a link markdown Flow is quite useful to do, since it gets two parameters: link label and link target. This way it is very usable via all your team bots.

The link opens always to a new tab / window.

The Flow and markdown format are quite simple:

The markdown is formatted: [Title](LinkURL)

Showing a picture with markdown

Yes, picture can be shown in the bot as well. The Project Oakdale makes it possible to use pictures in Office 365 – like from a SharePoint library or list. As long as you have a URL to the actual picture you can display pictures within the text. For this one I use a sample from my other demo displaying onboarding process.

You can also use GIFs as image URLs and they work in Teams as well – making your bots fun if the process permits.

Note: URLs like picture thumbnails in SharePoint document library do expire in time. Don’t use them as static ones. #lessonslearned Always get the fresh URL in the Flow or make sure the URL doesn’t expire.

The markdown format is ![alternative text](linkUrl)

In the bot you call Call to Action and get show returned image-variable in a message.

I have to add big thanks to my colleague Matti Kukkamäki who had researched out how to add public pictures to Power Virtual Agent bots. I took that inspiration and carried onwards with pictures in Office 365 and also to dig more into what markdown was supported with these bots.

Creating a list and table

List and table are a bit more complicated, but still doable

There are three kinds of lists:

  • Numbered
    • 0. Text here
    • 0. Text here
  • Bulleted
    • – Text here
    • – Text here
  • Nested
    • 1. Top text
      • – nested text
      • – nested text
    • 1. Top text 2
      • nested text
      • nested text

In Power Automate Flow you can use this to list items from, for example document library. Initialize the string variable in the beginning and then start adding rows

Remember to add a extra enter after the the last text to make it a “new list row”

Creating a table

This is somewhat similar than the list, but in this one you need to define the list columns separated with | when you initialize the variable.

In the looping you just add rows to the table.

Again, remember to add a extra row after the last |.

Using headers

You can define also up to five levels of headers in markdown syntax. However only the first 3 are really usable.

The headers are defined with # (hashtag) signs: number of hashtags equals the header level.

Testing in actual Teams bot

Of course testing inside the Test bot ( while in Teams PVA) is not the reality. Here are results of my testing with various parts.

  • Image: works
  • Header in Teams: works
  • List in Teams: works
  • Table in Teams: works

And on Teams mobile these look like this:

As can be seen the table is there, but user has to scroll it sideways to see everything.

And finally testing Bold + Italic and the link.

Using markdown syntax with Power Virtual Agents really makes a difference from “plain text” to “pleasant to the eye” user experience. With images.

One thought on “How to make your Teams bots richer with markdown

  1. Ӏ read this piece of wгiting fully concerning the resemblance of most
    up-to-date and preceding technologies, it’s awesօme
    article.

    Like

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.