> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kibocommerce.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Shopper Agent Implementation Guide

This guide provides complete instructions for implementing and configuring the Kibo Shopper Agent on your commerce storefront. It covers live chat widget setup, Admin UI configuration, and storefront integration.

The Kibo Shopper Agent automates common customer service tasks such as order status lookups, return processing, and product inquiries. The system handles these requests programmatically without requiring human agent involvement. For requests that require human assistance, conversations can be escalated to live agents with full context preserved.

## Table of Contents

1. [Overview](#overview)
2. [Architecture](#architecture)
3. [Prerequisites](#prerequisites)
4. [Live Chat Widget Setup](#live-chat-widget-setup)
5. [Shopper Agent Admin UI](#shopper-agent-admin-ui)
6. [Storefront Widget Integration](#storefront-widget-integration)
7. [Testing Your Implementation](#testing-your-implementation)
8. [API Reference](#api-reference)
9. [Troubleshooting](#troubleshooting)

***

## Quick Start

Implementation involves three main areas of configuration:

| Step                          | What You Do                                                         | Time Estimate |
| ----------------------------- | ------------------------------------------------------------------- | ------------- |
| 1. **Live Chat Widget Setup** | Create inbox, configure webhook to Kibo backend, get site token     | 15-30 minutes |
| 2. **Admin UI Configuration** | Review/customize playbooks, enable tools, configure safety settings | 30-60 minutes |
| 3. **Storefront Integration** | Add environment variables, create widget component, deploy          | 1-2 hours     |

**Workflow Summary:**

```mermaid theme={null}
flowchart LR
    subgraph HelpDesk["Live Chat Widget Setup"]
        A1[Create inbox] --> A2[Get site token]
        A2 --> A3[Configure webhook]
    end

    subgraph Admin["Admin UI"]
        B1[Review playbooks] --> B2[Enable tools]
        B2 --> B3[Set safety filters]
        B3 --> B4[Test in Admin UI]
    end

    subgraph Storefront["Storefront"]
        C1[Add env vars] --> C2[Add widget component]
        C2 --> C3[Deploy & test]
    end

    HelpDesk --> Admin --> Storefront
```

***

## Overview

Kibo Shopper Agent is an AI-powered conversational platform that provides intelligent customer service and shopping assistance. The platform enables:

* **Customer Service Agents**: Handle order inquiries, returns, cancellations, and complaints
* **Shopper Assistants**: Guide customers through product discovery and purchases
* **Live Agent Handoff**: Seamlessly escalate to human agents via Kibo Helpdesk
* **Multi-Tenant Support**: Configure different agents per tenant and site

### Key Components

| Component               | Purpose                                                       |
| ----------------------- | ------------------------------------------------------------- |
| **Kibo Helpdesk**       | Customer messaging platform for live chat and bot integration |
| **Shopper Agent Admin** | Web UI for managing agents, playbooks, and tools              |
| **Storefront Widget**   | Customer-facing chat interface embedded in storefronts        |
| **Tool Runtime**        | Backend APIs that execute commerce operations                 |

***

## Architecture

```mermaid theme={null}
flowchart TB
    subgraph Customer["Customer Touchpoint"]
        Widget[Storefront Widget]
    end

    subgraph Messaging["Messaging Layer"]
        Helpdesk[Kibo Helpdesk]
    end

    subgraph AI["AI Engine (Kibo Managed)"]
        AIEngine[Conversational AI]
    end

    subgraph Backend["Backend Services (Kibo Managed)"]
        Middleware[Chat Middleware]
        Tools[Tool Runtime APIs]
    end

    subgraph Commerce["Kibo Commerce"]
        Platform[Kibo Platform APIs]
    end

    subgraph Management["Configuration"]
        Admin[Shopper Agent Admin UI]
    end

    Widget --> Helpdesk
    Helpdesk <--> Middleware
    Middleware <--> AIEngine
    AIEngine <--> Tools
    Tools <--> Platform
    Admin --> Middleware
```

### Message Flow

1. Customer sends message via Kibo Helpdesk widget
2. Kibo Helpdesk forwards message to webhook endpoint
3. Chat Middleware routes to the AI engine
4. AI engine determines intent and calls appropriate tools
5. Tool Runtime executes commerce operations (orders, products, etc.)
6. Response flows back through the chain to customer

***

## Prerequisites

Before starting, ensure you have:

### Accounts and Access

* [ ] Kibo Commerce tenant with API access
* [ ] Access to Shopper Agent Admin UI (provided by Kibo)
* [ ] Kibo Helpdesk account (provided by Kibo)

### Information You'll Need

| Item                      | Description                  | Where to Get It       |
| ------------------------- | ---------------------------- | --------------------- |
| Kibo Tenant ID            | Your Kibo tenant identifier  | Kibo Admin Console    |
| Kibo Site ID              | Target site identifier       | Kibo Admin Console    |
| Kibo API Credentials      | Client ID and Shared Secret  | Kibo Developer Portal |
| Shopper Agent Admin URL   | URL for the Admin UI         | Provided by Kibo      |
| Shopper Agent Backend URL | Webhook endpoint URL         | Provided by Kibo      |
| Kibo Helpdesk Instance    | Helpdesk URL and credentials | Provided by Kibo      |

### What Kibo Provides

The following are managed by Kibo and pre-configured for your tenant:

* Cloud infrastructure
* AI agents and configuration
* Backend services (Chat Middleware, Tool Runtime)
* Agent definitions and base playbooks

***

## Live Chat Widget Setup

Kibo Helpdesk serves as the messaging platform that connects customers with your AI agents. Your Kibo Helpdesk instance will be provisioned and configured by Kibo.

### Step 1: Access Your Kibo Helpdesk Instance

Your Kibo representative will provide you with access credentials and the URL for your Helpdesk instance.

### Step 2: Create an Inbox

1. Log into Kibo Helpdesk
2. Go to **Settings > Inboxes**
3. Click **Add Inbox**
4. Select **Website** as the channel type
5. Configure:
   * **Website Name**: Your storefront name
   * **Website Domain**: Your storefront domain
   * **Widget Color**: Match your brand
6. Click **Create Inbox**

### Step 3: Get Your Site Token

After creating the inbox:

1. Go to **Settings > Inboxes**
2. Click on your inbox
3. Navigate to **Configuration** tab
4. Copy the **Website Token** (this is your `HELPDESK_SITE_TOKEN`)

### Step 4: Configure Webhook Integration

This connects Kibo Helpdesk to the Kibo Agentic backend.

1. Go to **Settings > Integrations > Webhooks**
2. Click **Add Webhook**
3. Configure:
   * **Webhook URL**: `https://your-agentic-backend.com/webhook/chat/helpdesk`
   * **Events to Subscribe**:
     * `message_created`
     * `conversation_updated`
     * `conversation_status_changed`
4. Click **Add Webhook**

### Step 5: Configure Agent Bot

1. Go to **Settings > Integrations > Agent Bots**
2. Create a new agent bot:
   * **Name**: `Kibo AI Assistant`
   * **Outgoing URL**: `https://your-agentic-backend.com/webhook/chat/helpdesk`
3. Assign the bot to your inbox

### Step 6: Enable Custom Attributes

Custom attributes allow session tracking between Kibo Helpdesk and Kibo Commerce.

1. Go to **Settings > Custom Attributes**
2. Create a new attribute:
   * **Name**: `kibo-session-id`
   * **Display Name**: `Kibo Session ID`
   * **Type**: `Text`
   * **Applies To**: `Conversation`

### Kibo Helpdesk Configuration Summary

| Setting    | Value                          | Where to Find         |
| ---------- | ------------------------------ | --------------------- |
| Site Token | `HELPDESK_SITE_TOKEN`          | Inbox > Configuration |
| Base URL   | Your Kibo Helpdesk URL         | Provided by Kibo      |
| Account ID | Number shown in URL            | Settings page         |
| Inbox ID   | Number shown in inbox settings | Inbox > Settings      |

***

## Shopper Agent Admin UI

The Admin UI is used to configure agents, playbooks, tools, and safety settings.

### Accessing the Admin UI

Navigate to your Shopper Agent Admin deployment:

```
https://your-admin-url/_agentadmin/
```

### Step 1: Authentication

1. Log in with your credentials
2. Your user context will determine which GCP project and agents you can access

### Step 2: Agent Selection

1. From the **Dashboard**, click **Agents**
2. Your configured agents will be listed
3. Select the agent you want to configure

### Step 3: Playbook Configuration

Playbooks define the conversational behavior of your agent.

#### Creating a Playbook

1. Navigate to **Playbooks** in the agent menu
2. Click **Create Playbook**
3. Configure:
   * **Display Name**: Descriptive name (e.g., "Order Status Handler")
   * **Goal**: What the playbook accomplishes
   * **Instructions**: Step-by-step conversation flow

#### Playbook Instruction Syntax

```markdown theme={null}
Goal: Help customers check their order status

Instructions:
- Greet the customer warmly
- Ask for their order number or email address
- Use ${TOOL:GetOrderStatus} to retrieve order information
- Present the order status clearly including:
  - Current status
  - Shipping information
  - Estimated delivery date
- Ask if they need help with anything else
- If they want to make changes, transfer to ${PLAYBOOK:Order Modifications}
```

#### Key Playbook Features

| Feature            | Syntax                     | Description                   |
| ------------------ | -------------------------- | ----------------------------- |
| Tool Reference     | `${TOOL:ToolName}`         | Calls a configured tool       |
| Playbook Reference | `${PLAYBOOK:PlaybookName}` | Transfers to another playbook |
| Parameters         | Input/Output definitions   | Pass data between steps       |

### Step 4: Tool Configuration

Tools connect your agent to backend functionality.

#### Available Tool Types

| Type           | Use Case                             |
| -------------- | ------------------------------------ |
| **OpenAPI**    | REST APIs with OpenAPI specification |
| **Function**   | Custom functions with schema         |
| **Data Store** | RAG-based document retrieval         |
| **Connector**  | Pre-built integrations               |

#### Creating an OpenAPI Tool

1. Navigate to **Tools** in the agent menu
2. Click **Create Tool**
3. Select **OpenAPI** as the type
4. Configure:
   * **Display Name**: Tool name (e.g., "Get Order Status")
   * **OpenAPI Spec**: Paste your OpenAPI/Swagger specification
   * **Authentication**: Configure as needed

#### Tool Authentication Options

| Method            | Configuration                        |
| ----------------- | ------------------------------------ |
| **API Key**       | Key name and value                   |
| **OAuth 2.0**     | Client ID, Secret, Token URL, Scopes |
| **Bearer Token**  | Token value                          |
| **Service Agent** | GCP service account                  |

### Step 5: Safety Settings

Configure content safety to protect users and your brand.

1. Navigate to **Settings** in the agent menu
2. Configure **Safety Filters**:

| Filter            | Recommended Level |
| ----------------- | ----------------- |
| Hate Speech       | Block Some        |
| Dangerous Content | Block Few         |
| Sexually Explicit | Block Some        |
| Harassment        | Block Some        |

3. Configure **Banned Phrases**:
   * Add phrases that should never appear in responses
   * Choose partial or exact match

4. Enable **Prompt Security** (recommended):
   * Protects against prompt injection attacks

### Step 6: Set Start Playbook

1. From the Playbooks list, find your main entry playbook
2. Click the menu and select **Set as Start Playbook**
3. This playbook will be the first to handle conversations

***

## Storefront Widget Integration

The widget embeds Kibo Helpdesk into your storefront for customer interactions.

### Step 1: Environment Configuration

Add to your storefront's `.env.local` file:

```bash theme={null}
# Kibo Helpdesk Configuration
HELPDESK_SITE_TOKEN=your_site_token_from_helpdesk
HELPDESK_BASE_URL=https://your-helpdesk-url.kibocommerce.com
```

### Step 2: Next.js Configuration

Ensure `next.config.js` exposes the variables:

```javascript theme={null}
module.exports = {
  publicRuntimeConfig: {
    helpdeskSiteToken: process.env.HELPDESK_SITE_TOKEN,
    helpdeskBaseUrl: process.env.HELPDESK_BASE_URL,
  },
}
```

### Step 3: Create the Helpdesk Widget Component

Create `components/core/HelpdeskWidget/HelpdeskWidget.tsx`:

```typescript theme={null}
import { useEffect, useRef, useCallback } from 'react'
import getConfig from 'next/config'
import { useAuthContext } from '@/context'

declare global {
  interface Window {
    helpdeskSettings: any
    helpdeskSDK: any
    $helpdesk: any
  }
}

const HelpdeskWidget = () => {
  const { publicRuntimeConfig } = getConfig()
  const { helpdeskSiteToken, helpdeskBaseUrl } = publicRuntimeConfig
  const { isAuthenticated, user } = useAuthContext()
  const hasSetUser = useRef(false)

  const createKiboSession = useCallback(async () => {
    try {
      const response = await fetch('/api/create-chat-session', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
      })
      const data = await response.json()

      if (data.id && window.$helpdesk) {
        window.$helpdesk.setCustomAttributes({
          'kibo-session-id': data.id,
        })
      }
    } catch (error) {
      console.error('Failed to create chat session:', error)
    }
  }, [])

  const handleHelpdeskReady = useCallback(() => {
    if (user && window.$helpdesk && !hasSetUser.current) {
      window.$helpdesk.setUser(user.id, {
        email: user.emailAddress,
        name: `${user.firstName || ''} ${user.lastName || ''}`.trim(),
      })
      hasSetUser.current = true
    }
  }, [user])

  const handleStartConversation = useCallback(() => {
    createKiboSession()
  }, [createKiboSession])

  useEffect(() => {
    if (!helpdeskSiteToken || !isAuthenticated) return

    // Configure Kibo Helpdesk
    window.helpdeskSettings = {
      hideMessageBubble: false,
      position: 'right',
      locale: 'en',
      type: 'standard',
    }

    // Load Helpdesk SDK
    const script = document.createElement('script')
    script.src = `${helpdeskBaseUrl}/packs/js/sdk.js`
    script.async = true
    script.defer = true

    script.onload = () => {
      window.helpdeskSDK.run({
        websiteToken: helpdeskSiteToken,
        baseUrl: helpdeskBaseUrl,
      })
    }

    document.body.appendChild(script)

    // Event listeners
    window.addEventListener('helpdesk:ready', handleHelpdeskReady)
    window.addEventListener('helpdesk:on-start-conversation', handleStartConversation)

    return () => {
      window.removeEventListener('helpdesk:ready', handleHelpdeskReady)
      window.removeEventListener('helpdesk:on-start-conversation', handleStartConversation)
    }
  }, [helpdeskSiteToken, helpdeskBaseUrl, isAuthenticated, handleHelpdeskReady, handleStartConversation])

  if (!helpdeskSiteToken || !isAuthenticated) return null

  return null // Widget renders itself via script
}

export default HelpdeskWidget
```

### Step 4: Create the Session API Endpoint

Create `pages/api/create-chat-session.ts`:

```typescript theme={null}
import type { NextApiRequest, NextApiResponse } from 'next'

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  if (req.method !== 'POST') {
    return res.status(405).json({ error: 'Method not allowed' })
  }

  try {
    // Get auth token from your Kibo API client
    const authToken = await getKiboAuthToken()

    // Get user info from session/cookie
    const userInfo = getUserFromRequest(req)

    const response = await fetch(
      `https://${process.env.KIBO_API_HOST}/api/commerce/chat/sessions/`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${authToken}`,
          'Content-Type': 'application/json',
          'x-vol-locale': 'en-US',
        },
        body: JSON.stringify({
          userId: userInfo.userId,
          accountId: userInfo.accountId,
          data: {},
          isAnonymous: false,
        }),
      }
    )

    const data = await response.json()
    return res.status(200).json(data)
  } catch (error) {
    console.error('Session creation error:', error)
    return res.status(500).json({ error: 'Failed to create session' })
  }
}
```

### Step 5: Add Widget to Layout

In your `DefaultLayout.tsx`:

```typescript theme={null}
import { HelpdeskWidget } from '@/components/core'

export default function DefaultLayout({ children }) {
  return (
    <>
      <Header />
      <main>{children}</main>
      <HelpdeskWidget />
      <Footer />
    </>
  )
}
```

***

## Testing Your Implementation

### Test 1: Admin UI Agent Testing

1. Log into Shopper Agent Admin
2. Select your agent
3. Navigate to **Agent Testing**
4. Select your site from the dropdown
5. Send test messages:
   * "What's my order status?"
   * "I want to return an item"
   * "Help me find a product"
6. Verify:
   * Responses are contextually appropriate
   * Tools are being called correctly
   * No safety filter blocks on normal queries

### Test 2: Kibo Helpdesk Integration

1. Open Kibo Helpdesk dashboard
2. Go to your inbox
3. Trigger a test conversation via the widget
4. Verify in Kibo Helpdesk:
   * Message appears in inbox
   * Bot responds appropriately
   * Custom attribute `kibo-session-id` is set

### Test 3: Storefront Widget

1. Navigate to your storefront
2. Log in as a customer
3. Click the chat widget
4. Start a conversation
5. Verify:
   * Widget loads correctly
   * Messages send and receive
   * Agent responds with relevant information
   * Order lookups work with real data

### Test 4: End-to-End Verification

Complete this checklist to verify your full implementation:

1. **Session Creation**
   * Open browser Developer Tools (Network tab)
   * Start a new conversation in the widget
   * Verify `/api/create-chat-session` returns a session ID

2. **Kibo Helpdesk Custom Attributes**
   * In Kibo Helpdesk dashboard, open a test conversation
   * Check that `kibo-session-id` attribute is populated

3. **Tool Functionality**
   * Ask the agent about an existing order
   * Verify it returns real order data from your Kibo tenant

4. **Safety Filters**
   * Test that normal queries are not blocked
   * Verify banned phrases (if configured) are filtered

### Test Scenarios to Try

| Scenario        | Example Query                           | Expected Behavior         |
| --------------- | --------------------------------------- | ------------------------- |
| Order lookup    | "What's the status of my last order?"   | Returns order details     |
| Product search  | "Show me red dresses under \$100"       | Returns matching products |
| Return request  | "I want to return my recent purchase"   | Initiates return flow     |
| Store inventory | "Is this available at a store near me?" | Shows nearby inventory    |
| Handoff         | "I want to speak to a human"            | Transfers to live agent   |

***

## API Reference

This section documents APIs relevant to your storefront integration. The backend Tool Runtime APIs and Admin APIs are used internally and do not require direct integration.

### Storefront Session API

Your storefront needs to call the Kibo Chat Session API to create sessions. This is typically done through a proxy endpoint in your Next.js API routes.

**Create Session** (called by your `/api/create-chat-session` endpoint)

```
POST https://{KIBO_API_HOST}/api/commerce/chat/sessions/

Headers:
  Authorization: Bearer {kibo-api-token}
  Content-Type: application/json
  x-vol-locale: en-US

Body:
{
  "userId": "string",        // From authenticated user
  "accountId": number,       // From authenticated user
  "data": {},                // Optional custom data
  "isAnonymous": boolean     // false for logged-in users
}

Response:
{
  "id": "session-uuid",      // Use this as kibo-session-id in Kibo Helpdesk
  "userId": "string",
  "accountId": number,
  "expires": "datetime"
}
```

### Kibo Helpdesk Webhook URL

Configure this URL in Kibo Helpdesk settings (you don't call it directly):

```
POST https://{agentic-backend-url}/webhook/chat/helpdesk
```

This endpoint is provided by Kibo. You configure it as the webhook URL in your Kibo Helpdesk inbox settings.

### Available Agent Tools

The following tools are available to agents and can be enabled/disabled in the Admin UI:

| Tool                      | Description                         |
| ------------------------- | ----------------------------------- |
| GetOrderStatus            | Retrieve order status and details   |
| CancelOrder               | Cancel a customer order             |
| CreateReturnLabel         | Initiate a return process           |
| FindOrderByShipmentNumber | Search orders by shipment tracking  |
| ProductSearch             | Search the product catalog          |
| GetProductDetails         | Get detailed product information    |
| NearbyProductInventory    | Check inventory at nearby locations |
| GetCart                   | Retrieve shopping cart contents     |
| AddToCart                 | Add items to cart                   |
| InitiateCheckout          | Start the checkout process          |

Tools are configured and enabled through the Admin UI. The agent automatically uses available tools based on conversation context.

***

## Environment Variables Reference

### Storefront Environment Variables

These are the environment variables you need to configure in your headless storefront:

```bash theme={null}
# Kibo Helpdesk Integration (Required for Shopper Agent)
HELPDESK_SITE_TOKEN=your-site-token          # From Kibo Helpdesk Inbox Configuration
HELPDESK_BASE_URL=https://your-helpdesk.kibocommerce.com   # Provided by Kibo

# Kibo API (You should already have these configured)
KIBO_API_HOST=your-tenant-api-host
KIBO_CLIENT_ID=your-client-id
KIBO_SHARED_SECRET=your-shared-secret
```

| Variable              | Required | Description                                 |
| --------------------- | -------- | ------------------------------------------- |
| `HELPDESK_SITE_TOKEN` | Yes      | Website token from your Kibo Helpdesk inbox |
| `HELPDESK_BASE_URL`   | Yes      | Your Kibo Helpdesk URL (provided by Kibo)   |
| `KIBO_API_HOST`       | Yes      | Your Kibo API host                          |
| `KIBO_CLIENT_ID`      | Yes      | Your application client ID                  |
| `KIBO_SHARED_SECRET`  | Yes      | Your application shared secret              |

***

## Support

For additional assistance, contact your Kibo representative.