Edit

Share via

CardFactory class

  • Reference
Package:
botbuilder-core

Provides methods for formatting the various card types a bot can return.

Remarks

All of these functions return an Attachment object, which can be added to an existing activity's attachments collection directly or passed as input to one of the MessageFactory methods to generate a new activity.

This example sends a message that contains a single hero card.

const { MessageFactory, CardFactory } = require('botbuilder');

const card = CardFactory.heroCard(
     'White T-Shirt',
     ['https://example.com/whiteShirt.jpg'],
     ['buy']
);
const message = MessageFactory.attachment(card);
await context.sendActivity(message);

Properties

contentTypes

Lists the content type schema for each card style.

Methods

actions(string | CardAction[] | undefined)

Returns a properly formatted array of actions.
adaptiveCard(any)

Returns an attachment for an Adaptive Card.
animationCard(string, string | MediaUrl[], string | CardAction[], Partial<AnimationCard>)

Returns an attachment for an animation card.
audioCard(string, string | MediaUrl[], string | CardAction[], Partial<AudioCard>)

Returns an attachment for an audio card.
heroCard(string, string | CardImage[], string | CardAction[], Partial<HeroCard>)

Returns an attachment for a hero card.
heroCard(string, string, string | CardImage[], string | CardAction[], Partial<HeroCard>)

Returns an attachment for a hero card.
images(string | CardImage[] | undefined)

Returns a properly formatted array of card images.
media(string | MediaUrl[] | undefined)

Returns a properly formatted array of media URL objects.
o365ConnectorCard(O365ConnectorCard)

Returns an attachment for an Office 365 connector card.
oauthCard(string, string, string, string, TokenExchangeResource)

Returns an attachment for an OAuth card.
receiptCard(ReceiptCard)

Returns an attachment for a receipt card.
signinCard(string, string, string)

Returns an attachment for a sign-in card.
thumbnailCard(string, string | CardImage[], string | CardAction[], Partial<ThumbnailCard>)

Returns an attachment for a thumbnail card.
thumbnailCard(string, string, string | CardImage[], string | CardAction[], Partial<ThumbnailCard>)

Returns an attachment for a thumbnail card.
videoCard(string, string | MediaUrl[], string | CardAction[], Partial<VideoCard>)

Returns an attachment for a video card.

Property Details

contentTypes

Lists the content type schema for each card style.

static contentTypes: any

Property Value

any

Method Details

actions(string | CardAction[] | undefined)

Returns a properly formatted array of actions.

static function actions(actions: string | CardAction[] | undefined): CardAction[]

Parameters

actions

string | CardAction[] | undefined

The array of action to include on the card. Each string in the array is converted to an imBack button with a title and value set to the value of the string.

Returns

CardAction[]

A properly formatted array of actions.

adaptiveCard(any)

Returns an attachment for an Adaptive Card.

static function adaptiveCard(card: any): Attachment

Parameters

card

any

A description of the Adaptive Card to return.

Returns

Attachment

An Attachment.

Remarks

Adaptive Cards are an open card exchange format enabling developers to exchange UI content in a common and consistent way. For channels that don't yet support Adaptive Cards natively, the Bot Framework will down-render the card to an image that's been styled to look good on the target channel. For channels that support hero cards you can continue to include Adaptive Card actions and they will be sent as buttons along with the rendered version of the card.

For more information about Adaptive Cards and to download the latest SDK, visit adaptivecards.io.

For example:

const card = CardFactory.adaptiveCard({
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [
      {
         "type": "TextBlock",
         "text": "Default text input"
      }
  ],
  "actions": [
      {
         "type": "Action.Submit",
         "title": "OK"
      }
  ]
});

animationCard(string, string | MediaUrl[], string | CardAction[], Partial<AnimationCard>)

Returns an attachment for an animation card.

static function animationCard(title: string, media: string | MediaUrl[], buttons?: string | CardAction[], other?: Partial<AnimationCard>): Attachment

Parameters

title

string

The card title.

media

string | MediaUrl[]

The media URLs for the card.

buttons

string | CardAction[]

Optional. The array of buttons to include on the card. Each string in the array is converted to an imBack button with a title and value set to the value of the string.

other

Partial<AnimationCard>

Optional. Any additional properties to include on the card.

Returns

Attachment

An Attachment.

audioCard(string, string | MediaUrl[], string | CardAction[], Partial<AudioCard>)

Returns an attachment for an audio card.

static function audioCard(title: string, media: string | MediaUrl[], buttons?: string | CardAction[], other?: Partial<AudioCard>): Attachment

Parameters

title

string

The card title.

media

string | MediaUrl[]

The media URL for the card.

buttons

string | CardAction[]

Optional. The array of buttons to include on the card. Each string in the array is converted to an imBack button with a title and value set to the value of the string.

other

Partial<AudioCard>

Optional. Any additional properties to include on the card.

Returns

Attachment

An Attachment.

heroCard(string, string | CardImage[], string | CardAction[], Partial<HeroCard>)

Returns an attachment for a hero card.

static function heroCard(title: string, images?: string | CardImage[], buttons?: string | CardAction[], other?: Partial<HeroCard>): Attachment

Parameters

title

string

The card title.

images

string | CardImage[]

Optional. The array of images to include on the card. Each element can be a CardImage or the URL of the image to include.

buttons

string | CardAction[]

Optional. The array of buttons to include on the card. Each string in the array is converted to an imBack button with a title and value set to the value of the string.

other

Partial<HeroCard>

Optional. Any additional properties to include on the card.

Returns

Attachment

An Attachment.

Remarks

Hero cards tend to have one dominant, full-width image. Channels typically render the card's text and buttons below the image.

For example:

const card = CardFactory.heroCard(
     'White T-Shirt',
     ['https://example.com/whiteShirt.jpg'],
     ['buy']
);

heroCard(string, string, string | CardImage[], string | CardAction[], Partial<HeroCard>)

Returns an attachment for a hero card.

static function heroCard(title: string, text: string, images?: string | CardImage[], buttons?: string | CardAction[], other?: Partial<HeroCard>): Attachment

Parameters

title

string

The card title.

text

string

The card text.

images

string | CardImage[]

Optional. The array of images to include on the card. Each element can be a CardImage or the URL of the image to include.

buttons

string | CardAction[]

Optional. The array of buttons to include on the card. Each string in the array is converted to an imBack button with a title and value set to the value of the string.

other

Partial<HeroCard>

Optional. Any additional properties to include on the card.

Returns

Attachment

An Attachment.

Remarks

Hero cards tend to have one dominant, full-width image. Channels typically render the card's text and buttons below the image. For example:

const card = CardFactory.heroCard(
     'White T-Shirt',
     ['https://example.com/whiteShirt.jpg'],
     ['buy']
);

images(string | CardImage[] | undefined)

Returns a properly formatted array of card images.

static function images(images: string | CardImage[] | undefined): CardImage[]

Parameters

images

string | CardImage[] | undefined

The array of images to include on the card. Each element can be a CardImage or the URL of the image to include.

Returns

CardImage[]

A properly formatted array of card images.

media(string | MediaUrl[] | undefined)

Returns a properly formatted array of media URL objects.

static function media(links: string | MediaUrl[] | undefined): MediaUrl[]

Parameters

links

string | MediaUrl[] | undefined

The media URLs. Each string is converted to a media URL object.

Returns

MediaUrl[]

A properly formatted array of media URL objects.

o365ConnectorCard(O365ConnectorCard)

Returns an attachment for an Office 365 connector card.

static function o365ConnectorCard(card: O365ConnectorCard): Attachment

Parameters

card

O365ConnectorCard

a description of the Office 365 connector card to return.

Returns

Attachment

An Attachment.

Remarks

For example:

const card = CardFactory.o365ConnectorCard({
  "title": "card title",
  "text": "card text",
  "summary": "O365 card summary",
  "themeColor": "#E67A9E",
  "sections": [
      {
          "title": "**section title**",
          "text": "section text",
          "activityTitle": "activity title",
      }
  ]
});

oauthCard(string, string, string, string, TokenExchangeResource)

Returns an attachment for an OAuth card.

static function oauthCard(connectionName: string, title: string, text?: string, link?: string, tokenExchangeResource?: TokenExchangeResource): Attachment

Parameters

connectionName

string

The name of the OAuth connection to use.

title

string

The title for the card's sign-in button.

text

string

Optional. Additional text to include on the card.

link

string

Optional. The sign-in link to use.

tokenExchangeResource

TokenExchangeResource

optional. The resource to try to perform token exchange with.

Returns

Attachment

An Attachment.

Remarks

OAuth cards support the Bot Framework's single sign on (SSO) service.

receiptCard(ReceiptCard)

Returns an attachment for a receipt card.

static function receiptCard(card: ReceiptCard): Attachment

Parameters

card

ReceiptCard

A description of the receipt card to return.

Returns

Attachment

An Attachment.

signinCard(string, string, string)

Returns an attachment for a sign-in card.

static function signinCard(title: string, url: string, text?: string): Attachment

Parameters

title

string

The title for the card's sign-in button.

url

string

The URL of the sign-in page to use.

text

string

Optional. Additional text to include on the card.

Returns

Attachment

An Attachment.

Remarks

For channels that don't natively support sign-in cards, an alternative message is rendered.

thumbnailCard(string, string | CardImage[], string | CardAction[], Partial<ThumbnailCard>)

Returns an attachment for a thumbnail card.

static function thumbnailCard(title: string, images?: string | CardImage[], buttons?: string | CardAction[], other?: Partial<ThumbnailCard>): Attachment

Parameters

title

string

The card title.

images

string | CardImage[]

Optional. The array of images to include on the card. Each element can be a CardImage or the URL of the image to include.

buttons

string | CardAction[]

Optional. The array of buttons to include on the card. Each string in the array is converted to an imBack button with a title and value set to the value of the string.

other

Partial<ThumbnailCard>

Optional. Any additional properties to include on the card.

Returns

Attachment

An Attachment.

Remarks

Thumbnail cards are similar to hero cards but instead of a full width image, they're typically rendered with a smaller thumbnail version of the image. Channels typically render the card's text to one side of the image, with any buttons displayed below the card.

thumbnailCard(string, string, string | CardImage[], string | CardAction[], Partial<ThumbnailCard>)

Returns an attachment for a thumbnail card.

static function thumbnailCard(title: string, text: string, images?: string | CardImage[], buttons?: string | CardAction[], other?: Partial<ThumbnailCard>): Attachment

Parameters

title

string

The card title.

text

string

The card text.

images

string | CardImage[]

Optional. The array of images to include on the card. Each element can be a CardImage or the URL of the image to include.

buttons

string | CardAction[]

Optional. The array of buttons to include on the card. Each string in the array is converted to an imBack button with a title and value set to the value of the string.

other

Partial<ThumbnailCard>

Optional. Any additional properties to include on the card.

Returns

Attachment

An Attachment.

Remarks

Thumbnail cards are similar to hero cards but instead of a full width image, they're typically rendered with a smaller thumbnail version of the image. Channels typically render the card's text to one side of the image, with any buttons displayed below the card.

videoCard(string, string | MediaUrl[], string | CardAction[], Partial<VideoCard>)

Returns an attachment for a video card.

static function videoCard(title: string, media: string | MediaUrl[], buttons?: string | CardAction[], other?: Partial<VideoCard>): Attachment

Parameters

title

string

The card title.

media

string | MediaUrl[]

The media URLs for the card.

buttons

string | CardAction[]

Optional. The array of buttons to include on the card. Each string in the array is converted to an imBack button with a title and value set to the value of the string.

other

Partial<VideoCard>

Optional. Any additional properties to include on the card.

Returns

Attachment

An Attachment.