Embedding Widget Chat and Widgets

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, callback scheduling, and form widgets.

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",
  xApiKey: "your-api-key",
  defaultTab: "text",
});

loadAgent({
  agentId: "your-chat-agent-id",
  xApiKey: "your-api-key",
  defaultTab: "text",
  hideTabSelector: true,
});

loadAgent({
  agentId: "your-agent-id",
  xApiKey: "your-api-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.

Chat widgets

Chat widgets are interactive UI components the assistant can present during a conversation. They render inside the chat interface so users can schedule callbacks, submit forms, or book appointments without leaving the widget.

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

The widget flow is:

The assistant decides a widget is needed and calls the send_widgets tool.
The widget renders inside the chat.
The user selects a time slot or submits form data.
The response is sent back to the assistant automatically.
The assistant confirms the action and can trigger an API call if api_config is provided.

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.

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",
    xApiKey: "your-api-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

Embedding Widget Chat and Widgets

Set up a chat agent

Chat modes

How chat mode works

Text input and output

Context compression

RAG summarization

Same configured tools

Chat widgets

Calendar widget

Form widget

Form field definition

Complete chat-only embed

Prompt examples

Prompt tips

Get Started

API Reference

Webhooks Setup

Telephony Integration

Documentation Index

​Set up a chat agent

​Chat modes

​How chat mode works

Text input and output

Context compression

RAG summarization

Same configured tools

​Chat widgets

​Calendar widget

​Form widget

​Form field definition

​Complete chat-only embed

​Prompt examples

​Prompt tips

Set up a chat agent

Chat modes

How chat mode works

Chat widgets

Calendar widget

Form widget

Form field definition

Complete chat-only embed

Prompt examples

Prompt tips