https://github.com/simbo/msteams-message-cards
A javascript library that creates message cards for MS Teams and sends them to a webhook (aka "connector").
https://github.com/simbo/msteams-message-cards
cards message message-cards msteams notifications teams
Last synced: over 1 year ago
JSON representation
A javascript library that creates message cards for MS Teams and sends them to a webhook (aka "connector").
- Host: GitHub
- URL: https://github.com/simbo/msteams-message-cards
- Owner: simbo
- License: mit
- Created: 2023-04-27T16:15:36.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2023-05-05T12:04:46.000Z (about 3 years ago)
- Last Synced: 2025-02-24T07:52:43.133Z (over 1 year ago)
- Topics: cards, message, message-cards, msteams, notifications, teams
- Language: TypeScript
- Homepage:
- Size: 137 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# MS Teams Message Cards
[](https://www.npmjs.com/package/msteams-message-cards)
[](http://simbo.mit-license.org/)
[](https://github.com/simbo/msteams-message-cards)
[](https://coveralls.io/github/simbo/msteams-message-cards)
[](https://github.com/simbo/msteams-message-cards/actions/workflows/ci.yml)
A javascript library that creates message cards for MS Teams and sends them to a
webhook (aka "connector").
It uses the
[legacy actionable message card](https://learn.microsoft.com/en-us/outlook/actionable-messages/message-card-reference)
format.
This library only supports basic features of message cards (just the ones I
needed). If you are missing a feature, feel free to create an
[issue](https://github.com/simbo/msteams-message-cards/issues/new) or a
[pull request](https://github.com/simbo/msteams-message-cards/compare).
Supported Message Card Features:
- `title`
- `text`
- `summary`
- `themeColor` (can be set via a color name using
[`color-name-to-code`](https://www.npmjs.com/package/color-name-to-code))
- `potentialAction` (URL buttons only)
- `sections`, containing:
- `text`
- `activityTitle`
- `activitySubtitle`
- `activityText`
- `activityImage`
- `potentialAction` (URL buttons only)
- `facts`
---
## Installation
This library is published to npm registry as
[`msteams-message-cards`](https://www.npmjs.com/package/msteams-message-cards).
You can install it:
```sh
# with npm
npm install --save msteams-message-cards
# with yarn
yarn add msteams-message-cards
```
ℹ️ **HINT**: This library is a pure ESM package. (You may want to
[read this](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).)
## Usage Examples
```js
import {
createMessageCardPayload,
sendMessageCard
} from 'msteams-message-cards';
const webhookURL = 'https://my-teams.com/webhook/123/';
// most simple usage
try {
await sendMessageCard({
webhookURL,
text: 'Hello World!'
});
} catch (error) {
console.error(error);
}
// create and log payload before sending
try {
const payload = createMessageCardPayload({ text: 'Hello World!' });
console.log(`Message Payload:\n${JSON.stringify(payload, null, 2)}`);
await sendMessageCard({ webhookURL, payload });
} catch (error) {
console.error(error);
}
// using some more features
try {
await sendMessageCard({
webhookURL,
title: 'This is great!',
text: "And here's my awesome message.",
summary: 'Awesome summary!',
color: 'dodger blue',
buttons: [{ label: 'More Awesomeness', url: 'https://awesome.com/' }],
sections: [
{
facts: [
{ name: '1', value: 'Foo' },
{ name: '2', value: 'Bar' },
{ name: '3', value: 'Baz' }
]
}
]
});
} catch (error) {
console.error(error);
}
```
## API
### `sendMessageCard`
```ts
async function sendMessageCard(options: Options): Promise;
```
#### Options
```ts
type Options = {
webhookURL: string;
payload?: Payload;
} & PayloadOptions;
```
- `webhookURL: string` (required)
…defines the webhook URL for the MS Teams connector.
- `payload?: Payload` (optional)
…defines the fully formatted payload to send.
Only required if there are no additional [payload options](#payload-options)
present from which a payload could be generated.
The options for `sendMessageCard` can also include all
[payload options](#payload-options).
### `createMessageCardPayload`
```ts
function createMessageCardPayload(options: PayloadOptions): Payload;
```
#### Payload Options
```ts
interface PayloadOptions {
summary?: string;
title?: string;
text?: string;
color?: string;
buttons?: Button[];
sections?: Section[];
}
type Button = { label: string; url: string } | [string, string];
interface Section {
text?: string;
buttons?: Button[];
facts?: Fact[];
activity?: Activity;
}
type Fact = { name: string; value: string } | [string, string];
interface Activity {
title?: string;
subtitle?: string;
text?: string;
image?: string;
}
```
For a valid minimum payload, at least `text` or `summary` needs to be present.
See also the
[official documentation for legacy actionable message cards](https://learn.microsoft.com/en-us/outlook/actionable-messages/message-card-reference)
for more details about the different message card options.
- `summary?: string`
…defines the message card summary. This is should be a one-liner and it used
in Outlook notifications.
- `title?: string`
…defines the message card title.
- `text?: string`
…defines the message card text. It can contain basic HTML and CSS.
- `color?: string`
…defines the message card theme color. Should be either a color hex code or a
color name that can be interpreted by
[`color-name-to-code`](https://www.npmjs.com/package/color-name-to-code).
- `buttons?: Button[]`
…defines the message card buttons. It should be an array of either objects
containing `label:string` and `url:string` or arrays where the first element
is used as label and the second as URL.
- `sections?: Section[]`
…defines one or more message card sections with multiple optional features, of
which at least one needs to be present:
- `text?: string`
…defines the section text.
- `buttons?: string`
…defines the section buttons. It should be an array of either objects
containing `label:string` and `url:string` or arrays where the first element
is used as label and the second as URL.
- `facts?: string`
…defines the facts table of a section. It should be an array of either
objects containing `name:string` and `value:string` or arrays where the
first element it used as name and the second as value.
- `activity?: Activity`
…defines an activity section which is suitable to represent and article or
post. It's defined using an object with the following properties:
- `title?: string`
…defines the title for the activity.
- `subtitle?: string`
…defines the subtitle for the activity.
- `text?: string`
…defines the text for the activity.
- `image?: string`
…defines the image for the activity.
## License
[MIT © Simon Lepel](http://simbo.mit-license.org/)