Overview

Buttons and Cards let you add interactivity to Webex Teams messages. Users can interact with your app in rich new ways without ever leaving the Webex Teams client.

Bots and Integrations can add cards to Webex Teams spaces by including a card attachment when posting a message. Card attachments use Microsoft's Adaptive Cards specification to define the content of the card. The Webex Teams clients render cards with the same look and feel across every platform, letting you focus on the content and the interaction without worrying about the presentation.

Design your own card

Experiment with the Button and Cards framework and export a JSON file.

Try it

anchorAbout Buttons and Cards

Cards are created by including an adaptive card attachment when posting a new message. Cards can be interactive, soliciting an action from the user, such as submitting a response to a poll; or they may be purely informational, such as displaying current weather conditions.

To make cards interactive, include buttons. Buttons are actions that users can use to open a URL, show another card, or submit data from an input form within the card. Cards may include up to five buttons (actions). If you include an input form, data submitted by a user is encrypted and stored within the Webex platform. You can use webhooks to receive notifications for new form submissions. Use the Webhooks API to create a webhook for the attachmentActions resource's created event to receive notifications about card actions. Just like other API resources that contain encrypted data, the webhook's body will not include the form submission. After you receive the webhook, you will need to retrieve the form data via the Attachment Actions API. See Handling Requests from Webex Teams in the Webhooks Guide for more information about how to use webhooks with encrypted data.

Here's an overview of how an application uses webhooks, messages, and attachment actions to create interactive cards:

Card Abilities

Cards can be used in direct 1:1 spaces or group spaces. When they're sent to a group space, every user in the space can see and interact with it.

The card's content cannot be changed after it's created. If you need to provide feedback to a user after an interaction with a card, you have a few options. You could remove the card and post a message with the result of the action. Or perhaps the card is in a group space where you want multiple people to interact with it, you could send them a 1:1 message after they've interacted with it.

To remove a card, simply delete the message that contains the card attachment. The card will be removed from the space.

anchorWorking with Cards

Buttons and Cards use Microsoft's Adaptive Cards specification to define the content of the card. To learn more about the specification, see the documentation. They also provide a schema explorer to help you create cards. Keep in mind that there are some elements and attributes that are not supported with Webex Teams.

Action Webhooks

When using the Action.Submit action or the selectAction attribute of other elements in cards, data that is generated by users is encrypted and stored within the Webex Platform. If you want to receive a notification when users submit data, you'll need to use webhooks. For more information about webhooks in general, see the Webhooks guide.

To watch for form submissions use the attachmentActions webhooks resource. Only one webhook is needed to receive submission notifications for every card created by your app–this resource does not support any filters.

POST https://webexapis.com/v1/webhooks

{
  "name": "My Attachment Action Webhook",
  "targetUrl": "https://example.com/mywebhook",
  "resource": "attachmentActions",
  "event": "created"
}

Creating a Card

To create a card in Webex Teams, include the adaptive card object in the attachments parameter of a new message. For help with defining the card's content, see the Adaptive Cards documentation.

Here's an example of how to create a message that will include a card with a few text blocks, an input form, and an action which will submit the form:

POST https://webexapis.com/v1/messages

{
  "roomId": "Y2lzY29zcGFyazovL3VzL1JPT00vYmJjZWIxYWQtNDNmMS0zYjU4LTkxNDctZjE0YmIwYzRkMTU0",
  "markdown": "[Tell us about yourself](https://www.example.com/form/book-vacation). We just need a few more details to get you booked for the trip of a lifetime!",
  "attachments": [
    {
      "contentType": "application/vnd.microsoft.card.adaptive",
      "content": {
        "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
        "type": "AdaptiveCard",
        "version": "1.0",
        "body": [
          {
            "type": "ColumnSet",
            "columns": [
              {
                "type": "Column",
                "width": 2,
                "items": [
                  {
                    "type": "TextBlock",
                    "text": "Tell us about yourself",
                    "weight": "bolder",
                    "size": "medium"
                  },
                  {
                    "type": "TextBlock",
                    "text": "We just need a few more details to get you booked for the trip of a lifetime!",
                    "isSubtle": true,
                    "wrap": true
                  },
                  {
                    "type": "TextBlock",
                    "text": "Don't worry, we'll never share or sell your information.",
                    "isSubtle": true,
                    "wrap": true,
                    "size": "small"
                  },
                  {
                    "type": "TextBlock",
                    "text": "Your name",
                    "wrap": true
                  },
                  {
                    "type": "Input.Text",
                    "id": "Name",
                    "placeholder": "John Andersen"
                  },
                  {
                    "type": "TextBlock",
                    "text": "Your website",
                    "wrap": true
                  },
                  {
                    "type": "Input.Text",
                    "id" : "Url",
                    "placeholder": "https://example.com"
                  },
                  {
                    "type": "TextBlock",
                    "text": "Your email",
                    "wrap": true
                  },
                  {
                    "type": "Input.Text",
                    "id": "Email",
                    "placeholder": "john.andersen@example.com",
                    "style": "email"
                  },
                  {
                    "type": "TextBlock",
                    "text": "Phone Number"
                  },
                  {
                    "type": "Input.Text",
                    "id": "Tel",
                    "placeholder": "+1 408 526 7209",
                    "style": "tel"
                  }
                ]
              },
              {
                "type": "Column",
                "width": 1,
                "items": [
                  {
                    "type": "Image",
                    "url": "https://upload.wikimedia.org/wikipedia/commons/b/b2/Diver_Silhouette%2C_Great_Barrier_Reef.jpg",
                    "size": "auto"
                  }
                ]
              }
            ]
          }
        ],
        "actions": [
          {
            "type": "Action.Submit",
            "title": "Submit"
          }
        ]
      }
    }
  ]
}

The content length of the entire message (text, markdown, and attachments) cannot exceed 22740 bytes. You can reduce the size of card attachments by not including whitespace in the card's JSON markup.

Images linked in a card will be downloaded and stored with the message. As a rule of thumb, the overall size of the card's JSON and downloaded images should not exceed 80 kilobytes, but this limit can be lower for cards with several images. Don't send cards with links to more than 10 images.

Fallback Text

When sending a card, the Webex message object must include either text or markdown properties for clients that cannot render cards. This text should give the user context about the card's content and provide an alternative method to interact with the card's actions. It cannot include @mentions.

Handling Submissions

If you registered a webhook for the attachmentActions webhook resource, your app will receive a webhook with the following envelope and data if a user submits data:

{
  "id": "Y2lzY29zcGFyazovL3VzL1dFQkhPT0svOTZhYmMyYWEtM2RjYy0xMWU1LWExNTItZmUzNDgxOWNkYzlh",
  "name": "My Attachment Action Webhook",
  "resource": "attachmentActions",
  "event": "created",
  "orgId": "OTZhYmMyYWEtM2RjYy0xMWU1LWExNTItZmUzNDgxOWNkYzlh",
  "appId": "Y2lzY29zcGFyazovL3VzL0FQUExJQ0FUSU9OL0MyNzljYjMwYzAyOTE4MGJiNGJkYWViYjA2MWI3OTY1Y2RhMzliNjAyOTdjODUwM2YyNjZhYmY2NmM5OTllYzFm",
  "ownedBy": "creator",
  "status": "active",
  "actorId": "Y2lzY29zcGFyazovL3VzL1BFT1BMRS83MTZlOWQxYy1jYTQ0LTRmZ",
  "data": {
    "id": "Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi85NmFiYzJhYS0zZGNjLTE",
    "type": "submit",
    "messageId": "GFyazovL3VzL1BFT1BMRS80MDNlZmUwNy02Yzc3LTQyY2UtOWI4NC",
    "personId": "Y2lzY29zcGFyazovL3VzL1BFT1BMRS83MTZlOWQxYy1jYTQ0LTRmZ",
    "roomId": "L3VzL1BFT1BMRS80MDNlZmUwNy02Yzc3LTQyY2UtOWI",
    "created": "2016-05-10T19:41:00.100Z"
  }
}

Similar to other webhook resources, the data property of attachmentActions webhooks will not contain any sensitive data. You will need to use the data.id property to retrieve the attachment action:

GET /attachment/actions/Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi85NmFiYzJhYS0zZGNjLTE

{
  "type": "submit",
  "messageId": "GFyazovL3VzL1BFT1BMRS80MDNlZmUwNy02Yzc3LTQyY2UtOWI4NC",
  "inputs": {
    "Name": "John Andersen",
    "Url": "https://example.com",
    "Email": "john.andersen@example.com",
    "Tel": "+1 408 526 7209"
  },
  "id": "Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi85NmFiYzJhYS0zZGNjLTE",
  "personId": "Y2lzY29zcGFyazovL3VzL1BFT1BMRS83MTZlOWQxYy1jYTQ0LTRmZ",
  "roomId": "L3VzL1BFT1BMRS80MDNlZmUwNy02Yzc3LTQyY2UtOWI",
  "created": "2016-05-10T19:41:00.100Z"
}

anchorSupported Clients

The following Webex Teams clients and SDKs support Buttons and Cards:

• Desktop Clients: Windows and Mac
• Mobile Clients: Android and iOS
  • Mobile clients currently do not support images within cards
• Web Client
• Browser SDK

anchorLimitations

• Webex Teams supports Adaptive Cards 1.2.
• The following card elements are not supported: Media.
• The following card properties are not supported: Action.ToggleVisibility for Actions, Action.ToggleVisibility for ActionSet, fallback for card elements, fallbackText, requires, speak, verticalContentAlignment.
• Data URIs cannot be used with any card property.
• The height property of the ColumnSet element is not supported.
• Cards may include up to five actions.
• Only one card can be sent per request.