> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ringg.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Embedding Widget Chat and Components

> Configure chat mode, chat-only embeds, interactive Components (Block Kit), and chat assistant prompts.

The Ringg widget supports text-based chat alongside voice calls. In chat mode, users type messages while the same assistant can still use configured tools, knowledge base queries, and interactive Components.

## Set up a chat agent

<Tip>
  Create a dedicated assistant for chat by cloning your voice assistant. Chat conversations are usually longer and benefit from prompts that allow structured answers, concise markdown, and clear widget handoffs.
</Tip>

<Steps>
  <Step title="Clone or create an assistant">
    Open the Ringg AI dashboard, go to assistants, and clone an existing voice assistant or create a new Webcall assistant for chat.
  </Step>

  <Step title="Tune the prompt for text">
    Update the assistant prompt for chat-style responses. Include when to answer directly, when to collect details, and when to present widgets.
  </Step>

  <Step title="Configure chat-specific tools">
    Add calendar widgets for callback scheduling, form widgets for data collection, or any API integrations the chat should use.
  </Step>

  <Step title="Use the chat assistant ID">
    Use the cloned assistant's `agentId` in the embed code and set `defaultTab` to `"text"`.
  </Step>
</Steps>

## Chat modes

<Tabs>
  <Tab title="Chat first">
    ```javascript theme={null}
    loadAgent({
      agentId: "your-chat-agent-id",
      authorization: "Bearer your-webcall-public-key",
      defaultTab: "text",
    });
    ```
  </Tab>

  <Tab title="Chat only">
    ```javascript theme={null}
    loadAgent({
      agentId: "your-chat-agent-id",
      authorization: "Bearer your-webcall-public-key",
      defaultTab: "text",
      hideTabSelector: true,
    });
    ```
  </Tab>

  <Tab title="Voice and chat">
    ```javascript theme={null}
    loadAgent({
      agentId: "your-agent-id",
      authorization: "Bearer your-webcall-public-key",
      defaultTab: "audio",
      hideTabSelector: false,
    });
    ```
  </Tab>
</Tabs>

| Option              | Type                | Default   | Description                                                                                       |
| ------------------- | ------------------- | --------- | ------------------------------------------------------------------------------------------------- |
| `defaultTab`        | `"audio" \| "text"` | `"audio"` | Tab shown when the widget loads. Use `"text"` for chat mode. Supported from v1.0.8+.              |
| `hideTabSelector`   | `boolean`           | `false`   | Hides the audio/text tab switcher for a single-mode experience. Supported from v1.0.8+.           |
| `bypassStartScreen` | `boolean`           | `false`   | Skips the start screen and begins a call or chat immediately on trigger click. Uses `defaultTab`. |

## How chat mode works

<CardGroup cols={2}>
  <Card title="Text input and output" icon="keyboard">
    Users send typed messages. Audio input and output are disabled in text mode.
  </Card>

  <Card title="Context compression" icon="archive">
    Long chat conversations are compressed automatically so the conversation can continue within model context limits.
  </Card>

  <Card title="RAG summarization" icon="book-open">
    Knowledge base query results are summarized in chat mode to reduce token usage and keep answers concise.
  </Card>

  <Card title="Same configured tools" icon="wrench">
    API integrations, knowledge base queries, widgets, and other configured tools work in chat mode.
  </Card>
</CardGroup>

## Components

Components are interactive UI the assistant presents during a conversation — cards, forms, pickers, ratings, and more — rendered inside the chat so users can act without leaving it. Components are built with **Block Kit** (see below) and are the current standard for all new builds.

<Note>
  Components work best in text mode. They can also be triggered during voice calls, but visual interaction is most natural in the chat interface.
</Note>

The flow is:

1. The assistant decides a component is needed and streams a Block Kit tree.
2. The component renders inside the chat.
3. The user taps a button, fills inputs, or picks a rating.
4. The response is sent back to the assistant automatically.
5. The assistant confirms the action and can trigger an API call if configured.

<Warning>
  The fixed-purpose **Calendar** and **Form** widgets below (the `send_widgets` tool with `calender_widget_tool` / `form_widget_tool`) are **legacy**. Existing agents keep working, but new builds should use **Components** (Block Kit) — a carousel of plan cards, a booking form, or a rating card are all expressible as blocks.
</Warning>

## Calendar widget (legacy)

Use the calendar widget for callback scheduling, demo booking, consultations, or follow-up appointments. Past slots are excluded so users see valid options.

<Warning>
  The required `tool_type` value is `calender_widget_tool`. Use that exact spelling in widget metadata.
</Warning>

| Field                       | Type      | Required | Description                                           |
| --------------------------- | --------- | -------- | ----------------------------------------------------- |
| `tool_type`                 | `string`  | Yes      | Must be `"calender_widget_tool"`.                     |
| `tool_id`                   | `string`  | Yes      | Unique identifier for this widget instance.           |
| `slot_duration_days`        | `integer` | Yes      | Number of days to show slots for, such as `7`.        |
| `slot_interval_minutes`     | `integer` | Yes      | Minutes between each slot, such as `30`.              |
| `start_time_24_hour_format` | `string`  | Yes      | Slot start time in `HH:MM` format, such as `"09:00"`. |
| `end_time_24_hour_format`   | `string`  | Yes      | Slot end time in `HH:MM` format, such as `"17:00"`.   |
| `timezone`                  | `string`  | Yes      | IANA timezone, such as `"Asia/Kolkata"`.              |
| `api_config`                | `object`  | No       | Optional API call made when the user selects a slot.  |

```json theme={null}
{
  "tool_type": "calender_widget_tool",
  "tool_id": "callback_scheduler",
  "slot_duration_days": 7,
  "slot_interval_minutes": 30,
  "start_time_24_hour_format": "09:00",
  "end_time_24_hour_format": "17:00",
  "timezone": "Asia/Kolkata",
  "api_config": {
    "url": "https://your-api.com/schedule-callback",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer your-token",
      "Content-Type": "application/json"
    },
    "body": {}
  }
}
```

When a user schedules a callback, the selected datetime and timezone are sent back to the assistant. If `api_config` is provided, the booking data is forwarded to your API.

## Form widget (legacy)

Use the form widget for contact details, lead qualification, support tickets, addresses, surveys, or other structured data collection.

| Field                 | Type     | Required | Description                                        |
| --------------------- | -------- | -------- | -------------------------------------------------- |
| `tool_type`           | `string` | Yes      | Must be `"form_widget_tool"`.                      |
| `tool_id`             | `string` | Yes      | Unique identifier for this widget instance.        |
| `title`               | `string` | Yes      | Title displayed at the top of the form.            |
| `submit_button_label` | `string` | Yes      | Text on the submit button, such as `"Submit"`.     |
| `form_fields`         | `array`  | Yes      | Array of field definitions.                        |
| `api_config`          | `object` | No       | Optional API call made when the form is submitted. |

### Form field definition

| Field         | Type      | Required | Description                                                         |
| ------------- | --------- | -------- | ------------------------------------------------------------------- |
| `key`         | `string`  | Yes      | Unique field identifier.                                            |
| `type`        | `string`  | Yes      | Field type, such as `"text"`, `"email"`, `"select"`, or `"number"`. |
| `description` | `string`  | Yes      | Label or placeholder text for the field.                            |
| `required`    | `boolean` | Yes      | Whether the field is mandatory.                                     |
| `options`     | `array`   | No       | Options list for select fields.                                     |

```json theme={null}
{
  "tool_type": "form_widget_tool",
  "tool_id": "contact_form",
  "title": "Contact Information",
  "submit_button_label": "Submit Details",
  "form_fields": [
    {
      "key": "full_name",
      "type": "text",
      "description": "Full Name",
      "required": true,
      "options": []
    },
    {
      "key": "email",
      "type": "email",
      "description": "Email Address",
      "required": true,
      "options": []
    },
    {
      "key": "preferred_plan",
      "type": "select",
      "description": "Preferred Plan",
      "required": false,
      "options": ["Basic", "Pro", "Enterprise"]
    }
  ],
  "api_config": {
    "url": "https://your-api.com/contacts",
    "method": "POST",
    "headers": {
      "Content-Type": "application/json"
    },
    "body": {}
  }
}
```

When the user submits the form, the collected data is sent back to the assistant. If `api_config` is provided, the data is also forwarded to your API endpoint.

## Block Kit — the Components system

Block Kit is the engine behind **Components**: the assistant builds a tree of typed blocks (cards, carousels, tables, inputs, buttons, ratings, and more) that render inside the chat. Unlike the fixed legacy calendar and form widgets, Block Kit lets the assistant lay out arbitrary content — plan comparisons, order trackers, feedback cards, or rich confirmations — and is the recommended path for all new builds.

<Note>
  Block Kit trees are streamed on the `ringg.blocks` topic (not a fixed tool), so payloads have no practical size limit. The widget renders them and reports interactions back to the assistant automatically.
</Note>

How it works:

1. The assistant resolves a fully-concrete block tree server-side (bindings filled, lists expanded) and streams it.
2. The widget renders it full-width in the transcript.
3. The user taps a button, fills inputs, or picks a rating.
4. The interaction is sent back to the assistant; a tap is treated as one conversation turn, so the card locks after responding.

The block **type catalog** (currently `1.4`) defines the available blocks and their props:

| Group   | Types                                                                                                                                                                                          |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Layout  | `box`, `row`, `column`, `card`, `carousel`, `form`, `expander`                                                                                                                                 |
| Content | `header`, `text`, `image`, `divider`, `badge`, `callout`, `facts`, `table`, `steps`                                                                                                            |
| Inputs  | `input_text`, `input_email`, `input_phone_number`, `input_number`, `input_date`, `input_time`, `input_textarea`, `input_checkbox`, `input_single_select`, `input_multi_select`, `input_rating` |
| Action  | `button`                                                                                                                                                                                       |

Most content and action blocks share a `size` (`sm` / `md` / `lg`) and `align` vocabulary; `image` uses `width` (`sm` / `md` / `full`) and `button` supports `full_width`. Blocks inherit the widget theme (colors, radius, button style), and every rendered node exposes a `data-ringg="block-<type>"` hook for CSS — see [Customization](/get-started/guides/embedding-widget-customization#block-kit).

## Complete chat-only embed

Use the CDN loader from the [quickstart](/get-started/guides/embedding-widget), then load the chat assistant with chat-only mode and optional branding.

```javascript theme={null}
loadAgentsCdn("latest", function () {
  loadAgent({
    agentId: "your-chat-agent-id",
    authorization: "Bearer your-webcall-public-key",
    defaultTab: "text",
    hideTabSelector: true,
    title: "Support Chat",
    description: "Hi! I can help you schedule a callback or answer your questions.",
    logoUrl: "https://example.com/your-logo.svg",
    buttons: {
      modalTrigger: {
        styles: {
          backgroundColor: "#4F46E5",
        },
        icon: {
          url: "https://example.com/chat-icon.svg",
          size: 24,
        },
      },
    },
    feedbackScreen: {
      title: "How was your chat?",
      description: "Your feedback helps us improve!",
      submitBtnCTA: "Submit",
    },
  });
});
```

Calendar and form widgets are configured in the assistant metadata through the Ringg AI dashboard. No additional frontend code is needed for the widgets themselves.

## Prompt examples

<Tabs>
  <Tab title="Callback scheduling">
    ```text theme={null}
    You are a friendly support assistant for [Company Name]. You help users with
    their questions and can schedule callbacks with our team.

    Guidelines:
    - Greet the user warmly and ask how you can help.
    - Answer questions using the knowledge base when available.
    - If the user wants to speak to a human agent, schedule a call, or book a demo,
      present the calendar widget so they can pick a convenient time slot.
    - After the user selects a time slot, confirm the booking with the date, time,
      and timezone in a clear, human-readable format.
    - Keep responses concise and conversational. This is a chat, not an email.
    ```
  </Tab>

  <Tab title="Form collection">
    ```text theme={null}
    You are a lead qualification assistant for [Company Name]. Your goal is to
    understand the user's needs and collect their contact information.

    Guidelines:
    - Start by understanding what the user is looking for.
    - Once you have enough context about their needs, present the contact form
      widget to collect their details: name, email, phone, and preferred plan.
    - After the form is submitted, thank the user and let them know a team member
      will follow up shortly.
    - Do not ask for information that the form will collect. Let the form handle it.
    ```
  </Tab>

  <Tab title="Calendar and form">
    ```text theme={null}
    You are a customer support assistant for [Company Name]. You can help users
    with questions, collect information, and schedule callbacks.

    Guidelines:
    - Greet the user and ask how you can help.
    - For general questions, answer directly using available knowledge.
    - If the user needs to speak with a human agent or wants a demo, present the
      calendar widget to schedule a callback.
    - If the user wants to submit a request, provide feedback, or share details,
      present the form widget to collect their information.
    - Always confirm the action after a widget interaction, such as "Your callback
      is booked for Tuesday at 2:00 PM" or "Thanks, we have received your details."
    - Keep responses short and friendly.
    ```
  </Tab>
</Tabs>

## Prompt tips

<Check>Be explicit about when to use each widget.</Check>
<Check>Do not duplicate widget fields in the conversation.</Check>
<Check>Ask the assistant to confirm bookings and form submissions after the widget returns data.</Check>
<Check>Keep chat responses shorter and more structured than voice responses.</Check>