## Quick start

Setting up the chat widget is very simple and the standard integration should only take a few lines of code.

1. Visit the [**Chat agent**](https://app.assembledhq.com/automations/chat) page.
2. Select the **Setup** tab.
3. Copy the script tag under **Installation** on the page.
4. Add it to your HTML header (make sure it’s available on whatever page you’d like the chat widget to appear). It will look like this:

```auto
<script
  src="https://cal.assembledhq.com/static/js/public-chat.js"
  data-company-id="YOUR_COMPANY_ID"
></script>
```

## Manage activation and rollout

By default, the Assembled widget will not appear on your site until you explicitly turn it on. To adjust your activation settings:

1. Open the [**Chat agent**](https://cal.assembledhq.com/automations/chat) page in Assembled.
2. Select **Manage activation** (in the top right corner of the page).
3. Choose between:
   - **Activate for all visitors**: All visitors see the widget immediately.
   - **Gradual rollout**: A specified percentage of visitors see the widget; the same users will continue to see it over time.
   - **Deactivate for all visitors**: No visitors will be able to see the widget.

## Installing chat for Zendesk help centers

If you're hosting your support site on Zendesk Guide, you can very quickly add Assembled AI for chat. Here are the steps you can take:

1. Go to the administrative portal for your Zendesk Guide settings. The URL will be: [https://[YOUR ZENDESK DOMAIN].zendesk.com/knowledge](https://[your%20zendesk%20domain].zendesk.com/knowledge)
2. Next, find the **Customize design icon** on the navigation bar.
3. Select the theme you'd like to edit (usually the theme that is live) and select **Customize**.
4. Once you're in the theme, select **Edit code** in the bottom right corner of the screen
      - If you can't find the **Edit code** button, you may need to upgrade to Guide Professional or Guide Enterprise (see [Zendesk's help center documentation here](https://support.zendesk.com/hc/en-us/articles/4408832558874-Editing-the-code-for-your-live-help-center-theme)).
5. Go to the **document_head.hbs** file and add your Assembled AI script tag into the document.
   
6. Select **Publish** to save the changes and enable chat for your help center.

## User authentication

User authentication enables you to link chat interactions to user accounts in your application and enhance the chat experience based on your user data. When authenticated, you can:

- Track user conversations in the Assembled admin dashboard.
- Provide personalized responses based on user attributes (for example, different types of responses from VIP users to free users).
- Maintain conversation context across sessions.

### User data interface

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `user_id` | string | Yes | User's unique identifier |
| `email` | string | No | User's email address |
| `name` | string | No | User's display name |
| `metadata` | Record<string, unknown> | No | Additional user data as key-value pairs |

### JWT token requirement

The JWT token must contain a map of claims in the user data interface. For example, here's the simplest allowable JWT claim:

```auto
{
  "user_id": "CURRENT_USER_ID"
}
```

To generate the token:

1. Navigate to the [Chat agent Setup tab](https://app.assembledhq.com/automations/chat/profiles/1d4f82aa-2ccb-4b33-a358-f1f2f4777b5f?selectedTab=setup) in Assembled and click 'Manage JWT Secret' to retrieve your JWT secret
2. Create a JWT token on your server using this secret
3. Send the token to your frontend for authentication

Example token generation (Node.js):

```auto
const jwt = require('jsonwebtoken');
const secret = 'YOUR_JWT_SECRET'; // From Assembled dashboard

const token = jwt.sign(
  {
     user_id: 'user_123',
     email: 'user@example.com',
     name: 'John Doe',
     metadata: {
       plan: 'premium',
       company: 'Acme Inc'
     }
  },
  secret,
);
```

### Authentication

To authenticate a user, generate a JWT token from your server and pass this to your frontend so that you can securely identify a user:

```auto
await window.assembled.authenticateUser('YOUR_JWT_TOKEN');
```

### Setting user data without authentication

You can also pass user data without signing and authenticating the validity of the data. To set unauthenticated user information, you can use the `setUserData` method:

```auto
await window.assembled.setUserData({
  user_id: "usr_1234",
  name: 'John Smith',
  metadata: {
    plan: 'enterprise'
  }
});
```

### Configuring user data in chat agent

1. Go to **Configure > Info fields > Smart fields**.
2. Create new smart fields that you will use to map the user data to if they don't already exist.
3. Head to **AI support > Chat agent > Setup**.
4. Select the attribute from the JSON path and map each user attribute to a smart field.

## Technical requirements

- Modern browser support (IE11+)
- JavaScript enabled

## Troubleshooting

Common issues and solutions:

1. **Widget not appearing**:
   - Verify company ID is correct
   - Check console for error messages
   - Ensure script is loaded properly
   - Listen for the error event (see AI Chat installation - advanced setup) to confirm the widget reported a load failure
2. **Authentication failures**:
   - Verify JWT token is valid
   - Check token expiration
   - Ensure proper user data format
3. **Style issues**:
   - Clear browser cache
   - Check for CSS conflicts
   - Verify custom style parameters