WHIZZVOICE
Docs · Build · Agents

Agents.

An agent is the thing that answers the phone: its persona, first message, languages, dialect, voice, tools, and knowledge base. You configure it once and reach it over the web widget, a phone number, or your SIP trunk. The router derives the engine and pricing tier from the language set — you never name a vendor.

Agent lifecycle#

FieldTypeDescription
draftstatusCreated or edited, not yet serving calls. Edits are free-form until you publish.
publishedstatusLive on the gateway at published_version. Calls route to this snapshot.

Editing a published agent updates the draft and re-syncs the live config on the next publish. Publishing snapshots an immutable version, so you can always roll back.

Create an agent#

POST/v1/agents
FieldTypeDescription
namestringoptionalHuman label for the dashboard. Defaults to "Untitled agent".
languagesstring[]requiredThe languages the agent speaks, as ISO codes — ar for Arabic plus any of the 31 others. Including ar routes the agent to the Dialect Engine and the Arabic pricing tier.
dialectstringoptionalThe Arabic dialect to speak — egyptian, saudi, gulf, levantine, msa, and more. See the dialect list.
voicestringoptionalA voice key valid for the chosen dialect or language (e.g. noura, yasmine). Falls back to the dialect's default voice.
first_messagestringoptionalThe line the agent opens with, in the caller's dialect. Sets the language before the caller speaks.
personastringoptionalSystem instructions — tone, boundaries, and what the agent must and must not do.
toolsstring[] | object[]optionalTools the agent may call mid-call, by name or full definition. Their inputs and outputs appear in the call's tool_calls.
knowledge_base_idstringoptionalA knowledge base to ground answers in via retrieval.
complianceobjectoptionalConsent and disclosure gates: { ai_disclosure, record_calls, consent_required }. ai_disclosure defaults to true.
Request
curl -X POST https://voice.whizztech.ai/v1/agents \
  -H "Authorization: Bearer $WHIZZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support · AR/EN",
    "languages": ["ar", "en"],
    "dialect": "saudi",
    "voice": "noura",
    "first_message": "حياك الله في خدمة عملاء وِز، كيف أقدر أخدمك؟",
    "persona": "Warm, concise support agent. Confirm the order before acting. Never invent a delivery date.",
    "tools": ["lookup_order", "expedite_shipment", "send_sms"],
    "knowledge_base_id": "kb_9d21f0a84c65",
    "compliance": { "ai_disclosure": true, "record_calls": true, "consent_required": true }
  }'
Response · 201 Created
{
  "id": "ag_7Q2c51b84a07",
  "object": "agent",
  "name": "Support · AR/EN",
  "status": "draft",
  "engine_route": "dialect",
  "lang_tier": "arabic",
  "languages": ["ar", "en"],
  "primary_language": "ar",
  "dialect": "saudi",
  "voice": "noura",
  "first_message": "حياك الله في خدمة عملاء وِز، كيف أقدر أخدمك؟",
  "persona": "Warm, concise support agent. …",
  "tools": ["lookup_order", "expedite_shipment", "send_sms"],
  "knowledge_base_id": "kb_9d21f0a84c65",
  "compliance": { "ai_disclosure": true, "record_calls": true, "consent_required": true },
  "published_version": 0,
  "created_at": "2026-07-13T09:32:18.000Z",
  "updated_at": "2026-07-13T09:32:18.000Z"
}

How routing is derived#

You never set the engine directly. The router reads the language set and returns engine_route and lang_tier:

FieldTypeDescription
engine_routestringdialect when Arabic or an extended language is present; global for mainstream languages; router for mixed sets that switch mid-call.
lang_tierstringThe pricing tier the agent bills at: lite · global · extended · arabic. An agent with any Arabic bills at arabic.

List & retrieve#

GET/v1/agents

Cursor-paginated, newest-first. Filter by status.

Response · 200 OK
{
  "object": "list",
  "data": [
    {
      "id": "ag_7Q2c51b84a07",
      "object": "agent",
      "name": "Support · AR/EN",
      "status": "published",
      "engine_route": "dialect",
      "lang_tier": "arabic",
      "published_version": 3,
      "created_at": "2026-07-13T09:32:18.000Z"
    }
  ],
  "has_more": false
}
GET/v1/agents/{id}

Returns the full agent object. IDs from other organizations return 404 not_found.

Update an agent#

PATCH/v1/agents/{id}

Send only the fields you want to change. Changing languages re-derives engine_route and lang_tier. If the agent is already published, the change lands on the draft — call publish to make it live.

Publish an agent#

POST/v1/agents/{id}/publish

Snapshots a new immutable version, syncs it to the gateway, and returns the web-widget embed. Attach a phone number to take PSTN calls.

Request
curl -X POST https://voice.whizztech.ai/v1/agents/ag_7Q2c51b84a07/publish \
  -H "Authorization: Bearer $WHIZZ_KEY"
Response · 200 OK
{
  "id": "ag_7Q2c51b84a07",
  "status": "published",
  "published_version": 4,
  "widget": {
    "agent_id": "ag_7Q2c51b84a07",
    "embed": "<script src=\"https://voice.whizztech.ai/w/ag_7Q2c51b84a07.js\" async></script>"
  }
}

Delete an agent#

DELETE/v1/agents/{id}

Removes the agent from the gateway and deletes it. In-flight calls finish; new calls to a deleted agent are rejected. Returns 204 No Content.

NextPhone numbers→