Embedding Widget Chat and Components

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

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.

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.

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.

Configure chat-specific tools

Add calendar widgets for callback scheduling, form widgets for data collection, or any API integrations the chat should use.

Use the chat assistant ID

Use the cloned assistant’s agentId in the embed code and set defaultTab to "text".

Chat modes

Chat first
Chat only
Voice and chat

loadAgent({
  agentId: "your-chat-agent-id",
  authorization: "Bearer your-webcall-public-key",
  defaultTab: "text",
});

loadAgent({
  agentId: "your-chat-agent-id",
  authorization: "Bearer your-webcall-public-key",
  defaultTab: "text",
  hideTabSelector: true,
});

loadAgent({
  agentId: "your-agent-id",
  authorization: "Bearer your-webcall-public-key",
  defaultTab: "audio",
  hideTabSelector: false,
});

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

Text input and output

Users send typed messages. Audio input and output are disabled in text mode.

Context compression

Long chat conversations are compressed automatically so the conversation can continue within model context limits.

RAG summarization

Knowledge base query results are summarized in chat mode to reduce token usage and keep answers concise.

Same configured tools

API integrations, knowledge base queries, widgets, and other configured tools work in chat mode.

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.

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

The flow is:

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

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.

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

The required tool_type value is calender_widget_tool. Use that exact spelling in widget metadata.

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.

{
  "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. 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.

{
  "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.

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.

How it works:

The assistant resolves a fully-concrete block tree server-side (bindings filled, lists expanded) and streams it.
The widget renders it full-width in the transcript.
The user taps a button, fills inputs, or picks a rating.
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.

Complete chat-only embed

Use the CDN loader from the quickstart, then load the chat assistant with chat-only mode and optional branding.

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

Callback scheduling
Form collection
Calendar and form

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.

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.

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.

Prompt tips

Be explicit about when to use each widget.

Do not duplicate widget fields in the conversation.

Ask the assistant to confirm bookings and form submissions after the widget returns data.

Keep chat responses shorter and more structured than voice responses.

Get Started

API Reference

Webhooks Setup

Telephony Integration

External Integrations

Embedding Widget Chat and Components

Set up a chat agent

Chat modes

How chat mode works

Text input and output

Context compression

RAG summarization

Same configured tools

Components

Calendar widget (legacy)

Form widget (legacy)

Form field definition

Block Kit — the Components system

Complete chat-only embed

Prompt examples

Prompt tips

​Set up a chat agent

​Chat modes

​How chat mode works

Text input and output

Context compression

RAG summarization

Same configured tools

​Components

​Calendar widget (legacy)

​Form widget (legacy)

​Form field definition

​Block Kit — the Components system

​Complete chat-only embed

​Prompt examples

​Prompt tips

Set up a chat agent

Chat modes

How chat mode works

Components

Calendar widget (legacy)

Form widget (legacy)

Form field definition

Block Kit — the Components system

Complete chat-only embed

Prompt examples

Prompt tips