Documentation

Build with Halo.

Put a voice agent inside your own product: an AI tutor in a lesson, an assistant in your app, an interviewer in your hiring flow. You design the agent in Halo; your server starts each call with the details for that person, your page connects to it, and the results come back to you.

Halo is in early access. Request access to get your workspace.

Quickstart

  1. 1

    Create an agent

    Write its instructions, pick a voice, add per-call details like {{student_name}} and the details it should collect.

  2. 2

    Test it

    Talk to it in the builder. Test calls are free.

  3. 3

    Publish and create an API key

    Publish the agent, then create a key in Settings → API keys.

  4. 4

    Start calls from your app

    Your server starts a call; your page connects with Halo's library.

  5. 5

    Get the results

    Read them from the API or receive them on your webhook.

Every agent's Use in your app tab shows its ID and this code, filled in for that agent.

Authentication

Send your API key as a bearer token: Authorization: Bearer halo_live_…. Create and revoke keys in Settings → API keys. Keys are shown once. Keep them on your server: anyone with a key can start calls on your minutes. The base URL is https://halo.techneeva.com/api/v1.

Start a call

POST /calls with the agent's ID and a value for each of its per-call details. The agent must be published. reference is yours (up to 20 keys): it comes back with the results so you know which user or lesson the call was for.

// On your server. The key lives in an environment variable, never in a page.
const res = await fetch("https://halo.techneeva.com/api/v1/calls", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HALO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agentId: "agt_k3x9q2m8p1zt",
    variables: { student_name: "Priya", topic: "Photosynthesis" },
    reference: { studentId: "stu_42", lessonId: "bio-101-4" },
    userName: "Priya",
  }),
})
const call = await res.json()
// { id: "call_…", status: "in_progress", joinToken: "join_…", joinTokenExpiresAt: "…" }

Send the joinToken to the user's page. It works once, within 10 minutes. Every per-call detail is required, and unknown ones are refused, so a typo shows up straight away.

Connect in your page

Add Halo's library and start the call with the join token. It asks for the microphone, plays the agent's voice and gives you live captions; how it looks is up to you.

<script src="https://halo.techneeva.com/sdk/halo.js"></script>
<script>
  // joinToken comes from your server (it works once, within 10 minutes).
  const call = await Halo.startCall({
    joinToken,
    onStatus: (status) => {},          // "connecting" → "live" → "ended"
    onCaption: (c) => {},              // { id, role: "agent" | "user", text, final }
    onAgentSpeaking: (speaking) => {}, // true while the agent talks
  })

  muteButton.onclick = () => call.mute(true)
  endButton.onclick = () => call.end()
</script>

Halo.startCall throws a HaloError with a code: invalid_join_token, microphone_blocked or connect_failed, and a message you can show to the user.

Get the results

GET /calls/{id} returns the call. Once status is ended you get the summary, every detail the agent collected (keyed by the names you gave them) and the transcript:

{
  "id": "call_b2qkciopy3ba",
  "agentId": "agt_k3x9q2m8p1zt",
  "status": "ended",
  "result": "completed",
  "reference": { "studentId": "stu_42", "lessonId": "bio-101-4" },
  "variables": { "student_name": "Priya", "topic": "Photosynthesis" },
  "createdAt": "2026-11-14T19:02:07Z",
  "startedAt": "2026-11-14T19:02:11Z",
  "endedAt": "2026-11-14T19:03:21Z",
  "durationSecs": 70,
  "summary": "Priya explained photosynthesis and knew it happens in the leaves, but wasn't sure what chlorophyll does…",
  "collected": {
    "understood_the_topic": "Yes",
    "weak_areas": "Not sure what chlorophyll does"
  },
  "transcript": [
    { "role": "agent", "text": "Hi Priya! Ready to go over Photosynthesis?", "atSecs": 1 },
    { "role": "user", "text": "It's how plants make their food using sunlight.", "atSecs": 7 }
  ],
  "hasRecording": true
}

result is completed, hung_up (the user left before talking) or failed. The summary can take a few seconds after the call ends; webhooks are sent once it's ready.

More endpoints

POST/calls
GET/calls/{id}
GET/calls?agentId=&limit=
POST/calls/{id}/end
GET/agents

Webhooks

Add a URL in Settings → Webhooks and Halo sends a POST when each call from your app ends (event call.ended; test calls from the builder aren't sent). Answer with any 2xx within 10 seconds. Failed deliveries are tried again after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours, and every attempt is listed in Settings. Use halo-event-id to ignore a repeat.

POST https://api.yourapp.com/halo/webhook
halo-signature: t=1763146945,v1=5f2c…
halo-event-id: evt_…

{
  "id": "evt_…",
  "type": "call.ended",
  "createdAt": "2026-11-14T19:03:40Z",
  "data": { …the call, exactly as GET /calls/{id} returns it… }
}

Verify signatures

Each webhook has a halo-signature header: a timestamp and an HMAC-SHA256 of timestamp.body made with your webhook's signing secret. Check it before you trust the request:

import crypto from "node:crypto"

// Use the raw request body, before any JSON parsing.
export function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")))
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex")
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300
  return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 ?? ""))
}

Errors and limits

Errors look like { "error": { "code": "…", "message": "…" } }. The message says what to fix.

400missing_variablesA per-call detail wasn't sent. `missing` lists them.
400unknown_variableA detail the agent doesn't have (often a typo). `expected` lists the right ones.
401unauthorizedMissing, wrong or revoked API key.
402minutes_used_upThis month's minutes are used up. `resetsOn` says when they come back.
403workspace_pausedThe workspace is paused. Contact support.
404agent_not_foundNo agent (or call) with this ID in your workspace.
409agent_not_livePublish the agent first.
429too_many_callsUp to 10 calls run at once in early access.

Calls last at most the agent's maximum call length. Only connected talk time counts towards your minutes, and test calls are free. Questions? Write to support@techneeva.com.