Instant Answers Widget

Maven offers an instant answers widgets that allow you to embed a Maven experience directly into your website.

To add the instant answers widget to your website, you need to add a small piece of javascript to your page. This javascript code will initialize the widget and connect it to your Maven instance.

Your personalized code snippet can be found on either the chat settings page or instant answers settings page within the Dashboard. You’ll need to copy and paste the code snippet into your website’s HTML to get started. More specific instructions for common sites are provided below.

Instant Answers Widget

The instant answers code snippet requires a slightly deeper integration. It needs to know which piece of the page to attach the widget to and also needs to know when the user question has been submitted and what the question was. This requires a bit more HTML knowledge.

Configuration Options

The Instant Answers widget supports several configuration options that can be customized:

Basic Configuration Example

1
Maven.InstantAnswersWidget.init({
2
  agentId: "your-agent-id",
3
  organizationId: "your-organization-id",
4
  locale: "en",
5
  signedUserData: "your-signed-jwt-token", // Optional user authentication
6
  unsignedUserData: {
7
    sessionId: "user-session-123",
8
    department: "support"
9
  },
10
  tags: ["help-center", "self-service"]
11
});

Authentication

Signed User Authentication

Maven Instant Answers supports signed and encrypted user authentication, allowing you to securely authenticate users and pass additional context data (such as session IDs) that can be used by Maven Apps to make API calls on behalf of the user.

Requirements

• A server-generated, signed and encrypted JWT containing user data
• A shared symmetrical encryption key, provided in the Instant Answers app settings under Security (Encryption secret)
• A shared public key for verifying signing, provided in the Instant Answers app settings under Security (JWT public key)

User Data Requirements

The user data object must include:

• firstName - User’s first name
• lastName - User’s last name
• id - User’s unique identifier (UUID)
• At least one of:
  • phoneNumber - User’s phone number
  • email - User’s email address
• Additional fields (like sessionId) will be included and can be used by Maven Apps

Generating User Authentication Token

To protect the user data in transit, generate a signed JWT token containing user data and encrypt the token with ES256 and a 32-bit secret key. This token must be generated on the backend and passed into the instant answers widget via the signedUserData property.

Example Implementation (TypeScript)

1
import { SignJWT, EncryptJWT } from 'jose';
2
3
async function secureUserData(userData: Record<string, string> & {
4
 id: string
5
 firstName: string
6
 lastName: string
7
 sessionId?: string  // Additional context data
8
} & (
9
 { email: string, phoneNumber?: string } |
10
 { email?: string, phoneNumber: string }
11
)) {
12
 // 1. Sign the user data with your private key (ES256 algorithm)
13
 const signedJWT = await new SignJWT(userData)
14
   .setProtectedHeader({ alg: 'ES256' })
15
   .setIssuedAt()
16
   .setExpirationTime('1d')
17
   .sign(yourPrivateKey);
18
19
 // 2. Encrypt the signed JWT using your encryption secret
20
 const encryptedJWT = await new EncryptJWT({ jwt: signedJWT })
21
   .setProtectedHeader({ alg: 'dir', enc: 'A128CBC-HS256' })
22
   .encrypt(base64url.decode(encryptionSecret));
23
24
 return encryptedJWT;
25
}

Using Signed User Data

Once you have generated the signed user data token, pass it to the widget during initialization:

1
Maven.InstantAnswersWidget.init({
2
  agentId: "your-agent-id",
3
  organizationId: "your-organization-id",
4
  signedUserData: await secureUserData({
5
    id: "user-123",
6
    firstName: "John",
7
    lastName: "Doe", 
8
    email: "[email protected]",
9
    sessionId: "session-abc-123" // Custom data for your app
10
  })
11
});

Setting up Zendesk help center

Zendesk provides instructions for customizing your help center theme. Follow those instructions to edit your theme.

For the chat widget you want to add your code snippet to script.js.

For the instant answers widget:

1. Goto “search_results.hbs”
2. Find

         {{#if results}}
           <ul class="search-results-list">

   And replace with:

         <div id="maven-instant-answers-container" style="margin-bottom: 5px"></div>
         {{#if results}}
           <ul class="search-results-list">

3. Add the following to the end of the file and remember to replace the API KEY with your Maven API key found within the code snippet on the Instant Answers Settings page.

   <script src="https://instant-answers.onmaven.app/js/widget.js" async></script>
   <script>
   // This code loads the Maven widget when the page is first opened
   addEventListener("load", function () {
     Maven.InstantAnswersWidget.init({
       agentId: "REPLACE THIS WITH YOUR AGENT", // defaults to support
       organizationId: "REPLACE THIS WITH YOUR ORG",
       locale: "en",
       signedUserData: "your-signed-jwt-token", // Optional: for authenticated users
       unsignedUserData: {
         page: "zendesk-help-center",
         source: "search"
       }
     });
     // If there is an HTML element on the page with the ID 'query'
     if (document.getElementById('query') !== null) {
       // Get the user question from the value of that element
       var text = document.getElementById('query').value;
       if (text) {
         console.log("Loading Maven with the question: " + text);
         Maven.InstantAnswersWidget.search({
           query: document.getElementById('query').value,
           selector: '#maven-instant-answers-container'
         });
       } else {
         console.log("No query found. Not loading Maven.");
       }
     } else {
       console.log("No HTML element found with the ID query. Not loading Maven.");
     }
   }); 
   </script>

If Maven does not render after adding this snippet, check the browser logs to see if either the query HTML element is missing or doesn’t have a value.

If you see those type of logs:

• Your Zendesk instance may be putting the user question in another HTML element - if so change query in the above snippet to the ID of the HTML element that the user question does appear in
• Or the question may only be in the page url, and not in the HTML at all. In this case, try replacing the above var text line with var text = new URLSearchParams(window.location.search).get("query");. (Note: you may also need to comment out the if statement that checks for the presence of the query element: document.getElementById('query') !== null)

Setting up Salesforce Digital Experience

The Maven Instant Answers widget can be added to a help center built on the Salesforce Content Management System (CMS). To allow a page hosted in the CMS to access Maven AGI, you will likely need to confirm or change a few security settings.

Trusted URLs for data access

First you must ensure that Salesforce can load data from Maven AGI. In the Salesforce setup navigation, search for “Trusted URLs”. In the Trusted URLs page, add entries for https://instant-answers.onmaven.app.

Trusted Scripts

Next the CMS must be allowed to load scripts from Maven AGI. In Experience Builder for your site, open the settings and navigate to Security & Privacy. Change “Content Security Policy (CSP)” to Relaxed, then add https://instant-answers.onmaven.app to the “Trusted Sites for Scripts” list.

Add the Maven Script

In Settings for your site in Experience Builder, navigate to “Advanced” and press the “Edit Head Markup” button. In the editor, add the following snippet

1
<script src="https://instant-answers.onmaven.app/js/widget.js" async></script>
2
<script>
3
    // This code loads the Maven widget when the page is first opened
4
    addEventListener("load", function () {
5
      Maven.InstantAnswersWidget.init({
6
        agentId: "REPLACE THIS WITH YOUR AGENT", // defaults to support
7
        organizationId: "REPLACE THIS WITH YOUR ORG",
8
        locale: "en",
9
        signedUserData: "your-signed-jwt-token", // Optional: for authenticated users
10
        unsignedUserData: {
11
          page: "salesforce-help-center",
12
          source: "search"
13
        }
14
      });
15
    }
16
</script>

Add the results container

In experience builder, add a “HTML Editor” component on the page where you would like the search results. Add the following markup:

1
<div id="maven-instant-answers-container"></div>

Add a search button, or hook the search button

To invoke search and start returning results from Maven, make the following Javascript call in a new button or when an existing search button is pressed

1
Maven.InstantAnswersWidget.search({
2
    query: text,
3
    selector: '#maven-instant-answers-container'
4
});

Still not working?

In general, if the instant answers widget renders but seems to load forever, this most likely means that Maven is being sent an empty question. Generally this means the user question needs to be pulled from a different HTML element on the page, or, it might be only in the page url. Reach out and we can help you fix this!

Contact us on Discord for technical support.