How can we help?

Talkdesk Digital Engagement: Configuring Rich Visuals for Talkdesk Chat
Published • Last Updated

This article provides an end-to-end overview of configuring Rich Visuals within the Talkdesk Chat widget, backed by the Talkdesk AI Agent Platform™. Traditional text-based AI interactions create heavy user friction, slow down workflows, and lead to high drop-off rates because users are forced to read dense walls of text and manually type every response. 

Implementing Rich Visuals solves this problem by replacing manual text entry with intuitive and responsive visual components, driving value through faster transaction completion times and significantly higher conversion rates.

The guide provides step-by-step instructions for:

 

Setting Up the Rich Visuals Integration

Setting Up the Rich UI Integration

Follow Configuring an Integration and Custom Integration to create the Rich UI integration.

Base path for regions:

  • US: https://api.talkdeskapp.com
  • EU: https://api.talkdeskapp.eu
  • CA: https://api.talkdeskappca.com
  • UK: https://api.talkdeskapp.co.uk

Authentication type: OAuth2 Client Credentials V2

Access token URL for regions:

  • US: https://<your account name>.talkdeskid.com/oauth/token
  • EU: https://<your account name>.talkdeskid.eu/oauth/token
  • CA: https://<your account name>.talkdeskca.com/oauth/token
  • UK: https://<your account name>.talkdeskid.co.uk/oauth/token

Creating OAuth Clients

Follow Creating a New OAuth Client to create a new OAuth Client in Talkdesk.

Note: If the account already has an OAuth Client, you can add these two scopes directly to your existing OAuth Client.

  • Grant type: Client credentials, Refresh token.
  • Scopes: digital-messaging-adapter.write.

Integration Input Schema

Set the following input schema on the integration:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "The root schema",
  "type": "object",
  "properties": {
    "template_name": {
      "type": "string",
      "title": "template_name"
    },
    "last_received_message_metadata": {
      "type": "string",
      "title": "last_received_message_metadata"
    },
    "state": {
      "type": "string",
      "title": "state"
    }
  },
  "required": [
    "template_name"
  ],
  "additionalProperties": false
}

 

Rich UI integration input schema configuration.

Creating and Customizing Rich Visuals

Overview

Navigate to Admin on the left sidebar, click Channels, select Chat, and open the Rich visuals tab to access Rich Visuals. This empowers administrators to create, customize, and publish Rich UI components such as button lists, carousels, quick replies, and forms, turning standard chat conversations into dynamic, agentic visual experiences. Every saved template generates a unique identifier (such as product_list_carousel) that you must reference directly inside your AI Agent prompts.

Note: Administrator permissions are required to edit or publish visuals, and unpublished updates remain saved as working drafts.

The Rich visuals tab, listing saved rich visuals.

Creating a Rich Visual

In the Rich Visuals tab, an administrator can create, customize, publish, rename, duplicate, and delete a Rich Visual.

  • Create rich visual: To create a Rich Visual, navigate to Channels under Admin on the left sidebar, select Chat, open the Rich visuals tab, and click the Create rich visual button. This lets you design and customize interactive UIs, such as carousels and quick replies, transforming standard text conversations into engaging visual, agentic chat experiences.
  • Select template and create: Choose from Rich Visual template options, including "Button list," "Carousel," "Quick reply," and "Form," to build interactive UI components for agentic chat. Click Create to create the Rich Visual in draft status.
  • Name: When naming your visual, the name must contain only letters, numbers, and underscores, up to 100 characters. Each name must be unique, as it serves as the identifier referenced directly within your AI Agent prompts.

The Create rich visual dialog with template options.

Customizing Rich Visuals

After clicking Create rich visual, the workspace opens, where you can customize layouts, text, button styles, and interactive actions using LLM prompts before saving or publishing your draft.

The rich visual editor workspace with prompt panel and live preview.

Customize rich visuals: Within the editor, type natural language prompts in the chat input box and click Send to update layouts, text, style, and actions (payload, open URL, call to number), and scenario-based UI elements, previewing your UI changes on the page instantly.

For example:

  • Text update: "Change all button labels from 'Chat with us' to 'View details.'"
  • Action update: "Update the 'View details' button on the 1st card to open the link https://www.company.com/view."
  • Action update: "Update the 'View details' button on the 2nd card to call +112345678."
  • Style update: "Highlight the 1st button style to primary."
  • Scenario update: "Convert the form to a doctor appointment booking."

Sample prompts panel, accessible from the prompt input box.

Sample prompts: Click any sample prompt to populate the input box, edit the text if needed, and click Send to update your visuals instantly. Access these samples by clicking the purple icon on the left side of the input box for quick customization.

Save: Click Save to store your Rich Visual as a draft. You can return and resume editing at any time.

Publish: Click Publish to release your latest Rich Visual with an updated version number. AI Agents automatically use only the most recently published version in their prompts.

 

Previewing Rich Visuals

Preview in Chat Widget: Click the preview icon to instantly visualize your Chat Widget, and use the view toggles on the right to switch between "Expanded," "Side," or "Compact" modes.

Preview of the rich visual in the chat widget.

Preview JSON Schema: Click the JSON icon to preview the underlying schema that powers the visual display — the reference for the UI element state using dynamic content or data coming from APIs.

Side-by-side preview of the chat widget and its JSON schema.

 

Saving and Publishing Rich Visuals

  • Save: Click Save to store your Rich Visual as a draft. You can return and resume editing at any time.
  • Publish: Click Publish to release your latest Rich Visual with an updated version number. AI Agents automatically use only the most recently published version in their prompts.
  • Version: A Rich Visual maintains a single active published version. Clicking Edit creates a working draft, and publishing it automatically archives the current version, which you can restore at any time.

 

Setting Up the Rich Visuals Skill in AI Agent Platform

Adding Variables

AI Agent flow with the Variables panel open.

Add variables: In the AI Agent flow, two key variables help manage your Rich Visuals. The template_name variable stores and passes the unique name of the visual you created in the Rich Visual Builder, ensuring the Agent flow displays the correct design. The rich_ui_state variable maps data from an API, if required, to the proper visual UI state.

Set template name: In the AI Agent, set the template name in sub-agent prompts.

For example, set the appointment_button value to the {template_name} variable before executing the "main menu rich ui" skill.

 

Setting Up the Rich UI Skill Without State

This configuration enables a Rich UI within the AI Agent flow using fully static content. Predefined through the Rich Visuals Builder, these visual components render directly within the flow without relying on backend APIs or dynamic data retrieval.

  • Add Rich UI skill: Add the Rich UI skill under a sub-agent.
  • New workflow: Create a new workflow for the Rich UI skill.

Sub-agent flow with the Rich UI skill added.

Edit the workflow:

  • Start Flow — Variable: String - template_name.
  • Execute Action - Generate Rich UI:
    • Connection: select the previous Rich UI integration.
    • Action: select the previous action of the Rich UI integration.
    • Input: template_name = template_name; last_received_message_metadata = Last received message metadata (system variable).

Start Flow step in the Rich UI skill workflow.

Execute Action - Generate Rich UI configuration panel.

 

Setting Up the Rich UI Skill With State

This configuration enables a Rich Visual within the AI Agent flow using dynamic, real-time data. By connecting to APIs, visual components populate and render based on incoming information.

  • Add Rich UI skill: Add the Rich UI skill under a sub-agent.
  • New workflow: Create a new workflow for the Rich UI skill.
  • Set up integration for the API: Set up the integration for the data used by the Rich Visual coming from the API.

Sub-agent flow configured with a third-party API integration.

Edit the workflow:

  • Start Flow — Variable: String - template_name.
  • Execute Action - 3rd API:
    • Connection: select the previous third-party API integration.
    • Action: select the previous action of the third-party API integration.
    • Outputs: Workflow.rich_ui_input.
  • Function - Build Rich UI State: Based on the output of "Execute Action - API," map the API data to the UI state. Refer to the JSON schema of the Rich Visual created in the Builder for the mapping.
  • Execute Action - Create Rich UI:
    • Connection: select the previous Rich UI integration.
    • Action: select the previous action of the Rich UI integration.
    • Inputs: template_name = template_name; last_received_message_metadata = Last received message metadata (system variable); state = rich_ui_state.

Function step mapping API output to the Rich UI state.

Execute Action - Create Rich UI configuration panel.

 

Previewing Rich UI at Runtime and Troubleshooting

Test rich visuals: The AI Agent Platform's Test Orchestration module currently supports text-only chat output during agent workflow testing. It does not provide a runtime preview of Rich UI components within the test canvas.

To validate flow execution today, use the Agent work stream trace to inspect workflow progression, and publish your agent configuration to preview Rich Visual components inside the external chat widget.

Note: Native, in-test runtime preview of Rich UI visuals is planned and included on the product roadmap for a future release.

Test Orchestration module showing text-only chat output.

All Articles ""
Please sign in to submit a request.

Related to