Embedding Widget Chat

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 a component.

Configure chat-specific tools

Build the Components the chat needs, such as a slot picker for callbacks or a form for data collection, and add any API integrations it 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, components, and other configured tools work in chat mode.

Interactive components

Cards, forms and pickers the assistant shows mid-conversation are built as Components. See Components for how to create them, mention them in a prompt, and wire them to your APIs. They work best in text mode, though they can also be triggered during voice calls.

Deprecated. The fixed-purpose Calendar and Form widgets below (the send_widgets tool with calender_widget_tool / form_widget_tool) are legacy, and the reference is kept here for agents already using them. Existing agents keep working, but new builds should use Components, since a carousel of plan cards, a booking form, or a rating card are all expressible as blocks, with layout and API wiring you control.

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",
    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",
    },
  });
});

Components and legacy widgets are both configured in the Ringg AI dashboard. No additional frontend code is needed for the interactive UI itself.

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 component, and mention it by its @[[name]] at that point in the prompt.

Do not duplicate a component’s fields in the conversation, and let it collect them.

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

Keep chat responses shorter and more structured than voice responses.

Get Started

API Reference

Webhooks Setup

Telephony Integration

MCP Server

External Integrations

Privacy and Compliance

Embedding Widget Chat

Set up a chat agent

Chat modes

How chat mode works

Text input and output

Context compression

RAG summarization

Same configured tools

Interactive components

Calendar widget (legacy)

Form widget (legacy)

Form field definition

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

​Interactive components

​Calendar widget (legacy)

​Form widget (legacy)

​Form field definition

​Complete chat-only embed

​Prompt examples

​Prompt tips

Set up a chat agent

Chat modes

How chat mode works

Interactive components

Calendar widget (legacy)

Form widget (legacy)

Form field definition

Complete chat-only embed

Prompt examples

Prompt tips