@robylon/whatsapp-react-sdk

v1.0.7

Published

5 days ago

React SDK for Robylon WhatsApp

0High
0Medium
0Low

mayank-robylon

alanastor

react chatbot ai robylon support

Robylon SDK

The Robylon SDK provides an easy way to integrate a customizable chatbot into your application. This SDK supports both React applications and plain JavaScript/no-code websites.

Installation

For React applications:

npm install @robylon/whatsapp-react-sdk
# or
yarn add @robylon/whatsapp-react-sdk

For plain JavaScript and no-code websites:

Add this script to your website by copying and pasting the following code into the <head> section of your HTML:

<script src="https://cdn.robylon.ai/whatsapp-sdk/latest/chatbot.js"></script>

Where to place the script:

For website builders (Wix, Squarespace, etc.):
- Find your site editor or dashboard
- Look for "Custom Code", "Header Code", or "Site Settings" options
- Paste the script there, usually in a section labeled "Header" or "Head"
For custom HTML sites:
- Open your website's HTML file in your editor
- Find the <head> section (it's near the top, between <html> and <body> tags)
- Paste the script tag just before the closing </head> tag
For WordPress:
- Go to your WordPress dashboard
- Navigate to Appearance → Theme Editor or use a header/footer plugin
- Add the script to the header.php file before the closing </head> tag

Note: Some of the integration options later in this guide will show different placements of this script - follow the specific example that best matches your needs.

React SDK Usage

React: Basic Implementation

To use the Robylon SDK in a React application:

import { Chatbot } from "@robylon/whatsapp-react-sdk";

function App() {
  const handleChatbotEvent = (event) => {
    console.log("Chatbot event:", event.type, event.data);
  };

  return (
    <div className="App">
      <h1>My Website</h1>

      <Chatbot
        api_key="YOUR_API_KEY"
        user_id="optional-user-id"
        user_token="optional-auth-token"
        user_profile={{
          name: "Optional User Name",
          email: "[email protected]",
        }}
        onEvent={handleChatbotEvent}
      />
    </div>
  );
}

export default App;

React: Event Handling

The React component accepts an onEvent prop for handling chatbot events:

<Chatbot
  api_key="YOUR_API_KEY"
  onEvent={(event) => {
    switch (event.type) {
      case "CHATBOT_LOADED":
        console.log("Chatbot loaded");
        break;
      case "CHATBOT_OPENED":
        console.log("Chatbot opened");
        break;
      case "CHATBOT_CLOSED":
        console.log("Chatbot closed");
        break;
      // See the Supported Events section for all available events
    }
  }}
/>

The Chatbot component renders a floating button that opens a chat interface when clicked. It handles all the communication with the Robylon backend services.

React: External Triggers

You can control the chatbot iframe from outside the component using a ref. This allows you to trigger open, close, or toggle actions from anywhere in your application:

import React, { useRef, useState, useEffect } from "react";
import { Chatbot, ChatbotRef } from "@robylon/whatsapp-react-sdk";

function App() {
  const chatbotRef = useRef < ChatbotRef > null;
  const [isChatbotReady, setIsChatbotReady] = useState(false);

  // Method 1: Check readiness state before calling methods
  const showChatbot = () => {
    if (chatbotRef.current?.isReady) {
      chatbotRef.current.show();
    } else {
      console.log("Chatbot not ready yet");
    }
  };

  const hideChatbot = () => {
    chatbotRef.current?.hide();
  };

  const toggleChatbot = () => {
    chatbotRef.current?.toggle();
  };

  // Method 2: Listen for ready event
  const handleChatbotEvent = (event) => {
    if (event.type === "CHATBOT_READY") {
      setIsChatbotReady(true);
    }
  };

  return (
    <div className="App">
      <h1>My Website</h1>

      {/* External control buttons with readiness state */}
      <button onClick={showChatbot} disabled={!isChatbotReady}>
        Show Chatbot
      </button>
      <button onClick={hideChatbot}>Hide Chatbot</button>
      <button onClick={toggleChatbot}>Toggle Chatbot</button>

      <Chatbot
        ref={chatbotRef}
        api_key="YOUR_API_KEY"
        user_id="optional-user-id"
        onEvent={handleChatbotEvent}
      />
    </div>
  );
}

Available External Methods & Properties

| Method/Property | Type | Description | | --------------- | -------- | ------------------------------------------------------ | | show() | function | Opens the chatbot iframe if it's currently closed | | hide() | function | Closes the chatbot iframe if it's currently open | | toggle() | function | Toggles the chatbot iframe visibility | | isReady | boolean | Indicates if the chatbot is ready for external control |

Event Handling with External Triggers

External trigger methods emit the same events as internal triggers:

CHATBOT_BUTTON_CLICKED - When show() or toggle() opens the chatbot
CHATBOT_CLOSED - When hide() or toggle() closes the chatbot
CHATBOT_READY - When the chatbot is ready for external control (emitted once after initialization)

This ensures consistent event handling regardless of how the chatbot is triggered.

Readiness Handling

The SDK provides multiple ways to handle chatbot readiness:

Check isReady property - Synchronous check before calling methods
Listen for CHATBOT_READY event - Event-based notification when ready
Guard clauses - Methods safely handle early calls with console warnings

This prevents race conditions and provides a smooth user experience.

Plain JavaScript & No-Code Integration

IMPORTANT: You will need an API key from Robylon for any integration to work.

Quick Embed (Easiest Method)

This is the simplest way to add the Robylon chatbot to any website with a single line of code. Just copy and paste this script tag into your HTML:

<script>(function(k){window.R=window.R||function(){(window.R.q=window.R.q||[]).push(arguments)};window.R=new Proxy(window.R,{get:(t,p)=>p==="q"?t.q:(...a)=>t(p,...a)});function l(){var s=document.createElement("script");s.src="https://cdn.robylon.ai/whatsapp-sdk/latest/chatbot.js";s.onload=()=>k&&window.RobylonChatbot.create({api_key:k});document.body.appendChild(s)}document.readyState==="complete"?l():window.addEventListener("load",l)})("YOUR_API_KEY_HERE");</script>

Just replace YOUR_API_KEY_HERE with your actual Robylon API key, and you're done! No additional code is needed.

ES5/Google Tag Manager

ES5 Compatible Version

For older browsers that don't support ES6 features, use this ES5 compatible version:

<script>(function(a){window.R=window.R||function(){(window.R.q=window.R.q||[]).push(Array.prototype.slice.call(arguments))};window.R.show=function(){window.R('show')};window.R.hide=function(){window.R('hide')};window.R.toggle=function(){window.R('toggle')};window.R.track=function(){window.R('track',Array.prototype.slice.call(arguments))};var o=function(){var s=document.createElement("script");s.src="https://cdn.robylon.ai/whatsapp-sdk/latest/chatbot.js";s.id="robylon-chatbot-sdk";s.onload=function(){if(a){window.RobylonChatbot.create({api_key:a})}};document.body.appendChild(s)};if(document.readyState==="complete"){o()}else{window.addEventListener("load",o)}})("YOUR_API_KEY_HERE");</script>

This version is compatible with Internet Explorer 11 and other older browsers that don't support ES6 features like arrow functions, const/let, and Proxy objects.

Quick Embed with Custom Position and Spacing

If you want to customize the position and spacing of the chatbot button, you can use this alternative version:

<script>(function(k,p,side,bottom){window.R=window.R||function(){(window.R.q=window.R.q||[]).push(arguments)};window.R=new Proxy(window.R,{get:(t,p)=>p==="q"?t.q:(...a)=>t(p,...a)});function l(){var s=document.createElement("script");s.src="https://cdn.robylon.ai/whatsapp-sdk/latest/chatbot.js";s.onload=()=>k&&window.RobylonChatbot.create({api_key:k,position:p,sideSpacing:side,bottomSpacing:bottom});document.body.appendChild(s)}document.readyState==="complete"?l():window.addEventListener("load",l)})("YOUR_API_KEY_HERE","Left",30,25);</script>

Just replace:

YOUR_API_KEY_HERE with your actual API key
"Left" with "Left" or "Right" for button position
30 with your desired side spacing in pixels
25 with your desired bottom spacing in pixels

ES5 Compatible Version with Custom Position and Spacing

For older browsers, use this ES5 compatible version with custom positioning:

<script>(function(a,p,s,b){window.R=window.R||function(){(window.R.q=window.R.q||[]).push(Array.prototype.slice.call(arguments))};window.R.show=function(){window.R('show')};window.R.hide=function(){window.R('hide')};window.R.toggle=function(){window.R('toggle')};window.R.track=function(){window.R('track',Array.prototype.slice.call(arguments))};var o=function(){var s=document.createElement("script");s.src="https://cdn.robylon.ai/whatsapp-sdk/latest/chatbot.js";s.id="robylon-chatbot-sdk";s.onload=function(){if(a){window.RobylonChatbot.create({api_key:a,position:p,sideSpacing:s,bottomSpacing:b})}};document.body.appendChild(s)};if(document.readyState==="complete"){o()}else{window.addEventListener("load",o)}})("YOUR_API_KEY_HERE","Left",30,25);</script>

Replace the same parameters as above for the ES5 compatible version.

Where to place the script:

At the end of your HTML <body> section for best performance
Or anywhere in your HTML code if you're using a website builder

There are several other ways to add the Robylon chatbot to your website or no-code platform, depending on your needs:

Option 1: Quick Setup - Load with Page

This is the simplest approach for any website. The chatbot loads while the page is loading but doesn't block the page from appearing.

What to copy:

1️⃣ Add this to your HTML <head> section:

<script
  src="https://cdn.robylon.ai/whatsapp-sdk/latest/robylon-chatbot.js"
  defer
></script>
<script>
  // Initialize when page is ready
  document.addEventListener("DOMContentLoaded", () => {
    RobylonChatbot.create({
      api_key: "YOUR_API_KEY", // Replace with your actual API key
      user_id: "optional-user-id", // Optional: remove if not needed
      user_profile: {
        name: "Optional User Name", // Optional: remove if not needed
        email: "[email protected]", // Optional: remove if not needed
      },
    });
  });
</script>

Complete example:

<!DOCTYPE html>
<html>
  <head>
    <title>Robylon SDK - Quick Setup</title>
    <!-- COPY FROM HERE -->
    <script
      src="https://cdn.robylon.ai/whatsapp-sdk/latest/robylon-chatbot.js"
      defer
    ></script>
    <script>
      // Initialize when page is ready
      document.addEventListener("DOMContentLoaded", () => {
        RobylonChatbot.create({
          api_key: "YOUR_API_KEY", // Replace with your actual API key
          user_id: "optional-user-id", // Optional: remove if not needed
          user_profile: {
            name: "Optional User Name", // Optional: remove if not needed
            email: "[email protected]", // Optional: remove if not needed
          },
        });
      });
    </script>
    <!-- COPY UNTIL HERE -->
  </head>
  <body>
    <h1>Your Website Content</h1>
    <!-- Your website content here -->
  </body>
</html>

Option 2: Reliable Loading - After DOM is Ready

This approach ensures the chatbot only initializes after your page is fully loaded, making it more reliable for websites with complex layouts.

What to copy:

1️⃣ Add this to your HTML <head> section:

<script src="https://cdn.robylon.ai/whatsapp-sdk/latest/robylon-chatbot.js"></script>

2️⃣ Add this at the end of your HTML <body> section:

<script>
  // Wait for page to be fully loaded before showing chatbot
  document.addEventListener("DOMContentLoaded", () => {
    RobylonChatbot.create({
      api_key: "YOUR_API_KEY", // Replace with your actual API key
      user_id: "optional-user-id", // Optional: remove if not needed
      user_profile: {
        name: "Optional User Name", // Optional: remove if not needed
        email: "[email protected]", // Optional: remove if not needed
      },
    });
  });
</script>

Complete example:

<!DOCTYPE html>
<html>
  <head>
    <title>Robylon SDK - Reliable Loading</title>
    <!-- COPY FROM HERE -->
    <script src="https://cdn.robylon.ai/whatsapp-sdk/latest/robylon-chatbot.js"></script>
    <!-- COPY UNTIL HERE -->
  </head>
  <body>
    <h1>Your Website Content</h1>
    <!-- Your website content here -->

    <script>
      // Wait for page to be fully loaded before showing chatbot
      document.addEventListener("DOMContentLoaded", () => {
        RobylonChatbot.create({
          api_key: "YOUR_API_KEY", // Replace with your actual API key
          user_id: "optional-user-id", // Optional: remove if not needed
          user_profile: {
            name: "Optional User Name", // Optional: remove if not needed
            email: "[email protected]", // Optional: remove if not needed
          },
        });
      });
    </script>
  </body>
</html>

Option 3: User Context - Initialize After User Data

This approach loads the chatbot after user data is available. Great for websites where you want to personalize the chat experience.

What to copy:

1️⃣ Add this to your HTML <head> section:

<script
  src="https://cdn.robylon.ai/whatsapp-sdk/latest/robylon-chatbot.js"
  defer
></script>

2️⃣ Add this script at the end of your HTML <body> section:

<script>
  // Wait for page to be ready
  document.addEventListener("DOMContentLoaded", () => {
    // Get your user data (replace this with your own method)
    getUserData().then((user) => {
      // Initialize chatbot with user info
      RobylonChatbot.create({
        api_key: "YOUR_API_KEY", // Replace with your actual API key
        user_id: user.id,
        user_profile: {
          name: user.name,
          email: user.email,
        },
      });
    });
  });

  // Example function to get user data - replace with your own
  function getUserData() {
    // This is just a placeholder - replace with your actual code
    return Promise.resolve({
      id: "user123",
      name: "Jane Smith",
      email: "[email protected]",
    });
  }
</script>

Complete example:

<!DOCTYPE html>
<html>
  <head>
    <title>My Website</title>
    <!-- COPY FROM HERE -->
    <script
      src="https://cdn.robylon.ai/whatsapp-sdk/latest/robylon-chatbot.js"
      defer
    ></script>
    <!-- COPY UNTIL HERE -->
  </head>
  <body>
    <h1>Your Website Content</h1>
    <!-- Your website content here -->

    <!-- COPY FROM HERE -->
    <script>
      // Wait for page to be ready
      document.addEventListener("DOMContentLoaded", () => {
        // Get your user data (replace this with your own method)
        getUserData().then((user) => {
          // Initialize chatbot with user info
          RobylonChatbot.create({
            api_key: "YOUR_API_KEY", // Replace with your actual API key
            user_id: user.id,
            user_profile: {
              name: user.name,
              email: user.email,
            },
          });
        });
      });

      // Example function to get user data - replace with your own
      function getUserData() {
        // This is just a placeholder - replace with your actual code
        return Promise.resolve({
          id: "user123",
          name: "Jane Smith",
          email: "[email protected]",
        });
      }
    </script>
    <!-- COPY UNTIL HERE -->
  </body>
</html>

Plain JS & No-Code: Event Handling

You can handle chatbot events in plain JavaScript using the onEvent callback:

What to copy:

const chatbot = RobylonChatbot.create({
  api_key: "YOUR_API_KEY", // Replace with your actual API key
  onEvent: function (event) {
    switch (event.type) {
      case "CHATBOT_LOADED":
        console.log("Chatbot loaded");
        break;
      case "CHATBOT_OPENED":
        console.log("Chatbot opened");
        break;
      case "CHATBOT_CLOSED":
        console.log("Chatbot closed");
        break;
      // See the Supported Events section for all available events
    }
  },
});

// The chatbot instance provides methods to control the chatbot
// chatbot.show();    // Show the chatbot
// chatbot.hide();    // Hide the chatbot
// chatbot.toggle();  // Toggle visibility
// chatbot.destroy(); // Remove the chatbot from the page

> **Note:** The plain JavaScript SDK provides direct instance methods for external control. The React SDK provides similar functionality through refs (see [React External Triggers](#react-external-triggers) section above).

Configuration Options

The SDK supports the following configuration options for both React and plain JavaScript implementations. Note: The React SDK also supports external triggers via refs for programmatic control of the chatbot iframe.

| Option | Type | Description | Required/Optional | | ------------- | -------- | ------------------------------------------------- | ----------------- | | api_key | string | Your Robylon API key | Required | | user_id | string | User identifier for conversation tracking | Optional | | user_token | string | Authentication token | Optional | | user_profile | object | Additional user information | Optional | | onEvent | function | Event handler for chatbot interactions | Optional | | position | string | Position of the chatbot button ("Left"/"Right") | Optional | | sideSpacing | number | Distance from the side of the screen (in px) | Optional | | bottomSpacing | number | Distance from the bottom of the screen (in px) | Optional | | show_launcher | boolean | Show the floating launcher button (default: true) | Optional | | launcher_size | number | Override button size in pixels (default: 48px) | Optional | | overrides | object | Customize chatbot header appearance | Optional |

Position and Spacing Configuration

You can control the position and spacing of the chatbot button either through the API configuration or directly in the SDK. If both are provided, the SDK configuration takes precedence.

React Example:

<Chatbot
  api_key="YOUR_API_KEY"
  position="Left"
  sideSpacing={30}
  bottomSpacing={25}
  launcher_size={64}
/>

React: Hide Floating Launcher Button

To hide the floating launcher and manage visibility via external triggers or custom UI, set show_launcher to false (defaults to true):

<Chatbot api_key="YOUR_API_KEY" show_launcher={false} />

Plain JavaScript Example:

RobylonChatbot.create({
  api_key: "YOUR_API_KEY",
  position: "Left",
  sideSpacing: 30,
  bottomSpacing: 25,
  launcher_size: 64,
});

Launcher Size Configuration

The launcher_size prop allows you to customize the size of the floating button. This is useful for matching your design requirements or creating more prominent call-to-action buttons.

React Example:

<Chatbot api_key="YOUR_API_KEY" launcher_size={64} />

Plain JavaScript Example:

RobylonChatbot.create({
  api_key: "YOUR_API_KEY",
  launcher_size: 64, // Override default 48 button size
});

Notes:

Default size is 48 if not specified
Only applies to IMAGE launcher type (TEXT and TEXTUAL_IMAGE launchers have fixed heights)
Size is specified in pixels
Affects both button width and height (creates square button)

Overrides Configuration

The overrides prop allows you to customize the chatbot header appearance, including avatars, titles, and styling. This is useful for branding or personalizing the chatbot interface.

Overrides Options

| Option | Type | Description | | ---------------------------- | ------ | ------------------------------------------ | | header_avatar | string | URL for the header avatar image | | agent_avatar | string | URL for the agent avatar image | | header_title | string | Custom header title text | | header_subtitle | string | Custom header subtitle text | | header_title_text_color | string | CSS color value for the title text | | header_subtitle_text_color | string | CSS color value for the subtitle text | | header_bg | string | CSS color or URL for the header background |

React Example:

<Chatbot
  api_key="YOUR_API_KEY"
  overrides={{
    header_avatar: "https://example.com/header-avatar.png",
    agent_avatar: "https://example.com/agent-avatar.png",
    header_title: "Support Team",
    header_subtitle: "We're here to help",
    header_title_text_color: "#1a1a1a",
    header_subtitle_text_color: "#666666",
    header_bg: "#ffffff",
  }}
/>

React: Partial Overrides

You can provide only the overrides you want to customize. Omitted properties will use their default values:

<Chatbot
  api_key="YOUR_API_KEY"
  overrides={{
    header_title: "Custom Title",
    header_title_text_color: "#007bff",
  }}
/>

Plain JavaScript Example:

RobylonChatbot.create({
  api_key: "YOUR_API_KEY",
  overrides: {
    header_avatar: "https://example.com/header-avatar.png",
    agent_avatar: "https://example.com/agent-avatar.png",
    header_title: "Support Team",
    header_subtitle: "We're here to help",
    header_title_text_color: "#1a1a1a",
    header_subtitle_text_color: "#666666",
    header_bg: "#ffffff",
  },
});

Plain JavaScript: Updating Overrides

To update overrides after initialization, you'll need to recreate the chatbot instance with new overrides:

let chatbot = RobylonChatbot.create({
  api_key: "YOUR_API_KEY",
  overrides: {
    header_title: "Initial Title",
  },
});

// Later, destroy and recreate with new overrides
chatbot.destroy();
chatbot = RobylonChatbot.create({
  api_key: "YOUR_API_KEY",
  overrides: {
    header_title: "Updated Title",
    header_title_text_color: "#ff0000",
  },
});

Color Format Examples

Colors can be specified in any valid CSS color format:

<Chatbot
  api_key="YOUR_API_KEY"
  overrides={{
    // Hex color
    header_title_text_color: "#1a1a1a",
    // RGB
    header_subtitle_text_color: "rgb(102, 102, 102)",
    // RGBA
    header_bg: "rgba(255, 255, 255, 0.95)",
    // Named color
    header_title_text_color: "navy",
  }}
/>

Event Handling

Supported Events

The SDK emits the following events that you can listen for in both React and plain JavaScript implementations:

| Event Type | ---------------------------- | CHATBOT_BUTTON_LOADED | CHATBOT_LOADED | CHATBOT_OPENED | CHATBOT_CLOSED | CHATBOT_READY | CHAT_INITIALIZED | CHAT_INITIALIZATION_FAILED | SESSION_REFRESHED | MESSAGE_SENT | MESSAGE_RECEIVED | CONVERSATION_STARTED | CONVERSATION_ENDED | USER_AUTHENTICATED | USER_PROFILE_UPDATED | USER_FEEDBACK_SUBMITTED | FILE_UPLOAD_STARTED | FILE_UPLOAD_COMPLETED | FILE_UPLOAD_FAILED | Description | Data | | ----------------------------------------------- | ---------------------------------------- | | The chatbot button has been loaded and rendered | - | | The chatbot iframe has been loaded | - | | The chatbot has been opened | - | | The chatbot has been closed | - | | The chatbot is ready for external control | - | | The chat session has been initialized | - | | The chat session failed to initialize | { error: string } | | The chat session has been refreshed | - | | User has sent a message | { message: string } | | A message was received from the chatbot | { message: string } | | A new conversation has started | { conversationId: string } | | The current conversation has ended | { conversationId: string } | | The user has been authenticated | { userId: string } | | The user profile has been updated | { profile: object } | | The user has submitted feedback | { rating: number, comment: string } | | A file upload has started | { fileName: string, fileSize: number } | | A file upload has completed | { fileName: string, fileUrl: string } | | A file upload has failed | { fileName: string, error: string } |

| CHATBOT_ERROR

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Robylon SDK

Table of Contents

Installation

For React applications:

For plain JavaScript and no-code websites:

Where to place the script:

React SDK Usage

React: Basic Implementation

React: Event Handling

React: External Triggers

Available External Methods & Properties

Event Handling with External Triggers

Readiness Handling

Plain JavaScript & No-Code Integration

Quick Embed (Easiest Method)

ES5/Google Tag Manager

ES5 Compatible Version

Quick Embed with Custom Position and Spacing

ES5 Compatible Version with Custom Position and Spacing

Where to place the script:

Option 1: Quick Setup - Load with Page

What to copy:

Complete example:

Option 2: Reliable Loading - After DOM is Ready

What to copy:

Complete example:

Option 3: User Context - Initialize After User Data

What to copy:

Complete example:

Plain JS & No-Code: Event Handling

What to copy:

Configuration Options

Position and Spacing Configuration

React Example:

React: Hide Floating Launcher Button

Plain JavaScript Example:

Launcher Size Configuration

React Example:

Plain JavaScript Example:

Overrides Configuration

Overrides Options

React Example:

React: Partial Overrides

Plain JavaScript Example:

Plain JavaScript: Updating Overrides

Color Format Examples

Event Handling

Supported Events