Embedding Widget

This guide covers everything you need to embed the Ringyo AI chat widget on your website, including code examples and advanced configuration.

Basic Embed

Add this snippet before the closing </body> tag:

<script
  src="https://widget.ringyo.ai/chat.js"
  data-agent-id="YOUR_AGENT_ID"
  async
></script>

That’s it — the widget will appear in the bottom-right corner of your page.

Full Configuration

<script
  src="https://widget.ringyo.ai/chat.js"
  data-agent-id="YOUR_AGENT_ID"
  data-color="#0D9488"
  data-position="bottom-right"
  data-welcome="Hi! How can I help you today?"
  data-name="Support Agent"
  data-avatar="https://yoursite.com/avatar.png"
  data-hide-branding="false"
  data-auto-open="false"
  data-delay="3000"
  async
></script>

Attribute Reference

Attribute	Type	Default	Description
`data-agent-id`	string	required	Your agent’s ID (from Dashboard → Agents)
`data-color`	hex string	`#0D9488`	Primary accent color
`data-position`	string	`bottom-right`	`bottom-right` or `bottom-left`
`data-welcome`	string	”Hi! How can I help?”	Initial message shown to visitors
`data-name`	string	Agent name	Display name in chat header
`data-avatar`	URL	Ringyo default	Agent avatar image URL
`data-hide-branding`	boolean	`false`	Hide “Powered by Ringyo” (Pro+)
`data-auto-open`	boolean	`false`	Auto-open widget on page load
`data-delay`	number	`0`	Delay before auto-open (ms)

JavaScript API

Control the widget programmatically after it loads:

// Open the widget
window.RingyoChat.open();

// Close the widget
window.RingyoChat.close();

// Toggle open/closed
window.RingyoChat.toggle();

// Send a message programmatically
window.RingyoChat.sendMessage('I need to book an appointment');

// Set visitor info (for personalization)
window.RingyoChat.setVisitor({
  name: 'Jane Smith',
  email: 'jane@example.com',
  phone: '+1234567890'
});

Framework Examples

React
Next.js
Vue

import { useEffect } from 'react';

function ChatWidget() {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://widget.ringyo.ai/chat.js';
    script.setAttribute('data-agent-id', 'YOUR_AGENT_ID');
    script.async = true;
    document.body.appendChild(script);

    return () => document.body.removeChild(script);
  }, []);

  return null;
}

export default ChatWidget;

import Script from 'next/script';

export default function Layout({ children }) {
  return (
    <>
      {children}
      <Script
        src="https://widget.ringyo.ai/chat.js"
        data-agent-id="YOUR_AGENT_ID"
        strategy="lazyOnload"
      />
    </>
  );
}

<script setup>
import { onMounted, onUnmounted } from 'vue';

let script;

onMounted(() => {
  script = document.createElement('script');
  script.src = 'https://widget.ringyo.ai/chat.js';
  script.setAttribute('data-agent-id', 'YOUR_AGENT_ID');
  script.async = true;
  document.body.appendChild(script);
});

onUnmounted(() => {
  if (script) document.body.removeChild(script);
});
</script>

Event Callbacks

Listen for widget events:

window.addEventListener('ringyo:ready', () => {
  console.log('Widget loaded');
});

window.addEventListener('ringyo:message', (e) => {
  console.log('New message:', e.detail);
});

window.addEventListener('ringyo:open', () => {
  console.log('Widget opened');
});

window.addEventListener('ringyo:close', () => {
  console.log('Widget closed');
});

Use event callbacks to trigger custom analytics or integrate with your app’s state management.

Next Steps

Chat Widget — basic setup guide
Custom Branding — style the widget to match your brand

Getting Started

Dashboard Guide

Core Concepts

Integrations

Advanced

Embedding Widget

Basic Embed

Full Configuration

Attribute Reference

JavaScript API

Framework Examples

Event Callbacks

Next Steps

​Embedding Widget

​Basic Embed

​Full Configuration

​Attribute Reference

​JavaScript API

​Framework Examples

​Event Callbacks

​Next Steps

Embedding Widget

Basic Embed

Full Configuration

Attribute Reference

JavaScript API

Framework Examples

Event Callbacks

Next Steps