> For the complete documentation index, see [llms.txt](https://atlas.anywhere.now/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://atlas.anywhere.now/channels-integrations/text-channels/webchat/adaptive-cards.md).

# Manage adaptive cards

Manage adaptive card definitions for WebChat so interactive forms use the intended payload, identifier, and follow-up response.

Adaptive cards store the payload and response text used by interactive WebChat messages. Keep each card `Id` stable after it is referenced by a live channel configuration.

{% hint style="warning" %}
Updates to adaptive-card definitions can affect live WebChat conversations immediately. Test changes in a non-production channel before you reuse an existing card identifier in production.
{% endhint %}

## Prerequisites

* A UCC SharePoint site already exists for the contact center. See [Create UCC Site](broken://spaces/8itFXJdndqu1dclywEFc/pages/fJStjm4z3XJycHzonnMR).
* You can open **Site Contents** and create, edit, and delete items in the relevant UCC SharePoint list.
* You know which WebChat flow or channel configuration will use the card.
* You know which Adaptive Cards payload version is supported by the customer environment.
* You have a validated payload ready from the [Adaptive Cards Designer](https://adaptivecards.io/designer/).

{% hint style="info" %}
The Adaptive Cards Designer may default to a newer payload version than the customer environment supports. Select the supported **Target Version** before copying features into a WebChat card.
{% endhint %}

## Choose the payload version

Use the payload version supported by the customer environment.

| Environment support   | Payload version to use | Notes                                                                       |
| --------------------- | ---------------------- | --------------------------------------------------------------------------- |
| DC2025.01 and later   | Adaptive Cards 1.4     | Examples can use 1.4 features such as input `label` values and `ActionSet`. |
| DC2024.02 and earlier | Adaptive Cards 1.0     | Examples use separate `TextBlock` labels and top-level `actions`.           |

Do not mix 1.0 and 1.4 payload structure in one card.

## Open the adaptive cards list

Adaptive cards are managed from the SharePoint-backed UCC site used by the contact center.

Open the current UCC SharePoint site, then use **Site Contents** or the equivalent deployment-specific list navigation to open the adaptive cards list.

{% hint style="info" %}
Use the current list entry exposed in **Site Contents** or the equivalent UCC-site navigation in your deployment. Do not rely on an obsolete direct URL pattern for this workflow.
{% endhint %}

## Adaptive card fields

| Field                   | Use                                                                                |
| ----------------------- | ---------------------------------------------------------------------------------- |
| `Title`                 | Display name used to identify the adaptive card in the administration list.        |
| `Id`                    | Stable identifier referenced by the consuming WebChat configuration.               |
| `Description`           | Optional administrative description of the card.                                   |
| `Adaptive Card Payload` | JSON payload that defines the card layout and submitted fields.                    |
| `Response`              | JSON response model that defines what happens after the customer submits the card. |

Before WebChat can load an adaptive card, the card must exist in the adaptive cards list and the consuming WebChat configuration must reference the card `Id`.

## Key values

Use these key values only in the adaptive card, or chained adaptive cards, that begin a conversation. They do not apply to cards sent during an agent conversation or after a dialogue closes.

| Key                     | Use                                                                                                                                                                            |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `standard.customerName` | Sets the customer name shown to the agent.                                                                                                                                     |
| `standard.customerUri`  | Sets the customer or conversation URI used for reporting, queue display, text search, timeline lookup, CRM Service lookup, CTI lookup, and related routing or search behavior. |
| `standard.subject`      | Sets a subject value that plugin flow settings can use for routing.                                                                                                            |

`standard.customerUri` must use email-address format, such as `customer@example.com`. If the submitted value does not use email-address format, WebChat falls back to a generic placeholder URI.

For post-dialogue transcript cards, use `standard.transcript` as the submit action id that requests the transcript link.

## Build a response

Every adaptive card needs a response. The response is JSON and can define one or more actions.

```json
{
  "Actions": [
    {
      "Id": "submit",
      "TargetUris": [],
      "Response": {
        "Content": "Thanks {standard.customerName} for sharing, let's look for an agent.",
        "Type": "Message"
      }
    }
  ]
}
```

| Response area      | Use                                                                                                                                                  |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Actions`          | Array of actions that match submit actions in the adaptive-card payload.                                                                             |
| `Id`               | Must match the adaptive-card submit action id.                                                                                                       |
| `TargetUris`       | Optional target URIs that receive submitted values. Use only environment-approved target URIs.                                                       |
| `Response.Content` | Message sent to the customer after submit. It can include submitted values in braces, such as `{standard.customerName}` or `{standard.customerUri}`. |
| `Response.Type`    | Response type. Use `Message` for message responses.                                                                                                  |

## Use adaptive cards in WebChat

Adaptive cards can be used at different stages of a WebChat conversation.

| Stage                 | Behavior                                                                                                                             | Configuration summary                                                                                                     |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| First message         | The customer receives an adaptive card before the conversation starts. After submission, WebChat can route the customer to an agent. | Configure an adaptive card id under the approved presence state and optionally disable input until the card is submitted. |
| Agent-sent message    | An agent sends an adaptive card during a conversation.                                                                               | Agents can search, preview, and send a card configured in the current UCC.                                                |
| Post-dialogue message | The customer receives an adaptive card after the dialogue closes.                                                                    | Configure a post-dialogue adaptive card id in the WebChat FrontEnd configuration.                                         |
| Chained card          | One submitted adaptive card opens one or more follow-up cards.                                                                       | Add `AdaptiveCardIds` to the matching response action.                                                                    |

{% hint style="info" %}
Website script loading, `WebChat.load(config)`, presence states, and front-end package caveats belong with [WebChat front end](/channels-integrations/text-channels/webchat/webchat-front-end.md). Provider endpoint, upload, time-to-live, and ListsPlugin settings belong with [WebChat](/channels-integrations/text-channels/webchat.md).
{% endhint %}

## Configure a first-message adaptive card

Use a first-message adaptive card when the customer must provide structured information before the chat starts.

1. Create the adaptive card item in the adaptive cards list.
2. Confirm the card `Id`.
3. Open the WebChat FrontEnd configuration for the website.
4. Configure the approved presence state to reference the adaptive card `Id`.
5. Decide whether customer input should be disabled until the card is submitted.
6. Test the flow from a non-production website page.

Use the front-end configuration pattern supplied for the environment. JavaScript object names, state names, and package behavior can differ by WebChat FrontEnd package.

## Send an adaptive card as an agent

Agents can send adaptive cards configured in the current UCC during a WebChat conversation.

1. Start or accept a WebChat conversation in WebAgent.
2. Open the reply option for adaptive cards.
3. Search for the card.
4. Preview the card before sending it.
5. Send the card to the customer.
6. Confirm that the submitted response appears in the conversation.

Avoid documenting exact toolbar labels unless they are confirmed for the current WebAgent UI.

## Configure a post-dialogue adaptive card

Use a post-dialogue adaptive card when the customer must receive a form or follow-up action after the dialogue closes.

Configure the WebChat FrontEnd post-dialogue settings to reference the card `Id`. In environments that use a JavaScript configuration object, this is commonly represented as a `postDialogue.adaptivecard.id` concept. Use the exact configuration shape supplied for the customer's WebChat FrontEnd package.

## Chain adaptive cards

Use chained adaptive cards when one card should open another card after submit.

Add `AdaptiveCardIds` to the response action that should trigger the next card or cards.

```json
{
  "Actions": [
    {
      "Id": "submit",
      "TargetUris": [],
      "Response": {
        "Content": "This is a message",
        "Type": "Message"
      },
      "AdaptiveCardIds": [
        "pick-department",
        "register"
      ]
    }
  ]
}
```

| Stage                        | Chained-card behavior                                                                                                 |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Before contact with an agent | The customer receives the next card in the chain. After all cards are submitted, WebChat can hunt an agent.           |
| During contact with an agent | The customer receives the next card in the chain. After all cards are submitted, the conversation continues normally. |
| After contact with an agent  | The customer receives the next card in the chain. After all cards are submitted, the conversation ends.               |

## Example: question form

Use a question form as a first-message card to collect the customer's name, email address, and subject before routing.

{% tabs %}
{% tab title="Adaptive Cards 1.4" %}

```json
{
  "type": "AdaptiveCard",
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "version": "1.4",
  "body": [
    {
      "type": "TextBlock",
      "text": "Question Form",
      "wrap": true,
      "size": "ExtraLarge"
    },
    {
      "type": "TextBlock",
      "text": "Before we start chatting, tell us a bit about yourself.",
      "wrap": true
    },
    {
      "type": "Input.Text",
      "label": "What is your name?",
      "id": "standard.customerName"
    },
    {
      "type": "Input.Text",
      "placeholder": "customer@example.com",
      "label": "What is your email?",
      "id": "standard.customerUri"
    },
    {
      "type": "Input.ChoiceSet",
      "choices": [
        {
          "title": "Support",
          "value": "Support"
        },
        {
          "title": "Sales",
          "value": "Sales"
        },
        {
          "title": "Other",
          "value": "Other"
        }
      ],
      "placeholder": "Select a subject",
      "label": "What is your question about?",
      "id": "standard.subject"
    },
    {
      "type": "ActionSet",
      "actions": [
        {
          "type": "Action.Submit",
          "title": "Let's get started",
          "id": "submit",
          "style": "positive"
        }
      ]
    }
  ]
}
```

{% endtab %}

{% tab title="Adaptive Cards 1.0" %}

```json
{
  "type": "AdaptiveCard",
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "version": "1.0",
  "body": [
    {
      "type": "TextBlock",
      "text": "Question Form",
      "wrap": true,
      "size": "ExtraLarge"
    },
    {
      "type": "TextBlock",
      "text": "Before we start chatting, tell us a bit about yourself.",
      "wrap": true
    },
    {
      "type": "TextBlock",
      "text": "What is your name?",
      "wrap": true
    },
    {
      "type": "Input.Text",
      "id": "standard.customerName",
      "spacing": "None"
    },
    {
      "type": "TextBlock",
      "text": "What is your email?",
      "wrap": true
    },
    {
      "type": "Input.Text",
      "placeholder": "customer@example.com",
      "id": "standard.customerUri",
      "spacing": "None"
    },
    {
      "type": "TextBlock",
      "text": "What is your question about?",
      "wrap": true
    },
    {
      "type": "Input.ChoiceSet",
      "choices": [
        {
          "title": "Support",
          "value": "Support"
        },
        {
          "title": "Sales",
          "value": "Sales"
        },
        {
          "title": "Other",
          "value": "Other"
        }
      ],
      "placeholder": "Select a subject",
      "id": "standard.subject",
      "spacing": "None"
    }
  ],
  "actions": [
    {
      "type": "Action.Submit",
      "title": "Let's get started",
      "id": "submit"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

Use this response for the question form:

```json
{
  "Actions": [
    {
      "Id": "submit",
      "TargetUris": [],
      "Response": {
        "Content": "Thanks {standard.customerName} for sharing, let's look for an agent.",
        "Type": "Message"
      }
    }
  ]
}
```

## Example: contact form

Use a contact form when WebChat is outside business hours and the customer must leave contact details.

{% hint style="warning" %}
`standard.customerUri` normally requires email-address format. If the contact form collects a phone number, treat that as an environment-specific sample and confirm how the submitted value is used before production rollout. `Skill` is example-specific and is not a reserved standard key.
{% endhint %}

```json
{
  "type": "AdaptiveCard",
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "version": "1.4",
  "body": [
    {
      "type": "TextBlock",
      "text": "Contact Form",
      "wrap": true,
      "size": "ExtraLarge",
      "weight": "Bolder"
    },
    {
      "type": "TextBlock",
      "text": "Our chat is currently unavailable. Leave your contact details so we can reach you.",
      "wrap": true
    },
    {
      "type": "Input.Text",
      "placeholder": "+3123456789",
      "label": "Phone number",
      "id": "standard.customerUri"
    },
    {
      "type": "Input.ChoiceSet",
      "choices": [
        {
          "title": "Support",
          "value": "Support"
        },
        {
          "title": "QuickSupport",
          "value": "QuickSupport"
        }
      ],
      "label": "Subject",
      "id": "Skill"
    },
    {
      "type": "ActionSet",
      "actions": [
        {
          "type": "Action.Submit",
          "title": "Submit",
          "style": "positive",
          "id": "submit"
        }
      ]
    }
  ]
}
```

Use an environment-approved `TargetUris` value only when submitted contact details must be posted to another system.

```json
{
  "Actions": [
    {
      "Id": "submit",
      "TargetUris": [
        "https://example.com/webhook"
      ],
      "Response": {
        "Content": "One of our agents will reach out during business hours on {standard.customerUri}.",
        "Type": "Message"
      }
    }
  ]
}
```

## Example: post-dialogue transcript card

Use a post-dialogue transcript card when customers must be able to request a transcript after the dialogue closes.

{% hint style="info" %}
The WebChat Dialogue Provider `Uri` must be publicly accessible for transcript download links. Use the environment-supplied public endpoint; do not use local domain examples.
{% endhint %}

```json
{
  "type": "AdaptiveCard",
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "version": "1.4",
  "body": [
    {
      "type": "TextBlock",
      "text": "Transcript",
      "wrap": true,
      "size": "ExtraLarge",
      "weight": "Bolder"
    },
    {
      "type": "TextBlock",
      "text": "Would you like the transcript of this conversation?",
      "wrap": true,
      "color": "Dark"
    },
    {
      "type": "ActionSet",
      "actions": [
        {
          "type": "Action.Submit",
          "title": "Yes please",
          "style": "positive",
          "id": "standard.transcript"
        }
      ]
    }
  ]
}
```

Use this response for the transcript card:

```json
{
  "Actions": [
    {
      "Id": "standard.transcript",
      "TargetUris": [],
      "Response": {
        "Content": "<b>Your transcript is ready!</b>",
        "Type": "Message"
      }
    }
  ]
}
```

A new post-dialogue card is sent each time the conversation is handled. If the customer continues the conversation after the agent ends it, the transcript can be replaced in the database by the transcript for the continued conversation.

## Manage adaptive card items

<details>

<summary>Create an adaptive card item</summary>

1. Open the adaptive cards list.
2. Select **Add new item**.
3. Enter the `Title`, `Id`, and any description text.
4. Paste the card JSON into **Adaptive Card Payload**.
5. Enter the response JSON into **Response**.
6. Select **Save**.

</details>

<details>

<summary>Edit an adaptive card item</summary>

1. Open the adaptive cards list.
2. Select the existing item.
3. Select **Edit Properties**.
4. Before you change a live card, copy the current `Id`, **Adaptive Card Payload**, and **Response** values so you can restore them if needed.
5. If the card is already referenced by a live channel configuration, keep the existing `Id` and update only the description, payload, or response text.
6. If you need a different `Id`, create a new adaptive card item instead of changing the live identifier.
7. Select **Save**.

</details>

<details>

<summary>Remove an adaptive card item</summary>

1. Open the adaptive cards list.
2. Select the item.
3. Confirm no live channel configuration still references the card, and record the current `Id`, **Adaptive Card Payload**, and **Response** values for recovery.
4. Select **Delete Item**.

</details>

## Verification

1. Confirm the item appears in the list with the expected `Title` and `Id`.
2. Confirm the consuming WebChat configuration references the same `Id`.
3. Submit the card in a test conversation.
4. Confirm that the submitted fields and follow-up response render as expected.
5. Confirm that first-message, agent-sent, post-dialogue, or chained behavior matches the intended WebChat scenario.
6. Confirm that any target URI receives only the approved submitted values.

## Related topics

{% content-ref url="/spaces/8itFXJdndqu1dclywEFc/pages/fJStjm4z3XJycHzonnMR" %}
[Broken mention](broken://spaces/8itFXJdndqu1dclywEFc/pages/fJStjm4z3XJycHzonnMR)
{% endcontent-ref %}

{% content-ref url="/pages/OJFGnA9QSYrs7vAdem5L" %}
[Configure WebChat for WebAgent](/channels-integrations/text-channels/webchat.md)
{% endcontent-ref %}

{% content-ref url="/pages/ELNAEkOc2gs99YPCuUOI" %}
[Configure the WebChat website front end](/channels-integrations/text-channels/webchat/webchat-front-end.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://atlas.anywhere.now/channels-integrations/text-channels/webchat/adaptive-cards.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.