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.
Authentication
One secret key, on your server.
Start a call
Personalise every call with its own details.
Connect in your page
Mic, voice and captions in your own design.
Webhooks
Results the moment a call ends.
Halo is in early access. Request access to get your workspace.
Quickstart
- 1
Create an agent
Write its instructions, pick a voice, add per-call details like {{student_name}} and the details it should collect.
- 2
Test it
Talk to it in the builder. Test calls are free.
- 3
Publish and create an API key
Publish the agent, then create a key in Settings → API keys.
- 4
Start calls from your app
Your server starts a call; your page connects with Halo's library.
- 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
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.
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.