# 5 Minute Quick Start Integrating Rep.ai is a breeze. 1\. Visit to grab your API key. If you haven't yet created an account, you'll need to do that first. After you sign-up, you'll see your API key first in the onboarding, and then in [your widget settings at the bottom](https://app.rep.ai/settings/widget?expand=install). 2\. Integrate Rep.ai into your web app with NPM/Yarn or a script tag. Rep.ai runs entirely in the browser. {% tabs %} {% tab title="Script Tag" %} Paste the following script **at the very top** of of the `` of your site. ```markup ``` {% endtab %} {% tab title="NPM/Yarn" %} Install the package via NPM: ```bash # NPM npm install --save @repai/widget # Yarn yarn add @repai/widget ``` Import `RepAI` and call `RepAI.init()` with your configuration options ```typescript import RepAI from "@repai/widget"; RepAI("init", "YOUR_CLIENT_KEY_HERE"); ``` {% endtab %} {% endtabs %} # Controlling the Widget Use the Javascript API to control widget behaviors The `RepAI` API exposes a few methods that allow you to control the widget without user interaction. This can be useful for controlling the user experience around users requesting calls, or hooking up the widget to custom UI elements. ### `RepAI("init", api_key, options?)` You can add options to the `init` call to specify how the widget should render initially. ```javascript RepAI("init", "", { /** * Whether or not to hide the widget initially. * * Defaults to false. */ hidden: false, /** * Which side to render the widget on, 'left' or 'right'. * * Defaults to 'right'. */ position: "right", /** * Whether or not to connect the widget on init, or manually later. * If the client has recently connected, they will connect anyway * despite this setting to allow for navigation and refreshes. * * Defaults to true. */ connect: true, /** * Which design to use for the launcher, 'pill' or 'video'. Pill * is the small circle design that is used on smaller devices. * Video is the larger widget. Even if 'video' is specified, * 'pill' will be used on smaller devices. * * Defaults to 'video'. */ launcher: 'pill', /** * Class name to use as selector for sensitive elements, causes * them not to be sent when viewing a visitor's screen. Should not * include selector characters like . or #, cannot be an arbitrarily * complex selector. * * Defaults to 'sb-block'. */ blockClass: "sb-block", /** * How the widget initializes itself. It has three possible values. * * "retrigger" The widget will re-establish its session on each page load. * This is the default mode. * * "iframe-jit" The widget loads the page into an iframe * when an agent connects. After that the widget will be continuously * connected as they navigate the site. * * Defaults to 'retrigger' */ mode: "retrigger" }) ``` Note that some of these options overlap with the configurations set via your organization's widget appearance settings page. If any of these arguments are provided programmatically, the JS options will take precedence over the appearance settings. ### `RepAI("show")` ```javascript RepAI("show"); ``` Shows the widget if it's hidden. If you want to start the widget hidden and programmatically show later, initialize with `hidden: false`. ### `RepAI("hide")` ```javascript RepAI("hide"); ``` Hides the widget if it's visible. ### `RepAI("expand")` ```javascript RepAI("expand"); ``` Expands the widget if it's visible. ### `RepAI("alert", options?)` ```javascript RepAI("alert", { // Title text to display in the push notification title: "My important page", // Body message to display in the push notification body: "Some helper text", }) ``` Puts the visitor into an alert state, which displays them prominently on the dashboard, and sends all available admins a push notification. You can configure the notification with the optional options object argument. Alerting will cause no visual change for the visitor, it's only for dashboard alerting purposes. ### `RepAI("dial")` ```javascript RepAI("dial"); ``` Puts the visitor into the dialing state, which displays them prominently on the dashboard, sends all available admins a push notification, and displays to the user the dialing state. This is equivalent to the user clicking on the widget to dial. The widget will always be visible when dialing, even if it was hidden. ### `RepAI("bookMeeting")` ```typescript RepAI("bookMeeting"); ``` Immediately opens the widget to the book meeting view that they normally see if the dial timer times out, or if no admins are available. Either shows them an email submission form, or the Calendly widget if [Calendly is configured](/integrations/calendly). ### `RepAI("connect")` ```typescript RepAI("connect"); ``` Triggers the widget to connect to the Rep.ai server if it wasn't already connected. This is only used in conjunction with `{ connect: false }` or `RepAI("disconnect")` as the widget will normally connect by default after calling `RepAI.init()` ### `RepAI("disconnect")` ```typescript RepAI("disconnect"); ``` Triggers the widget to disconnect from the Rep.ai server if it wasn't already disconnected. This should typically be used in conjunction with `RepAI.connect()`. Note that if your Rep.ai installation initializes with `{ connect: true }` or doesn't specify a connect parameter, the widget will immediately connect on the next page load or refresh unless `RepAI("disconnect")` is called again. ### `RepAI("showPopup", options?)` ```typescript RepAI("showPopup", { /** * Whether to display a 'small' popup or a 'large' full screem modal * * Defaults to 'small' */ size: "small" }); ``` Triggers a small popup to appear above the widget, or a larger modal to take over the screen, to invite visitors to use the Rep.ai widget to start a call. Either of them will only show up if the widget is currently collapsed, and agents are available to take calls. Otherwise there will be no effect. ### `RepAI("startJourney", options)` ```typescript RepAI("startJourney", { /** * Journey ID to start the visitor on. * * The journey must be enabled. */ journeyId: 123 }); ``` This asynchronous call will attempt to start the visitor on the journey for the provided ID. If the journey is not found or not active, the api call will not succeed. If the visitor is currently on a different journey, it will be cancelled in favor of the one specified in the `journeyId` option parameter. If the visitor is already on the specified journey, the call will return `true` without restarting the journey.\ \ This function returns a `Promise` representing whether the visitor has been (or already is) started on the journey. It will log failures to the browser console. # Custom Visitor Identities You can provide custom visitor identity information to the Rep.ai dashboard, which will allow you to deduplicate visitors and give customer support agents information about who they're helping. ### Code Sample ```javascript RepAI("identify", YOUR_UNIQUE_CUSTOM_ID, // String or integer, replace with your own custom unique value { email: "daniel@rep.ai", // REQUIRED: Required to create or associate a contact with the visitor. displayName: "Jessie", // Changes the name of the visitor in the dashboard avatar: "https://example.com/avatar.png", // Changes the avatar of the visitor in the dashboard tag: "PAID_PLAN", // or "NEW_PLAN" or "TRIAL_PLAN": Adds an icon next to the visitor name in the dashboard anyDataYouWant: "hotdogs", // Any other custom data can be added as well }, ); ``` {% hint style="danger" %} #### Providing a Unique Custom ID In order to fully use the `identify` api, you must have a unique custom identifier available in Javascript to attach to the visitor, and use that to replace `YOUR_UNIQUE_CUSTOM_ID` above. This value is typically a user ID or an email address. Using a static value or a value that can collide with multiple visitors (such as an IP address or a name) can cause loss of data and disconnected sessions. If you do not have a custom identifier but would still like to set custom properties to view in the dashboard, you can pass `undefined` as the unique identifier. Subsequent visits from this visitor may not have the associated metadata, and their session history will be incomplete. {% endhint %} ### Custom Metadata The custom data object can provide customer service agents any other details that may be important to the session. The object has a few implementation notes and limits: * The `email` key is required. Email addresses are used to create or associate a contact with the visitor. If the `email` key is not present the metadata will be ignored. * Keys must be JSON-serializable values. * Repeated calls to identify will overwrite previous data, and should be called on every session. * New keys passed into the custom data object will be added on to previous custom data, so you don't have to pass the whole object every time, and can pass keys that you may not have until later into the visitor's session. * If you want to remove a key, you must pass `null` for its value. Simply omitting it will keep the previous value. {% hint style="warning" %} **Custom Metadata Length Restriction** Custom Metadata is limited on a per-visitor basis. Each visitor is limited to 1024 bytes for metadata storage. When adding custom metadata, if the change would cause the stored custom metadata to exceed this limit, the change will not persist and the custom metadata will be left in the state prior to the update being attempted. {% endhint %} ### Secure Identities For security-conscious customers, we recommend validating user identities on your server before identifying them to Rep.ai. This is done by generating a unique hash of the visitor's identity before sending it to Rep.ai, using a secret key on your server. You only need to hash the custom user ID, and optionally the email if you're providing one in the custom metadata. Below are examples of how to generate this hash on your server. {% tabs %} {% tab title="Python (3+)" %} ```python import hmac import hashlib import json def generate_repai_identity_hash(user_id: str, email: str) -> str: data = {"id": user_id} if email: data["email"] = email return hmac.new( bytes( os.environ.get("REPAI_IDENTITY_SECRET_KEY"), encoding="utf-8", ), bytes( json.dumps(data, separators=(",", ":")), encoding="utf-8", ), digestmod=hashlib.sha256, ).hexdigest() ``` {% endtab %} {% tab title="Node.js" %} ```javascript import crypto from 'crypto'; function generateRepAIIdentityHash(id, email) { const data = { id: id }; if (email) { data.email = email; } return crypto .createHmac('sha256', process.env.REPAI_IDENTITY_SECRET_KEY) .update(JSON.stringify(data)) .digest('hex'); } ``` {% endtab %} {% endtabs %} {% hint style="info" %} If you don't see your server's language listed above, you can use any technique to generate an equivalent HMAC SHA256 hash of the data in JSON string form. For example, an ID of "123" and an email of "" would be a hash of: `{"id":"123","email":"email@example.com"}` Make sure the JSON string is in the correct order (id first, email second) and that it has no unnecessary whitespace. Any difference in the JSON string will result in mismatching hashes. {% endhint %} You'll take the hash generated from your server and add it as the third argument to the `RepAI("identify")` call, like so. ```javascript // This assumes you have an API endpoint at /api/repai-identity-hash // that returns the hash as text, and assumes that you have some kind of // user object in Javascript that has an id and email. Your implementation may // look different. fetch("/api/repai-identity-hash").then(async res => { const authHash = await res.text(); RepAI("identify", user.id, { email: user.email }, authHash, ); }); ``` You can retrieve your secure identity secret key from the [Security Settings page](https://app.rep.ai/settings/security) on the Rep.ai dashboard. Once you've implemented everything above, you can toggle on requiring secure identities. This will cause any identity sent without a valid hash to be rejected. # Listening to Events Integrate your application with the Rep.ai widget by listening for and reacting to events The Rep.ai widget triggers events on the global `window` object in JavaScript that can be listened for and reacted to. Some of these events will get triggered by calls to the Rep.ai JavaScript API, but they can also be triggered by visitor interaction with the widget, or by admins interacting with visitors via the Rep.ai dashboard. ## Conversion Event Tracking Example A popular use case for the Events API is conversion tracking. the `sb:callstart` event will be fired whenever a call is accepted by a visitor, and you can listen for these events like so: ```javascript window.addEventListener("sb:callstart", () => { gtag('event', 'callstart', { 'event_category': 'chat', 'event_label': 'sb:callstart', }); }); ``` Refer to GA4 documentation to [set up events](https://developers.google.com/analytics/devguides/collection/gtagjs/events), [set up event parameters](https://developers.google.com/analytics/devguides/collection/ga4/event-parameters?client_type=gtag), and [mark events as conversions](https://support.google.com/analytics/answer/13128484?sjid=9040534538290068234-NC). ### Events

Event name	Description
Event name	Description
`sb:initialized`	Emits when the widget is fully initialized and ready to be interacted with.
`sb:error`	Emits if a critical error is encountered during widget initialization. The error is included in `event.detail`.
`sb:expand`	Emits on the widget going into its expanded state, either by the visitor clicking on the widget or by calling `RepAI.expand()`.
`sb:collapse`	Emits on the widget going into its collapsed state, either by the visitor clicking on the widget or by calling `RepAI.collapse()`.
`sb:callaccept`	Emits on the visitor accepting a call that was initiated either proactively or reactively.
`sb:callreject`	Emits on the visitor rejecting a call that was initiated either proactively or reactively.
`sb:dialstart`	Emits on the widget requesting assistance, either by the visitor clicking on the dial button or by calling `RepAI.dial()`
`sb:dialcancel`	Emits on the dial canceling, either by the visitor clicking "Cancel" or the "X" button on the top right of the widget while dialing.
`sb:dialmiss`	Emits on the widget going into the dial missed state after a period of time elapses after dialing but nobody answered the request for help.
`sb:callstart`	Emits on an admin starting a call with a visitor. This will emit before the visitor explicitly presses "accept" on the call.
`sb:callend`	Emits on a call ending, either by the visitor ending it, the admin ending it, or from a network connectivity issue.
`sb:availabilitychange`	Emits on org availability changes. Includes an object with current org states: `{ detail: { isAvailable: boolean; isBusy: boolean; isWorkingHours: boolean; } }`
`sb:agentsavailabilitychange`	Emits on agents' availability changes. Includes a full list of agents with current availabilities. `{ "agents": [ { "avatar": null, "available": true, "onCall": true, "title": "Support", "id": 1, "name": "Steven" }, { "avatar": null, "available": false, "onCall": true, "title": "Support", "id": 2, "name": "Joe" } ] }`

# Examples of Custom Behavior Trigger Rep.ai from buttons ## Custom dial trigger Rep.ai can be invoked by most HTML elements by adding an `onclick` attribute. ```markup ``` Or you can listen for the `click` event in JavaScript. ```javascript var button = document.getElementById('my-button'); button.addEventListener("click", function() { RepAI("dial"); }); ``` ## Require permission before initializing You can take the `RepAI("init")` snippet and call it at any point, including after the user has agreed to a permission (e.g. by clicking "accept" in a modal or banner.) However, **you still must keep the long part of the snippet that looks like `!function...` first**, in order to load the `RepAI` API. Here's an example using a jQuery dialog, but it would work with any JavaScript framework. ```markup

Would you like to opt-in to receiving calls from our team during your session?

``` ## Handling missed calls If you want to trigger custom behavior after a visitor tries dialing but nobody answers their request, you can listen to the `sb:dialmiss` event. Here's an example that directs the visitor to the contact page if they're missed: ```javascript window.addEventListener("sb:dialmiss", function() { window.location.href = "/contact-us"; }); ``` ## Show expanded widget, hide on collapse If you want to keep the widget hidden most of the time, but expand it to let the user decide if they want to call or book a meeting (depending on availability) without immediately dialing, you can do that with a combination of `RepAI` methods and events. ```javascript // Show & expand the widget. RepAI("show"); RepAI("expand"); // If the visitor closes it after expanding, hide it completely. window.addEventListener("sb:collapse", () => { RepAI("hide"); }); ``` ## Listen for initialization or error If Rep.ai is initialized and triggered as a core part of your user flow, you may want to handle the UX of a user encountering an error with widget initialization. ```javascript // On clicking a button, initialize the widget and dial. const button = document.getElementById("call-button"); button.addEventListener("click", () => { button.disabled = true; RepAI("init", "CLIENT_KEY_HERE"); RepAI("dial"); // Widget initialized correctly. window.addEventListener("sb:initialized", () => { button.disabled = false; }); // Widget encountered a critical error. window.addEventListener("sb:error", (ev) => { button.disabled = false; alert("Failed to start a call! Please contact support."); console.log("What happened?!", ev.detail); }); }); ``` # Security and Spam Prevention To avoid malicious use of your organization's Rep.ai widget, and to prevent your team from wasting time on spam callers, there are a few options that you can configure on the settings [Security page](http://app.rep.ai/settings/security). ### Domain Allow List Add a list of all the domains you plan to use the Rep.ai widget on. Any attempts to load the widget on other web pages will be blocked, and you'll never see those clients in the dashboard. Domains are subdomain specific, so connections from `app.mycompany.com` will be rejected if your allow list only contains `mycompany.com`. The allow list currently does not support wildcarding. #### Development domains While you can manually specify your development domains along side your public domains, we also include a toggle to allow connections from most common development domains without having to exhaust your available domains. These include: * All `localhost` ports * Any IP address (e.g. `http://127.0.0.1`) * Any `.local` domain # Virtual Backgrounds Rep.ai offers virtual backgrounds for Chromium-based browsers (Google Chrome, Chromium, Brave, Microsoft Edge, Opera). If you use a different browser, you can utilize virtual webcam software to get the same result. We recommend you use any of the following: | Software | Windows Support | macOS Support | Linux Support | | ------------------------------------------ | --------------- | ---------------------------- | ------------- | | [ChromaCam](https://www.chromacam.me/) | ✅ All browsers | ✅ All browsers except Safari | ❌ | | [XSplit VCam](https://www.xsplit.com/vcam) | ✅ All browsers | ✅ All browsers except Safari | ❌ | Once you start a call, click on the overflow menu below the call button and select which camera to use. This will be saved as the default for future calls. ![](/files/-MbcBjXc1MXzaWUBjxhR) If you don't see your virtual camera in the device list, confirm the app is running and restart your browser. Safari does not support virtual cameras either. # How to Identify Contacts who Click Through Emails to Your Site from Email Sequencers With the right setup, Rep.ai can identify contacts (name, company, email) who click through email campaigns. Email clickthrough identification at contact-level relies on a unique link query parameters per email recipient. Below is a set of steps to configure your Rep.ai instance to recognize individuals by their email. 1. Add this code to your site in addition to the installation code you already installed: ```javascript ``` 1. Build a reference table of email and base64-encoded query parameters attached to the clickthrough URL. This can be done in a Google Sheet, but is easiest to automate in Clay, especially if you use a sequencer that integrates with Clay. 1. The one column you *must* encode is the email as “sbec” 2. You can optionally encode firstname as “sbfn”, lastname as “sbln”, and company name as “sbcn” 3. Example query string:[https://rep.ai?sbec=ZXZhbkBzZXJ2aWNlYmVsbC5jb20=\&sbfn=RXZhbg==\&sbln=RHVubg==\&sbcn=U2VydmljZUJlbGw=](https://servicebell.com?sbec=ZXZhbkBzZXJ2aWNlYmVsbC5jb20=\&sbfn=RXZhbg==\&sbln=RHVubg==\&sbcn=U2VydmljZUJlbGw=) 4. See this sheet for reference: 2. Integrate the table from Clay or Sheets into your campaign, so that the hyperlinked text includes the encoded data. 3. Rep.ai will pick up the clickthrough and display alerts and contact information accordingly. For reference, below is the Python code to encode an email. You can build this as a column in Clay. ```python import base64 # String to encode data = "evan@rep.ai" # Encode the string to bytes encoded_bytes = base64.b64encode(data.encode('utf-8')) # Convert bytes to string encoded_string = encoded_bytes.decode('utf-8') print(encoded_string) ``` # Browser Compatibility Rep.ai uses some of the latest technology available in browsers to support 2 way video calling and the screen takeover feature. The table below outlines which of the most common browsers are supported: | Browser | Supported | | ----------------- | --------- | | Chrome | ✅ Yes | | Firefox | ✅ Yes | | Safari | ✅ Yes | | Microsoft Edge | ✅ Yes | | Internet Explorer | ❌ No | | iOS Safari | ✅ Yes | | Android Chrome | ✅ Yes | | Android Firefox | ✅ Yes | Only recent versions are considered, users on significantly older versions of their browsers may experience issues. ### Users with Incompatible Browsers Users whose browsers don't support Rep.ai will see the widget, but with a message letting them know that they'll need to update their browser to speak to an agent. # Notifications Make sure you're being alerted right when your visitors are ready to talk If you're not receiving notifications from your browser when visitors are dialing or alerting, make sure that they're enabled and your system is allowing them. ### Enabling Notifications in Rep.ai You can enable notifications from the [Notifications Settings page](https://app.rep.ai/settings/notifications) in the dashboard, by clicking "Enable Push Notifications." Your browser will ask you for permission to send you notifications. Once you allow it, you'll be sent you a confirmation notification. It should look like this: {% tabs %} {% tab title="Chromium on macOS" %} ![Chromium includes Chrome, Edge, Brave, and Opera browsers](/files/-M_7e-goHfRmCTbY90Rj) {% endtab %} {% tab title="Chromium on Windows" %} ![Chromium includes Chrome, Edge, Brave, and Opera browsers](/files/-M_7eUhG_QAh8mEke0cx) {% endtab %} {% tab title="Firefox on macOS" %} ![](/files/-M_7g5qddVecBLbHn1G1) {% endtab %} {% tab title="Firefox on Windows" %} ![](/files/-M_7gCFwSWsxFxdoYksa) {% endtab %} {% endtabs %} If you don't get a test notification after enabling them, make sure your operating system allows notifications from your browser with the steps below: ### Enabling Notifications in your Operating System If you're still not seeing notifications after enabling them, it's likely that your system is not allowing the browser to display notifications. Select your operating system below for instructions on how to enable them: {% tabs %} {% tab title="macOS" %} 1. Search for "Notifications" in spotlight, or open "Notifications" from "System Preferences" 2. Find your browser in the list of applications 3. Ensure that "Allow Notifications" is toggled on, and that the style is either "Banners" or "Alerts" ![](/files/-M_7dTTbxpAysvMR08Dd) {% endtab %} {% tab title="Windows" %} 1. Search for "Notifications" in your start menu, or go to "Settings" and open "Notifications & actions" 2. Ensure that "Get notifications from apps and other senders" is enabled 3. Scroll down to "Get notifications from these senders" and ensure your browser has their notifications enabled. 4. Click on your browser, and confirm that "Show notification banners" is enabled. 1. Firefox won't appear in this list, it does not use system-level notifications on Windows ![](/files/-M_7d7OYGrtTdLhLCvI9) ![](/files/-M_7dAizaMyimIMykcGw) {% endtab %} {% endtabs %} ### Browser Compatibility The following browsers support push notifications: | Browser | Supports Push Notifications | | ----------------- | ------------------------------------------------------------- | | Chrome | ✅ Yes | | Firefox | ✅ Yes | | Safari | ❌ No | | Microsoft Edge | ✅ Yes | | Brave | [⚠️](https://emojipedia.org/warning/) Requires configuration¹ | | Internet Explorer | ❌ No | | iOS Safari | ❌ No | | Android Chrome | ✅ Yes | | Android Firefox | ✅ Yes | 1. Go to brave://settings/privacy and enable "Use Google services for push messaging". Must restart browser for setting to take effect. # Content-Security-Policy (CSP) Content-Security-Policy (CSP) is a browser feature that limits what origins (i.e. domains) your page can interact with. When you configure a security policy on your website, the browser will reject any connections that don't fit the policy. If you're using the `