Connect Ruut to your Website / Web applications

If you need to use live chat on a website, web application, or even a mobile application, you will need to create a website workspace. You can create as many website workspaces as you wish, and they will all be linked to one Ruut dashboard.

Here is an integration guide on how to set up the website workspace on Ruut:

Step 1: Connect from Dashboard

On the dashboard, as a new user, you will see an option to set up your workspace. Click on it, and it will take you directly to the workspace section, where you will find a list of channels you can set up in your workspace.

Step 2: Create a New Workspace

From the workspace section on Ruut, you need to create a new workspace. Select the website workspace, and it will open up its requirements. Follow the steps provided.

Step 3: Enter Necessary Information

When you click on the website channel to connect to your workspace, you will need to submit several items:

• Website Name: This is the name that will show on the Chat Widget.

• Website Domain: This is the domain or web URL of the website or application you are integrating.

• Blog URL: If you have a blog and want your users to read it directly from the chat widget, provide the link. The view will be rendered, allowing users to interact with it from the chat widget.

• Widget Color: Set your company’s primary color as the widget color to match your brand and business.

• Welcome Heading: This is the first text presented to your users when the chat widget is launched, e.g., "Welcome to Ruut Chat" or "Glad to have you join us here."

• Welcome Tagline: This tagline accompanies the welcome heading, e.g., "Ask us anything."

• Enable Greeting: If you want automated greetings when users first visit the chat widget, enable channel greeting. This will present another field where you can add a message for the greetings.

After inputting all the necessary fields, click "Create Inbox" to save your details. Once saved, proceed to the next step.

Step 4: Add Your Agent

Once your website channel has been connected, add your support staff to that workspace. Once that’s done, you are ready to use your website channel with any application you wish.

Step 5: Use Your Website Channel

Now that your website channel is created, you will be presented with a view like the image below.

For some applications you will be integrating with, you need to copy the entire script tag to the JavaScript section of your application. For mobile, WordPress, or other platforms, you will be required to copy the value of the Website token, which allows you to interact directly with the application.

For Developers

Identify a User (Set User Details)

Once Ruut is ready, you can identify a user using the setUser method.

This is optional but strongly recommended if your users are logged in.

<script>
  window.addEventListener("ruut:ready", function () {
    window.$ruut.setUser("USER_ID", {
      email: "[email protected]",
      name: "John Doe",
      avatar_url: "https://example.com/avatar.png",
      phone_number: "+2348012345678",
      identifier_hash: "SECURE_HASH",
      description: "Premium customer",
      country_code: "NG",
      city: "Lagos",
      company_name: "Ruut Inc",
      social_profiles: {
        twitter: "johndoe",
        linkedin: "john-doe",
        facebook: "john.doe",
        github: "johndoe"
      }
    });
  });
</script>

Required vs Optional Fields

Required

• USER_ID
  A unique identifier for the user in your system (string).

Common Optional Fields

• email

• name

• avatar_url

• phone_number

Advanced / Optional Fields

• identifier_hash (recommended for security)

• description

• country_code

• city

• company_name

• social_profiles

You can pass as many or as few fields as you need.

Secure User Identity with identifier_hash

For security-sensitive applications, Ruut supports identity verification using an identifier_hash.

This hash should be generated on your server using your Ruut secret key and the user’s ID.
It prevents impersonation and ensures user data integrity.

If you don’t need this, you can safely omit it.

Open the Chat Programmatically (Optional)

If you want to open the chat automatically once Ruut is ready:

<script>
  window.addEventListener("ruut:ready", function () {
    window.$ruut.toggle("open");
  });
</script>

Updating or Resetting a User

Update Custom Attributes

<script>
  window.$ruut.setCustomAttributes({
    plan: "pro",
    last_login: "2026-01-10"
  });
</script>

Remove a Custom Attribute

<script>
  window.$ruut.deleteCustomAttribute("plan");
</script>

Reset User Session

<script>
  window.$ruut.reset();
</script>

This is useful when a user logs out.

Need more help with setting up your live chat workspace, speak to your account manager directly.

Or reach us at [email protected]