DocumentationBlogSupport
Log inSign up
Log inSign up
BlogSupport
Build
Getting StartedPlatform Introduction
Embedded Apps
OverviewDeveloper GuideSidebar API Quick StartSubmission Checklist for Embedded Apps
Design Guidelines
MessagingMeetingsDevicesSidebar
API Reference
BotsButtons and CardsIntegrationsService AppsLogin with WebexGuest IssuerWidgetsWebex ConnectInstant Connect Meeting LinksDeveloper SandboxSubmit Your AppSupport PolicyFAQs
APIs
XML API DeprecationAccess the APIREST API BasicsComplianceWebhooksWebex APIs
Admin
OverviewAdmin APIsAuthentication
Guides
Hybrid ServicesWebhooksReal-time File DLP BasicsUsing Webex Service AppsProvisioning APIsAudit Events Error Reference
Reference
Admin Audit EventsAuthorizationsEventsGroupsHistorical AnalyticsHybrid ClustersHybrid ConnectorsLicensesMeeting QualitiesOrganization ContactsOrganizationsPartner ManagementPartner TagsPeopleRecording ReportRecordingsReport TemplatesReportsResource Group MembershipsResource GroupsRolesSecurity Audit EventsSession TypesSpace ClassificationsTracking CodesWorkspace LocationsWorkspace Metrics
Webex Calling Beta
Overview
Guides
Integrations and Authorization
Webex Calling
OverviewSDKs and ToolsWhat's New
Guides
Integrations and AuthorizationProvisioning APIsWebex for Wholesale
Reference
Call ControlsCall RoutingCalling Service SettingsDevice Call SettingsDevicesFeatures: Announcement RepositoryFeatures: Auto AttendantFeatures: Call ParkFeatures: Call PickupFeatures: Call QueueFeatures: Call RecordingFeatures: Hunt GroupFeatures: Paging GroupFeatures: Receptionist ClientLocation Call SettingsLocation Call Settings: Call HandlingLocation Call Settings: SchedulesLocation Call Settings: VoicemailLocationsNumbersPeopleRecording ReportReportsReports: Detailed Call HistoryUser Call SettingsVirtual Line Call SettingsWholesale Billing ReportsWholesale ProvisioningWorkspace Call SettingsWorkspaces
Webex for Broadworks
Overview
Guides
Integrations and AuthorizationWholesale and Broadworks Common GuideDeveloper's Guide
Reference
BroadWorks Billing ReportsBroadWorks EnterprisesBroadWorks SubscribersBroadWorks Workspaces
Webex for UCM
Guides
Integrations and Authorization
Reference
UCM Profile
Contact Center
Overview
Customer Journey Data
Overview
Guides
Getting StartedFAQ
Devices
Overview
Guides
Devices
Reference
Device Call SettingsDevice ConfigurationsDevicesWorkspace LocationsWorkspace MetricsWorkspace PersonalizationWorkspacesxAPI
Meetings
Overview
Guides
Integrations and AuthorizationWebhooksUsing Webex Service AppsWebinar GuideMeeting Resource Guide
Reference
Meeting ChatsMeeting Closed CaptionsMeeting InviteesMeeting MessagesMeeting ParticipantsMeeting PollsMeeting PreferencesMeeting Q and AMeeting QualitiesMeeting TranscriptsMeetingsMeetings Summary ReportPeopleRecording ReportRecordingsSession TypesTracking CodesVideo MeshWebhooks
Messaging
Overview
Guides
BotsIntegrations and AuthorizationWebhooksUsing Webex Service AppsButtons and Cards
Reference
Attachment ActionsEventsMembershipsMessagesPeopleRoom TabsRoomsTeam MembershipsTeamsTracking CodesWebhooks
Webex Assistant Skills
Overview
Guides
Skills SDK GuideSkills Developer PortalSkills Reference GuideSkills UX Guide
FedRAMP
Overview
Guides
Create a BotCreate an IntegrationNotes on API Support
Workspace Integrations
OverviewTechnical DetailsControl Hub Features
Webex Status API
Full API Reference
Admin Audit EventsAttachment ActionsAuthorizationsBroadWorks Billing ReportsBroadWorks EnterprisesBroadWorks SubscribersBroadWorks WorkspacesCall ControlsCall RoutingCalling Service SettingsDevice Call SettingsDevice ConfigurationsDevicesEventsFeatures: Announcement RepositoryFeatures: Auto AttendantFeatures: Call ParkFeatures: Call PickupFeatures: Call QueueFeatures: Call RecordingFeatures: Hunt GroupFeatures: Paging GroupFeatures: Receptionist ClientGroupsHistorical AnalyticsHybrid ClustersHybrid ConnectorsLicensesLocation Call SettingsLocation Call Settings: Call HandlingLocation Call Settings: SchedulesLocation Call Settings: VoicemailLocationsMeeting ChatsMeeting Closed CaptionsMeeting InviteesMeeting MessagesMeeting ParticipantsMeeting PollsMeeting PreferencesMeeting Q and AMeeting QualitiesMeeting TranscriptsMeetingsMeetings Summary ReportMembershipsMessagesNumbersOrganization ContactsOrganizationsPartner ManagementPartner TagsPeopleRecording ReportRecordingsReport TemplatesReportsReports: Detailed Call HistoryResource Group MembershipsResource GroupsRolesRoom TabsRoomsSecurity Audit EventsSession TypesSiteSpace ClassificationsTeam MembershipsTeamsTracking CodesUCM ProfileUser Call SettingsVideo MeshVirtual Line Call SettingsWebhooksWholesale Billing ReportsWholesale ProvisioningWorkspace Call SettingsWorkspace LocationsWorkspace MetricsWorkspace PersonalizationWorkspacesxAPI
API Changelog
SDKs
iOSAndroidBrowserNode.jsJava
Developer CommunityCertifications

Buttons and Cards

Give new levels of interactivity to Webex users by adding Buttons and Cards to your apps.

anchorOverview
anchor

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

Sample Card

Bots and Integrations can add cards to Webex 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 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
Buttons and Cards Designer
anchorWhat's New
anchor

Support for Version 1.3 properties:

  • isRequired
  • label
  • errorMessage
  • regex

Sample JSON for card exhibiting input validation using Version 1.3 properties is as follows:

{
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.3",
    "body": [
        {
            "type": "Input.Text",
            "label": "Name",
            "isRequired": true,
            "placeholder": "First Name + Last Name",
            "errorMessage": "Please provide a valid input",
            "regex": "^[\\p{L} .'-]+$",
            "id": "sample text"
        },
        {
            "type": "Input.Date",
            "id": "sample date",
            "label": "Date of Birth",
            "errorMessage": "Please enter a valid date",
            "isRequired": true,
            "min": "1960-01-01",
            "max": "1999-12-31"
        }
    ],
    "actions": [
        {
            "type": "Action.Submit",
            "title": "Action.Submit"
        }
    ]
}
anchorAbout Buttons and Cards
anchor

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 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 Interactions

You can see examples of Buttons and Cards and learn more about Buttons and Cards right in Webex. Send a direct message to the CardSchool Bot to get started.

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.

If you need to provide feedback to a user after an interaction with a card, you have a few options.

  • You could edit the content of the card as a result of the action (currently available only for the cards that doesn't include images, either pre or post edit). Edit message is the driving force behind editing a card.
  • You could remove the card and post a message with the result of the action. To remove a card, simply delete the message that contains the card attachment. The card will be removed from the space.
  • 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.

The ability to update card content for cards with images will be released in the future. Stay tuned to our blog for updates.

anchorWorking with Cards
anchor

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.

You can design and experiment with Buttons and Cards in our interactive Buttons and Cards Designer. You can also use the CardSmapler Bot to see how your cards will look in the Webex clients.

For an introduction to Webex Cards, see the following lab on Cisco DevNet, Webex Adaptive Cards.

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, 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 https://webexapis.com/v1/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
anchor

The following Webex clients and SDKs support Buttons and Cards:

  • Desktop Clients: Windows and Mac
  • Mobile Clients: Android and iOS
  • Web Client
  • Browser SDK
  • Widgets

Watch our blog for news about Buttons and Cards support in our other clients and SDKs.

anchorLimitations
anchor
  • Webex supports Adaptive Cards Version 1.3.
  • The following card elements are not supported: Media.
  • The following card properties are not supported: fallback for card elements, fallbackText, requires, and speak.
  • The height property of the ColumnSet element is not supported.
  • Cards may include up to twenty actions (using ActionSet gives you more freedom).
  • Only one card can be sent per request.
  • Editing of Cards on User interaction is possible only for cards with no images, pre or post Edit.
Related Resources
  • Buttons and Cards Designer
  • Adaptive Cards
  • Overview
  • What's New
  • About Buttons and Cards
  • Working with Cards
  • Supported Clients
  • Limitations

Connect

Support

Developer Community

Developer Events

Contact Sales

Handy Links

Webex Ambassadors

Webex App Hub

Resources

Open Source Bot Starter Kits

Download Webex

DevNet Learning Labs

Terms of Service

Privacy Policy

Cookie Policy

Trademarks

© 2023 Cisco and/or its affiliates. All rights reserved.