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:

<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:

<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>.

<!-- 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)

<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)

<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)

<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:

<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.

<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

<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: "[email protected]",
        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

9) Full Implementation Plan

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

Phase 2 — Identify users & context

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

Phase 3 — Conditional experiences

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

Phase 4 — Escalation to Zendesk (asynchronous)

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

Phase 5 — Compliance & CSP

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

Phase 6 — QA & Launch

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

10) Rollout Plan (Checklist)

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

PreviousLive Chat SDK NextAcademy

Last updated 14 days ago