AI Voice Agents

{
  "type": "object",
  "description": "Look up an order by its id",
  "properties": {
    "orderId": { "type": "string", "description": "The order id, e.g. ord_123" },
    "channel": { "type": "string", "enum": ["web", "store"] },
    "notify":  { "type": "boolean" }
  },
  "required": ["orderId"]
}

// Your backend: the API key never leaves the server.
import express from "express";
import { PurpleCallioClient } from "@purplecallio/sdk";

const client = new PurpleCallioClient({
  apiKey: process.env.PURPLECALLIO_API_KEY!,
  apiUrl: "https://purplecallio.com/api",
});

const app = express();

app.post("/api/ai-session", requireLogin, async (req, res) => {
  const session = await client.ai.createSession({
    agentId: process.env.PURPLECALLIO_AGENT_ID!,
    participant: { id: req.user.id, name: req.user.name },
    metadata: { plan: req.user.plan }, // optional, max 2 KB JSON
  });
  // Hand the browser only the short-lived bj_ai_ token.
  res.json({ token: session.token });
});

// Later, from your backend:
// await client.ai.getSession(sessionId);
// await client.ai.endSession(sessionId);

import { PurpleCallioAgentCall } from "@purplecallio/sdk";

async function talkToAgent() {
  const { token } = await fetch("/api/ai-session", { method: "POST" }).then((r) => r.json());

  const call = new PurpleCallioAgentCall({
    token,
    apiUrl: "https://purplecallio.com", // your PurpleCallio server origin (required)
  });

  call.on("transcript", ({ role, text, final }) => render(role, text, final));
  call.on("agentState", (state) => setIndicator(state)); // listening | thinking | speaking
  call.on("tool.confirmation_required", ({ id, name }) =>
    call.confirmTool(id, window.confirm(`Allow the agent to run ${name}?`)),
  );
  call.on("error", (err) => console.warn(err.code));
  call.on("ended", ({ reason }) => console.log("ended:", reason));

  await call.start(); // call from a click handler so audio can play
  // call.mute(); call.unmute(); call.end();
}

import { usePurpleCallioAI } from "@purplecallio/react";

const getToken = () =>
  fetch("/api/ai-session", { method: "POST" })
    .then((r) => r.json())
    .then((s) => s.token);

export function SupportAgent() {
  const ai = usePurpleCallioAI({
    getToken,
    apiUrl: "https://purplecallio.com", // required
  });

  if (ai.status === "idle" || ai.status === "ended") {
    return <button onClick={ai.start}>Talk to support</button>;
  }
  return (
    <div>
      <p>{ai.status} · {ai.agentState} · {ai.durationSeconds}s</p>
      <button onClick={ai.isMuted ? ai.unmute : ai.mute}>{ai.isMuted ? "Unmute" : "Mute"}</button>
      <button onClick={ai.end}>End</button>
      {ai.pendingConfirmations.map((t) => (
        <button key={t.id} onClick={() => ai.confirmTool(t.id, true)}>Allow {t.name}</button>
      ))}
      {ai.error && <p role="alert">{ai.error.code}</p>}
      {ai.transcript.map((l) => <p key={l.key}>{l.role}: {l.text}</p>)}
    </div>
  );
}

import { PurpleCallioAI } from "@purplecallio/react";

export function SupportWidget() {
  return (
    <PurpleCallioAI
      apiUrl="https://purplecallio.com" // required
      getToken={() => fetch("/api/ai-session", { method: "POST" }).then((r) => r.json())}
      className="my-agent"
      startLabel="Talk to support"
    />
  );
}

{
  "tool": "orderStatus",
  "arguments": { "orderId": "ord_123" },
  "sessionId": "…",
  "callId": "…",
  "agentId": "…",
  "participant": { "id": "user_42", "name": "Sam" }
}

const crypto = require("crypto");
const express = require("express");

const SECRET = process.env.PURPLECALLIO_TOOL_SECRET; // bj_tool_…
const MAX_SKEW_SECONDS = 300;

function verifyPurpleCallio(rawBody, headers) {
  const timestamp = headers["x-purplecallio-timestamp"];
  const signature = headers["x-purplecallio-signature"] || "";
  if (!timestamp || Math.abs(Date.now() / 1000 - Number(timestamp)) > MAX_SKEW_SECONDS) {
    return false; // missing or stale: possible replay
  }
  const expected =
    "sha256=" + crypto.createHmac("sha256", SECRET).update(`${timestamp}.${rawBody}`).digest("hex");
  const a = Buffer.from(signature);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

const app = express();

// Verify against the raw bytes, before any JSON parsing.
app.post("/tools/order-status", express.raw({ type: "application/json" }), (req, res) => {
  const raw = req.body.toString("utf8");
  if (!verifyPurpleCallio(raw, req.headers)) return res.status(401).json({ error: "bad signature" });
  const { arguments: args } = JSON.parse(raw);
  res.json({ status: lookUpOrder(args.orderId) });
});

// GET tools: the signed string is the `payload` query parameter.
app.get("/tools/order-status", (req, res) => {
  const raw = String(req.query.payload || "");
  if (!verifyPurpleCallio(raw, req.headers)) return res.status(401).json({ error: "bad signature" });
  const { arguments: args } = JSON.parse(raw);
  res.json({ status: lookUpOrder(args.orderId) });
});