Sending analytics to a Microsoft Teams channel as a message
Atomic provides a webhook subscriptions capability for sending analytic events in near real-time to external cloud services and applications.
This tutorial is written specifically for sending analytics events via webhooks to Microsoft Teams. It describes how to set up a webhook subscription configuration that sends Atomic analytics to a Webhook URL provided when you add a Webhook 'Connector' in your Microsoft Teams account. The mapping script provided is intended as a starting point; your implementation should be thoroughly tested to ensure it meets your specific requirements.
To follow the steps in this tutorial, you will need:
- Edit-level permissions to the webhook resource in your Atomic environment, so that you can configure the outgoing webhook subscription.
- A MS Teams account, a Channel you wish to post Atomic events to, and user permissions to Teams that permit you to add a Webhook Connector to your Channel.
The data sent in webhooks is controlled by you when configuring them. In addition to choosing which event types to subscribe to, we provide a mapping feature you can use to control which data to include, and in what shape.
Add a Webhook Connector to your MS Teams channel
In this step, you will configure your MS Teams Channel so that Atomic can send events to it via a Webhook subscription.
Add a connector
- Navigate to the settings for your Channel by choosing 'Manage channel' from the overflow menu
- Expand the Connectors options and choose Edit
- Follow the prompts to add a new Incoming Webhook
- Name the webhook (this will be the name shown beside messages from Atomic), upload an icon for the Connector and finalize to generate your unique Webhook URL. Copy this for use in the next step.
-
Back in Atomic, go to configuration > analytics > webhook subscriptions and create a new subscription. In this particular example we will configure a Webhook subscription and mapping script which is suitable for sending details of Action Flow Failed events to Teams, illustrating how you may choose to alert your team in when these issues are detected.
- Choose 'All cards' from the card options
- Give your Webhook Subscription a meaningful name
- Choose 'action-flow-step-failed' from the event types options list
- Paste in the URL generated in the previous step
- Save
- Open the mapping options for your Webhook subscription, choose JavaScript mapping, and paste the following example, modify it to suit your needs, then save.
// This extract the platform context from the event payload
// and builds an array of content in the format Teams expects
const transformedPlatformContext = Object.keys(data.platformContext).map(key => {
if (key === "errors") {
return {
name: `${key}:`,
value: JSON.stringify(data.platformContext[key][0])
};
} else {
return {
name: `${key}:`,
value: JSON.stringify(data.platformContext[key])
};
}
});
// This is an example payload MS Teams expects
// https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using
const myPayload = {
"@type": "MessageCard",
"@context": "http://schema.org/extensions",
"summary": `New ${data.eventName} event`,
"sections": [{
"activityTitle": `**${data.analyticsEvent}**`,
"activitySubtitle": `**UserId:** ${data.endUserId}`,
"facts": transformedPlatformContext
}]
};
// This returns the payload we built and will show a preview to the right here
return myPayload;
Open the Request Debugger from the overflow menu on your webhook subscription to debug requests. Live events will have their payloads hidden to protect PII, but test events will be fully displayed.
- That's it! When events matching your webhook subscription setup come through, they will be mapped using your mapping script and sent to your MS Teams channel.
Troubleshooting
- Before connecting the webhook subscriptions to Teams, you can use a website such as https://webhook.site/
- Learn more about Webhook Subscriptions available in Atomic