# Live Chat in Zendesk

## Raia × Zendesk Help Center Integration Guide

A practical, copy-pasteable guide for embedding **Raia Live Chat** in a Zendesk Help Center (Guide), passing user context for tracking/analytics, and conditionally loading different chat configurations (e.g., Premium vs Standard).

***

### 0) At-a-glance

* **Where to add code in Zendesk:** `Guide Admin → Customize design → Edit code → templates/document_head.hbs` (loads on every Help Center page).
* **Minimum you need:** Raia Live Chat embed snippet (API key), a Preview or duplicate theme you can publish, and (optionally) your CSP allowlist.
* **Identity & context:** Pass `user.id`, `user.name`, and (if needed) organization names to Raia for identification and routing.
* **Conditional loading:** Load different Raia widgets (keys/config) based on user context (e.g., Premium vs Standard).

***

### Quick Start (10‑minute setup)

**Goal:** get Raia Live Chat running in your Zendesk Help Center with user context.

#### 1) Paste the embed snippet

In `templates/document_head.hbs`:

```html
<script async src="https://raiabot.raia2.com/assets/raia-chatbot-widget.js" data-api-key="YOUR_API_KEY" onload="onRaiaChatLoaded()"></script>
```

#### 2) Add the onload callback

Just above the script tag:

```html
<script>
  function onRaiaChatLoaded() {
    // Identify the signed-in user from Zendesk Curlybars
    raiaChat.sendCommand('SET_USER', {
      user: { fkId: '{{user.id}}', firstName: '{{user.name}}', email: '{{user.email}}' }
    });

    // Provide conversation context for the AI Agent
    raiaChat.sendCommand('SET_CONTEXT', { context: 'zendesk_help_center' });

    // Optional: let the agent use current page text as context
    // raiaChat.sendCommand('ENABLE_CURRENT_PAGE_TEXT');
  }
</script>
```

#### 3) Publish & test

* Preview the theme → open an article page → verify the launcher appears.
* Start a chat; confirm your user appears in Raia with the correct `fkId` and email.

**That’s it.** You can now fine‑tune behavior with the SDK commands below and (optionally) set up Premium vs Standard keys and asynchronous Zendesk escalation.

***

### 1) Embed the Raia Live Chat agent

Paste your Raia snippet near the bottom of **`document_head.hbs`**, just before `</head>`.

```html
<!-- Raia Live Chat -->
<script async src="https://raiabot.raia2.com/assets/raia-chatbot-widget.js" data-api-key="YOUR_API_KEY" onload="window.onRaiaChatLoaded && window.onRaiaChatLoaded()"></script>
```

**Tips**

* Use a **Preview** or a **cloned theme** first. After verification, click **Publish**.
* For multi-brand: repeat in each brand’s active theme (or only where you want Raia).

***

### 2) Pass user context from Zendesk to Raia (via Live Chat SDK)

Use the **Live Chat SDK** to pass identity and context after the script loads. Choose one approach.

#### Option A — Onload + SDK (simple & recommended)

```html
<script>
  function onRaiaChatLoaded() {
    // Identify the signed-in user from Zendesk Curlybars
    raiaChat.sendCommand('SET_USER', {
      user: {
        fkId: '{{user.id}}',
        firstName: '{{user.name}}',
        email: '{{user.email}}'
      }
    });

    // Provide conversation context for the AI Agent
    raiaChat.sendCommand('SET_CONTEXT', { context: 'zendesk_help_center' });

    // (Optional) Allow the agent to use current page text as context
    // raiaChat.sendCommand('ENABLE_CURRENT_PAGE_TEXT');
  }
</script>
<script async src="https://raiabot.raia2.com/assets/raia-chatbot-widget.js" data-api-key="YOUR_API_KEY" onload="onRaiaChatLoaded()"></script>
```

#### Option B — Global object + SDK (richer payloads)

```html
<script>
  window.RAIA_CONTEXT = {
    user: {
      fkId: '{{user.id}}',
      firstName: '{{user.name}}',
      email: '{{user.email}}',
      organizations: [ {{#each user.organizations}}"{{name}}"{{#unless @last}},{{/unless}}{{/each}} ]
    },
    page: { url: location.href, title: document.title }
  };
  function onRaiaChatLoaded() {
    raiaChat.sendCommand('SET_USER', { user: window.RAIA_CONTEXT.user });
    raiaChat.sendCommand('SET_CONTEXT', { context: 'help_center' });
  }
</script>
<script async src="https://raiabot.raia2.com/assets/raia-chatbot-widget.js" data-api-key="YOUR_API_KEY" onload="onRaiaChatLoaded()"></script>
```

#### Option C — JSON script tag + SDK (safe escaping)

```html
<script id="raia-user" type="application/json">{ "fkId": "{{user.id}}", "firstName": "{{user.name}}", "email": "{{user.email}}" }</script>
<script>
  function onRaiaChatLoaded() {
    try {
      const raw = document.getElementById('raia-user')?.textContent || '{}';
      raiaChat.sendCommand('SET_USER', { user: JSON.parse(raw) });
      raiaChat.sendCommand('SET_CONTEXT', { context: 'help_center' });
    } catch(e) {}
  }
</script>
<script async src="https://raiabot.raia2.com/assets/raia-chatbot-widget.js" data-api-key="YOUR_API_KEY" onload="onRaiaChatLoaded()"></script>
```

***

### 3) Identify the user in Raia for tracking & routing (SDK)

Use the SDK commands in your `onRaiaChatLoaded` callback:

```html
<script>
  function onRaiaChatLoaded() {
    const u = window.RAIA_CONTEXT?.user || { fkId: '{{user.id}}', firstName: '{{user.name}}', email: '{{user.email}}' };

    // Identify the user for tracking/memory
    raiaChat.sendCommand('SET_USER', { user: u });

    // Attach conversation/session context for the AI Agent
    raiaChat.sendCommand('SET_CONTEXT', {
      context: 'zendesk_help_center/{{help_center.name}}/{{help_center.locale}}'
    });
  }
</script>
```

This enables attribution, routing (e.g., Premium), and cleaner analytics.

***

### 4) Conditional loading (e.g., Premium vs Standard)

Load the correct key/config at runtime based on user attributes.

```html
<script>
  const orgsCSV = '{{#each user.organizations}}{{name}}{{#unless @last}},{{/unless}}{{/each}}';
  const isPremium = (orgsCSV || '').split(',').map(s=>s.trim()).includes('Premium');
  const apiKey = isPremium ? 'YOUR_PREMIUM_API_KEY' : 'YOUR_STANDARD_API_KEY';

  function onRaiaChatLoaded() {
    raiaChat.sendCommand('SET_USER', { user: { fkId: '{{user.id}}', firstName: '{{user.name}}' } });
    raiaChat.sendCommand('SET_CONTEXT', { context: isPremium ? 'premium' : 'standard' });
  }

  const s = document.createElement('script');
  s.src = 'https://raiabot.raia2.com/assets/raia-chatbot-widget.js';
  s.async = true;
  s.setAttribute('data-api-key', apiKey);
  s.onload = onRaiaChatLoaded;
  document.head.appendChild(s);
</script>
```

***

### 5) Content Security Policy (CSP)

If your Help Center enforces CSP, add Raia endpoints. Example (tighten as needed):

```
script-src   https://raiabot.raia2.com;
connect-src  https://api.raia2.com https://raiabot.raia2.com YOUR_BACKEND_HOST;
img-src      https://raiabot.raia2.com data:;
frame-src    https://raiabot.raia2.com;
```

***

### 6) Escalation to Zendesk (Recommended: **Asynchronous Ticket Handoff**)

Standard approach for clients: **Raia Live Chat collects transcript & context and a Zendesk Support ticket is created via API**. An agent follows up by email. If a synchronous human conversation is needed, your team can initiate a **live transfer via Raia Co‑Pilot**.

#### 6.1 What clients configure

* **When to escalate:** keywords ("human"), low-confidence paths, premium users, or specific flows.
* **What to send:** requester identity (email/name or external id), summary subject, transcript (or link), plan/brand/locale/org, and any relevant tags.
* **Where to send:** your backend endpoint that calls the Zendesk **Tickets API** (keep credentials server-side).
* **What users see:** a confirmation message in the Raia widget (with optional ticket number) and an email reply from Support.

#### 6.2 UI copy (ready to paste)

> “I’ve shared this conversation with our support team. You’ll get an email update shortly. Ticket: **#{{ticket\_id}}**.”

#### 6.3 Best practices

* Use a **stable external ID** to join Raia sessions to Zendesk users.
* Route Premium customers via group/priority/tags.
* Keep PII minimal; enrich server-side.
* Verify requests from Raia to your backend (shared secret/JWT).

***

### 7) Developer access

* **Zendesk:** API token/OAuth, custom fields, groups.
* **Infra:** A minimal endpoint (Cloud Run/Functions) that calls Zendesk Tickets API.
* **Raia:** Configure escalation rules; access to conversation IDs/transcripts.

***

### 8) Live Chat SDK Reference

#### Commands

* `OPEN_CHAT` `{ page }`
* `CLOSE_CHAT`
* `SEND_MESSAGE` `{ message }`
* `SET_USER` `{ user: { fkId, fkUserId?, firstName?, lastName?, email?, phoneNumber?, customData? } }`
* `CLEAR_USER`
* `SET_CONTEXT` `{ context }`
* `CLEAR_CONTEXT`
* `ENABLE_CURRENT_PAGE_TEXT`
* `DISABLE_CURRENT_PAGE_TEXT`

#### Usage notes

* Always call `raiaChat.sendCommand(...)` **after** the script loads.
* Use the script tag’s `onload` attribute or a window callback (`onRaiaChatLoaded`).

#### Example onload usage

```html
<script>
  function onRaiaChatLoaded() {
    raiaChat.sendCommand("OPEN_CHAT", { page: "chat" });
    raiaChat.sendCommand("SET_CONTEXT", { context: "test context" });
    raiaChat.sendCommand("ENABLE_CURRENT_PAGE_TEXT");
    raiaChat.sendCommand("SET_USER", {
      user: {
        email: "test@test.com",
        fkId: "123",
        fkUserId: "456",
        customData: { productId: "dk3j02k", quantity: 10 }
      }
    });
  }
</script>

<script async src="https://raiabot.raia2.com/assets/raia-chatbot-widget.js" data-api-key="YOUR_API_KEY" onload="onRaiaChatLoaded()"></script>
```

#### Example integration

* [CodeSandbox demo](https://codesandbox.io/p/sandbox/4w5g86)

***

### 9) Full Implementation Plan

#### Phase 1 — Enable the widget

1. Add embed snippet + `onRaiaChatLoaded` (Quick Start above).
2. Verify widget loads on homepage, category, article, and search pages.

#### Phase 2 — Identify users & context

1. Pass `SET_USER` (at minimum `fkId`, optionally name/email).
2. Pass `SET_CONTEXT` with a simple source tag (`zendesk_help_center`).
3. (Optional) `ENABLE_CURRENT_PAGE_TEXT` for richer context.

#### Phase 3 — Conditional experiences

1. Decide how to determine Premium vs Standard (org name, SSO claim, etc.).
2. Use conditional loader to choose the correct `data-api-key`.

#### Phase 4 — Escalation to Zendesk (asynchronous)

1. Configure escalation rules in your Raia agent (keywords/low confidence/premium).
2. On escalate, your backend creates a Zendesk ticket via API with transcript/context.
3. Confirm widget copy shows ticket ID and email follow‑up expectations.

#### Phase 5 — Compliance & CSP

1. Add CSP allowlist for `https://raiabot.raia2.com` and `https://api.raia2.com` (see §5).
2. Minimize PII; prefer stable IDs.

#### Phase 6 — QA & Launch

1. Test signed‑in vs anonymous users.
2. Test Premium vs Standard routing.
3. Test escalation path end‑to‑end (ticket created, email received).
4. Publish in a low‑traffic window; monitor for 24–48h.

***

### 10) Rollout Plan (Checklist)

1. **Clone** current theme → create **Staging** theme.
2. Add SDK embed + context passing (and conditional logic if needed).
3. **Preview** across key page types; validate identity & CSP.
4. Configure **asynchronous escalation** endpoint; test with Premium/Standard.
5. **Publish** during a low-traffic window.
6. **Monitor** logs and Zendesk ticket creation for 48h; have rollback ready.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.raiaai.com/applications/chat/live-chat-in-zendesk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.