Adding a Live Chat Widget to Your Website

This helpful guide will walk you through the process of embedding the Orlo Live Chat widget onto your website, allowing you to connect with your visitors in real-time.

How it Works 

To ensure the user data you send is secure and hasn't been tampered with, we use a process called data signing. You'll generate a unique digital "signature" using a special key before sending the data to our widget. We then verify this signature using another key to confirm the data's authenticity.

Here's a visual overview of the process:

 

 

Generate Your Secure Keys (RSA Key Pair)

Think of this as creating a unique lock and key for your data. We recommend generating a new pair of keys for each Live Chat widget for enhanced security, but you can use the same pair if you prefer.

Follow these steps on your server (not directly in your website or app code):

1. Generate a Private Key: This is your secret key and should never be shared.

   openssl genrsa -out private.pem 2048
   

2. Extract the Public Key: This is the key you'll share with Orlo so we can verify the signature created with your private key.

   openssl rsa -in private.pem -outform PEM -pubout -out public.pem
   

   These commands will create two files: private.pem (your private key) and public.pem (your public key).

 Add Your Public Key to Orlo

You need to tell Orlo your public key so it can verify the data you send.

1. Go to Settings in your Orlo account.
   
   
2. Click on Manage your Live Chat Widgets.
   
   

1. Carefully copy and paste the entire contents of your public.pem file into this field.
2. Click Save Changes.

 Prepare the User Data (JSON Object)

On your server (where your website or app's backend code runs), you need to create a piece of data in a specific format called JSON. This data will contain information about the logged-in user.

Minimum Required Data:

At a minimum, your JSON object must include the following:

{
  "name": "customer name",
  "isLoggedIn": true
}

• name: The full name of the customer.
• isLoggedIn: A value of true if the user is currently logged in to your website or app.

Optional Data (Pre-fill Email):

You can also include the user's email address to automatically fill this field in the chat widget (if you've enabled it as a required field in your widget settings):

{
  "name": "customer name",
  "isLoggedIn": true,
  "email": "example@example.com"
}

If you don't provide the email here but have it set as a required field in your widget settings, the user will still be asked for it before they can chat.

Custom Data (Agent Information Sidebar):

You can include any extra information you think would be helpful for your customer service agent. The "key" you use in the JSON will be the label the agent sees in their chat sidebar. Use clear, readable labels (avoiding programming terms like camelCase or underscores).

{
  "name": "customer name",
  "isLoggedIn": true,
  "User ID": 124,
  "Telephone": "01234567890",
  "Account Type": "Premium"
}

Securely Sign the Data (JWT Token)

Now you need to create a secure "signature" for this JSON data using your private key. We use a standard method called JWT (JSON Web Tokens) for this. There are many libraries available in various programming languages that make this process easy.

• Learn more about JWT: https://jwt.io/introduction/
• JWT Specification: https://tools.ietf.org/html/rfc7519

The output of this signing process will be a single, long string (the JWT token). This token contains your user data along with the secure signature.

Send the JWT Token to the Live Chat Widget

Once you have generated the JWT token, you need to pass it to the Orlo Live Chat widget on your website or app.

For Websites (JavaScript):

You'll need to add some JavaScript code to your website. You can find a code snippet under the Customer data section in the second box when you go to Settings > Manage your Live Chat Widgets > click Embed.

Place this code anywhere on your webpage or run it after you've retrieved the JWT_TOKEN (for example, after an AJAX call to your server).

Important: Replace JWT_TOKEN in the code snippet with the actual JWT token you generated on your server.

For Mobile Applications:

1. Navigate to Settings > Manage your Live Chat Widgets > click Embed.

2. At the bottom, you'll find your Mobile URL Information. Choose the URL that includes jwt.

3. When you embed the live chat view in your mobile app, you will need to append parameters to this URL:

   • jwt: Replace this with the JWT token you generated.
   • widgetId: Replace this with the actual ID of your Live Chat widget (found in the settings).

   Your final URL in your mobile app might look something like this:

   YOUR_MOBILE_URL_WITH_JWT?jwt=YOUR_GENERATED_JWT_TOKEN&widgetId=YOUR_WIDGET_ID

By following these steps, you can seamlessly pre-fill user details and provide valuable context to your agents, creating a smoother and more efficient live chat experience for your customers.