Shopper Agent Implementation Guide

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

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}

# Kibo Helpdesk Configuration
HELPDESK_SITE_TOKEN=your_site_token_from_helpdesk
HELPDESK_BASE_URL=https://your-helpdesk-url.kibocommerce.com

module.exports = {
  publicRuntimeConfig: {
    helpdeskSiteToken: process.env.HELPDESK_SITE_TOKEN,
    helpdeskBaseUrl: process.env.HELPDESK_BASE_URL,
  },
}

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

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

import { HelpdeskWidget } from '@/components/core'

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

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"
}

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

# 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