Skip to main content
This playbook is for teams that want the assistant to answer common questions and create a support handoff when the conversation needs a human. Typical examples:
  • Help desk ticket creation after a low-confidence answer
  • Support handoff when a user asks for an agent
  • CRM note creation after a completed assistant session
  • Internal triage based on session and request IDs

​
Flow

  1. Send the question to Uppzy from your backend
  2. Inspect the response metadata
  3. Show the answer if it is suitable for self-service
  4. Create a support ticket when escalation rules match
  5. Store session_id and request_id in your CRM record
  6. Submit feedback when the user or agent evaluates the answer

​
Escalation rules

Start with simple rules that your support team can audit. Common escalation signals:
  • confidence_level is low
  • User message includes an explicit handoff phrase
  • User gives bad feedback
  • Your application detects a sensitive business flow
  • The conversation has repeated unresolved questions
Do not send full API keys, private tokens, or raw payment data to your CRM notes.

​
Server-side handoff example

This example uses a placeholder createTicket function. Replace it with your CRM or help desk client. 
import { uppzy } from "./uppzy-client.js";
import { createTicket } from "./support-client.js";

const SITE_ID = process.env.UPPZY_SITE_ID;

function wantsHuman(message) {
  const normalized = message.toLowerCase();
  return normalized.includes("agent") || normalized.includes("human");
}

function shouldEscalate(message, answer) {
  return answer.confidence_level === "low" || wantsHuman(message);
}

export async function answerOrCreateTicket(req, res) {
  const { customerId, email, message } = req.body;
  const sessionId = `support_${customerId}`;

  const answer = await uppzy(`/m2m/sites/${SITE_ID}/chat`, {
    method: "POST",
    body: {
      session_id: sessionId,
      email,
      message,
      response_language: "en",
    },
  });

  if (shouldEscalate(message, answer)) {
    const ticket = await createTicket({
      customerId,
      subject: "Assistant handoff",
      summary: "A conversation needs support review.",
      metadata: {
        uppzy_session_id: answer.session_id,
        uppzy_request_id: answer.request_id,
        confidence_level: answer.confidence_level,
      },
    });

    return res.json({
      mode: "handoff",
      ticket_id: ticket.id,
      session_id: answer.session_id,
      request_id: answer.request_id,
      answer: answer.answer,
    });
  }

  return res.json({
    mode: "self_service",
    session_id: answer.session_id,
    request_id: answer.request_id,
    answer: answer.answer,
    confidence_level: answer.confidence_level,
  });
}

​
Agent review pattern

When an agent reviews the conversation, store only the operational identifiers you need. Recommended CRM metadata: 
{
  "uppzy_session_id": "support_91342",
  "uppzy_request_id": "req_abc123",
  "confidence_level": "low",
  "source": "uppzy_m2m"
}
Avoid putting API keys, internal credentials, full private customer records, or unrelated logs in CRM metadata.

​
Feedback after agent review

If an agent marks the answer as useful or not useful, submit a feedback event. 
import { uppzy } from "./uppzy-client.js";

const SITE_ID = process.env.UPPZY_SITE_ID;

export async function submitAgentFeedback(sessionId, requestId, useful) {
  return uppzy(`/m2m/sites/${SITE_ID}/chat/feedback`, {
    method: "POST",
    body: {
      session_id: sessionId,
      request_id: requestId,
      feedback: useful ? "good" : "bad",
    },
  });
}

​
Rollout checklist

  • Keep escalation rules simple at launch
  • Store session_id and request_id in the ticket metadata
  • Send only the minimum customer context your support process needs
  • Use feedback to mark useful and not useful answers
  • Review low-confidence answers weekly and update reference content