Chat Widget

Maven offers a chat widget that allows you to embed a Maven experience directly into your website.

Installation

To install the chat app on your agent:

1. Navigate to the Apps page in the Agent Designer.
2. Click on Browse & Install on the Apps Directory tile.
3. Search for “Chat” and click on the Chat app tile.
4. Click on the Install button.

Integration

To add the chat 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 the chat settings page under the “Instructions” tab. Copy and paste the following code snippet into your website’s HTML, preferably just before the closing </body> tag:

1
<script src='https://chat.onmaven.app/js/widget.js' defer></script>
2
<script async>
3
  addEventListener("load", function () {
4
    Maven.ChatWidget.load({
5
      organizationId: "YOUR_ORGANIZATION_ID",
6
      agentId: "YOUR_AGENT_ID",
7
    })
8
  });
9
</script>

Basic Settings

The chat app supports several basic configuration options that can be customized through the Dashboard:

• Logo URL - The URL of the logo to display in the chat header.
• Brand Color - The accent color used on the chat UI.
• Welcome Message - The message displayed when the chat widget is opened.
• Popular Questions - Questions shown directly under the welcome message.

Additionally, the appearance of the widget on your site can be further customized:

1
  Maven.ChatWidget.load({
2
    organizationId: "YOUR_ORGANIZATION_ID",
3
    agentId: "YOUR_AGENT_ID",
4
    bgColor: "#007AFF",
5
    buttonLabel: "Chat with us",
6
    horizontalPosition: "left",
7
    verticalPosition: "top",
8
  })

Advanced Settings

The full list of chat app settings:

The full list of widget configuration options:

Programmatic Control

You can programmatically control the widget using the following methods:

1
// Open the widget
2
window.Maven.open();
3
4
// Close the widget
5
window.Maven.close();

Live Agent Handoff

Maven Chat supports seamless handoff to live agent support through various service providers. When configured, conversations can be automatically transferred to human agents.

Currently supported providers:

• Salesforce
• Zendesk
• Front

Salesforce Configuration

Maven Chat integrates with Salesforce Live Agent to provide human support capabilities. This integration requires configuration in both Salesforce and Maven.

Requirements

• Salesforce account with Live Agent enabled
• Access to Salesforce Setup
• A configured Live Agent deployment and button

Setup Process

Follow these steps to configure Salesforce integration:

1. Configure Live Agent Deployment

   • Navigate to Salesforce Setup > Embedded Service Deployments
   • Locate or create a new deployment
   • Note the Deployment ID and ES Live Agent Dev Name

2. Configure Chat Button

   • Navigate to Setup > Chat Buttons & Invitations
   • Create or select an existing chat button
   • Note the Button ID

3. Locate Live Agent Settings

   • Find your Chat Host URL in the Salesforce Live Agent settings
   • Note your Organization ID

Configuration

Create a handoff configuration object with the following structure:

1. Create your configuration object:

1
{
2
  type: 'salesforce',
3
  orgId: 'your-org-id',
4
  chatHostUrl: 'https://d.la12s-core1.sfdc-lywfpd.salesforceliveagent.com',
5
  chatButtonId: 'your-button-id',
6
  deploymentId: 'your-deployment-id',
7
  eswLiveAgentDevName: 'your-live-agent-name',
8
  apiSecret: 'your-api-secret',
9
  allowAnonymousHandoff: false,
10
  enableAvailabilityCheck: false
11
}

2. Convert to JSON and add to Maven:
   • Convert the object to a JSON string
   • Enter it in the Live agent handoff configuration field in chat app settings

Configuration Options

Zendesk Configuration

Maven Chat integrates with Zendesk Conversations to provide human support capabilities. This integration requires configuration in both Zendesk and Maven.

Requirements

• Zendesk account with Professional plan or above
• Access to the Conversations API
• Admin access to configure integrations

Setup Process

Follow these steps to configure Zendesk integration:

1. Create Zendesk Integration

   • Navigate to the Zendesk Admin Center
   • Go to Apps and integrations > Integrations > Conversations integrations
   • Click Create integration
   • Enter a unique name for the integration

2. Configure Webhook

   • Set Webhook endpoint URL to https://chat.onmaven.app/api/zendesk/webhook
   • Uncheck Webhook body data
   • Check all Webhook subscriptions
   • Click Save
   • After saving, note the Webhook ID from the URL (it will be in the format https://admin.zendesk.com/admin/integrations/webhooks/{webhookId})

3. Generate API Key

   • Navigate to the API Keys tab
   • Click Create API key
   • Enter an identifying name for the key
   • Copy and securely store the provided ID and secret key
   • Click Next to complete the setup

Configuration

Create a handoff configuration object with the following structure:

1. Create your configuration object:

1
{
2
  type: 'zendesk',
3
  subdomain: 'your-zendesk-subdomain',
4
  apiKey: 'int_your_integration_api_key',
5
  apiSecret: 'your_integration_api_secret',
6
  appId: 'your_zendesk_app_id',
7
  webhookId: 'your-webhook-id'
8
}

2. Convert to JSON and add to Maven:
   • Convert the object to a JSON string
   • Enter it in the Live agent handoff configuration field in chat app settings

Configuration Options

Front Configuration

Maven Chat integrates with Front to provide human support capabilities. This integration requires configuration in both Front and Maven.

Requirements

• Front account with admin access
• Access to Front’s developer settings
• Maven-created Front Application Channel

Setup Process

Follow these steps to configure Front integration:

1. Create Front Application

   • Navigate to Front Developer Settings
   • Click Create App
   • Enter app name and description
   • Note the App UID and App Secret from Basic Information

2. Configure Channel

   • Go to the Features tab
   • Click Create channel type
   • Configure the following settings:
     • Set Webhook URL to https://chat.onmaven.app/api/front
     • Set Authentication strategy to Bearer
     • Set Contact type to Custom
     • Set Supported attachments to Text
     • Enable Reply/Compose
     • Set Composer type to Basic
     • Set Timeline Type UI to Chat Timeline
   • Click Create

3. Connect Channel in Front

   • Navigate to Channels under your workspace
   • Click Connect a channel
   • Find your channel under the “Other” section
   • Set Name and Token to orgId-agentId
   • Select target inbox and click Continue

Configuration

The handoff configuration requires two steps:

1. Create your configuration object:

1
{
2
  type: 'front',
3
  apiKey: 'your-front-api-token',
4
  appId: 'your-front-app-uid',
5
  apiSecret: 'your-front-app-secret',
6
  shiftNames: [],
7
  host: 'optional-self-hosted-front-url'
8
}

2. Convert to JSON and add to Maven:
   • Convert the object to a JSON string
   • Enter it in the Live agent handoff configuration field in chat app settings

Configuration Options

Additional Setup Requirements

1. Content Security Policy

   • Update your CSP to allow content from chat.onmaven.app

2. Widget Installation

   • Include the widget script:

     1
     <script src='https://chat.onmaven.app/js/widget.js' defer></script>

   • Initialize with configuration:

     1
     addEventListener("load", function () {
     2
       Maven.ChatWidget.load({
     3
         organizationId: "your-org-id",
     4
         agentId: "your-agent-id",
     5
         // ... other configuration options
     6
       });
     7
     });

Authentication

Signed User Authentication

Maven Chat now accepts signed and encrypted user authentication, allowing our customers to securely authenticate their users with Maven and persist user data across Maven apps. Authentication is optional and users will fall back to anonymous sessions.

Requirements

• A server-generated, signed and encrypted JWT containing user data
• A shared symmetrical encryption key, provided in the chat app settings (Encryption secret)
• A shared public key for verifying signing, provided in the chat app settings (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 will be included in the Maven user that’s created

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 chat 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
} & (
8
 { email: string, phoneNumber?: string } |
9
 { email?: string, phoneNumber: string }
10
)) {
11
 // 1. Sign the user data with your private key (ES256 algorithm)
12
 const signedJWT = await new SignJWT(userData)
13
   .setProtectedHeader({ alg: 'ES256' })
14
   .setIssuedAt()
15
   .setExpirationTime('1d')
16
   .sign(yourPrivateKey);
17
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
25
 return encryptedJWT;
26
}