Implement channel-specific functionality

  • Article

APPLIES TO: SDK v4

Some channels provide features that can't be implemented with only message text and attachments. To implement channel-specific functionality, you can pass native metadata to a channel in the activity object's channel data property. For example, your bot can use the channel data property to instruct Telegram to send a sticker or to instruct Office365 to send an email.

This article describes how to use a message activity's channel data property to implement this channel-specific functionality:

Channel Functionality
Email Send and receive an email that contains body, subject, and importance metadata.
LINE Send a message that implements LINE-specific message types.
Teams Handle @-mentions in Microsoft Teams messages.

Note

The value of an activity object's channel data property is a JSON object. Therefore, the examples in this article show the expected format of the channelData JSON property in various scenarios. To create a JSON object using .NET, use the JObject (.NET) class.

Create a custom email message

To create a custom email message, set the activity channelData property to a JSON object that contains the following properties:

Property Description
bccRecipients A semicolon (;) delimited string of email addresses to add to the message's Bcc (blind carbon copy) field.
ccRecipients A semicolon (;) delimited string of email addresses to add to the message's Cc (carbon copy) field.
htmlBody An HTML document that specifies the body of the email message. See the channel's documentation for information about supported HTML elements and attributes.
importance The email's importance level. Valid values are high, normal, and low. The default value is normal.
toRecipients A semicolon (;) delimited string of email addresses to add to the message's To field.

The outgoing and incoming messages between the user and the bot may have a channelData activity that contains a JSON object whose properties are specified in the previous table. The snippet below shows an example of the channelData property for an incoming custom email message, from the bot to the user.

{
    "type": "ActivityTypes.Message",
    "locale": "en-Us",
    "channelID": "email",
    "fromName": { "id": "mybot@mydomain.com", "name": "My bot"},
    "recipientName": { "id": "joe@otherdomain.com", "name": "Joe Doe"},
    "conversation": { "id": "123123123123", "topic": "awesome chat" },
    "channelData":
    {
        "htmlBody": "<html><body style = \"font-family: Calibri; font-size: 11pt;\" >This is more than awesome.</body></html>",
        "importance": "high",
        "ccRecipients": "Yasemin@adatum.com;Temel@adventure-works.com",
    }
}

Create a LINE message

To create a message that implements LINE-specific message types (such as sticker, templates, or LINE-specific action types like opening the phone camera), set the activity object's channel data property to a JSON object that specifies LINE message types and action types.

Property Description
type The LINE action/message type name

These LINE message types are supported:

  • Sticker
  • Imagemap
  • Template (Button, confirm, carousel)
  • Flex

These LINE actions can be specified in the action field of the message type JSON object:

  • Postback
  • Message
  • URI
  • Datetimerpicker
  • Camera
  • Camera roll
  • Location

For details about these LINE methods and their parameters, see the LINE Bot API documentation.

This snippet shows an example of a channelData property that specifies a channel message type ButtonTemplate and three action types: "camera", "cameraRoll", and "datetimepicker".

"channelData": {
    "type": "template",
    "altText": "This is a buttons template",
    "template": {
        "type": "buttons",
        "thumbnailImageUrl": "https://example.com/bot/images/image.jpg",
        "imageAspectRatio": "rectangle",
        "imageSize": "cover",
        "imageBackgroundColor": "#FFFFFF",
        "title": "Menu",
        "text": "Please select",
        "defaultAction": {
            "type": "uri",
            "label": "View detail",
            "uri": "http://example.com/page/123"
        },
        "actions": [{
                "type": "cameraRoll",
                "label": "Camera roll"
            },
            {
                "type": "camera",
                "label": "Camera"
            },
            {
                "type": "datetimepicker",
                "label": "Select date",
                "data": "storeId=12345",
                "mode": "datetime",
                "initial": "2017-12-25t00:00",
                "max": "2018-01-24t23:59",
                "min": "2017-12-25t00:00"
            }
        ]
    }
}

Add a bot to Teams

Bots added to a team become another team member, who can be @mentioned as part of the conversation. In fact, bots only receive messages when they're @mentioned, so other conversations on the channel are not sent to the bot. For more information, see Channel and Group chat conversations with a Microsoft Teams bot.

Because bots in a group or channel respond only when they're mentioned (@botname) in a message, every message received by a bot in a group channel contains its own name, and you must ensure your message parsing handles that. In addition, bots can parse out other users mentioned and mention users as part of their messages.

Check for and strip @bot mention

Mention[] m = sourceMessage.GetMentions();
var messageText = sourceMessage.Text;

for (int i = 0;i < m.Length;i++)
{
    if (m[i].Mentioned.Id == sourceMessage.Recipient.Id)
    {
        //Bot is in the @mention list.
        //The below example will strip the bot name out of the message, so you can parse it as if it wasn't included. Note that the Text object will contain the full bot name, if applicable.
        if (m[i].Text != null)
            messageText = messageText.Replace(m[i].Text, "");
    }
}

var text = message.text;
if (message.entities) {
    message.entities
        .filter(entity => ((entity.type === "mention") && (entity.mentioned.id.toLowerCase() === botId)))
        .forEach(entity => {
            text = text.replace(entity.text, "");
        });
    text = text.trim();
}

Important

Adding a bot by GUID, for anything other than testing purposes, isn't recommended. Doing so severely limits the functionality of a bot. Bots in production should be added to Teams as part of an app. See Create a bot and Test and debug your Microsoft Teams bot.

Additional resources