anchorOverview

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.

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. 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 endpoint. 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 and an interactive card designer to help you create cards.

Action Webhooks

When using the Action.Submit action 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://api.ciscospark.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://api.ciscospark.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. The content length of the text and markdown fields cannot exceed 7439 bytes. You can reduce the size of card attachments by not including whitespace in the card's JSON markup.

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.

If a message also includes a file attachment, the text or markdown properties may be used to describe the file attachment. Webex Teams clients will include the message text if both a card and a file attachment are present.

Fallback text specified in the fallbackText property will be used if a client doesn't support the card's schema version. It will not be used by Webex Teams clients that do not support cards.

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
• Web Client
• Browser SDK

anchorLimitations

• Webex Teams supports Adaptive Cards 1.1.
• All card elements are available for use except Media.
• All card properties are available for use except backgroundImage, iconUrl, and speak.
• Cards may include up to five actions.
• Messages with cards may include up to ten images.
• Only one card can be sent per request.

anchorMore Information

For more information about Adaptive Cards, see https://adaptivecards.io/.