# Zernio Voice Agent

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-enriquemarq1-zernio-library-skills-zernio-voice-agent`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Enriquemarq1](https://agentstack.voostack.com/s/enriquemarq1)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Enriquemarq1](https://github.com/Enriquemarq1)
- **Source:** https://github.com/Enriquemarq1/zernio-library-skills/tree/main/.claude/skills/zernio-voice-agent

## Install

```sh
agentstack add skill-enriquemarq1-zernio-library-skills-zernio-voice-agent
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# zernio-voice-agent

Build a **WhatsApp Voice AI agent** by asking Claude. Two tools, one flow:

- **Zernio** runs the messaging + orchestration and **places the WhatsApp call** (`start_call`).
- **Retell AI** runs the **real-time voice conversation** (STT → LLM → TTS, low-latency, human-sounding).
- The bridge between them is one field: **`start_call.forwardTo`** → a Retell SIP/WebSocket endpoint.

> **The skill informs; the agent acts.** This file + the two `reference/` docs give Claude the full
> contract. Claude builds the node graph, creates it through the Zernio API, and writes the Retell
> agent's prompt. **You stay in control** — Claude shows you the graph + both prompts and confirms
> before creating or activating (it goes live on a real number, and a call costs money).

## The architecture (memorize this)

```
WhatsApp inbound message
   └─▶ Zernio workflow: tag ─▶ human-escape ─▶ [ai] greet + qualify (text, with memory) ─▶ reply ─▶ wait
                                                          │
                                  contact replies "CALL"  ▼
                                              [start_call]  forwardTo ──▶  Retell AI voice agent
                                                  │ success → post-call text          (answers, talks, books)
                                                  │ permission_required → ask + loop
                                                  └ failed → fall back to text
```

Two brains, kept consistent: the **Zernio `ai` node** triages in chat; the **Retell agent** talks on
the call. Same name, same warmth, so it feels like one assistant.

## What you can ask
- "Build me a WhatsApp voice agent that books appointments."
- "When someone DMs and wants to talk, have an AI voice agent call them."
- "Connect my Retell agent to my Zernio WhatsApp number."
- "Write the voice prompt for the Retell agent."

## What Claude needs (ask once, remember in-session)
1. **ZERNIO_API_KEY** — `Authorization: Bearer ` (zernio.com → Settings → API keys).
2. **profileId + accountId** — `GET /v1/profiles`, `GET /v1/accounts`.
3. **A WhatsApp Business CALLING number bought + KYC'd inside Zernio** — `start_call` is WhatsApp-only
   and needs a real, verified number. **KYC can take days — start it first.** (Text-only testing works
   on the sandbox; the voice bridge needs the live number.) See `reference/whatsapp-calling-api.md`.
4. **A Retell AI account + a built agent** (voice, model, and the prompt from `templates/retell-voice-agent.base.md`),
   exposed for inbound calls — see `reference/retell-voice-api.md` for the SIP-bound-agent setup.
5. The **business details** in plain words — for BOTH prompts (the chat triage + the voice agent).

## The recipe (Claude follows this)

### 1. Write the two prompts
- **Text triage** — the Zernio `ai` node's systemPrompt (in the workflow template). Greets, answers,
  and offers the call. Fill the `[BRACKETS]`.
- **Voice agent** — the Retell agent's prompt. Start from `templates/retell-voice-agent.base.md`
  (read `templates/retell-voice-agent.example.md` for a filled one). Voice rules matter: no markdown,
  one question per turn, confirm names/numbers/times, end the call cleanly.

### 2. Stand up the Retell side (so `forwardTo` has a target)
Recommended: **static SIP-bound agent** (Path 1 in `reference/retell-voice-api.md`) — import a number
into Retell, bind your `agent_id`, and you get a fixed SIP address. Set the workflow's
`start_call.forwardTo` to it (`sip:…@sip.retellai.com`, or your trunk URI; `wss://…` also supported per
Zernio's WhatsApp Calling docs). Test the agent in Retell's playground first.

### 3. Build + create the Zernio workflow (one call, draft)
Start from `templates/whatsapp-voice-agent.workflow.json` — the memory-enabled text loop **plus** the
`start_call` escalation with `success` / `permission_required` / `failed` handled. Fill ``,
``, ``, ``, and the systemPrompt `[BRACKETS]`; strip `_` keys.
```bash
curl -s -X POST "https://zernio.com/api/v1/workflows" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" -H "Content-Type: application/json" \
  -d @workflow.json
```
Returns the workflow **id** in `draft`.

### 4. Activate
```bash
curl -s -X POST "https://zernio.com/api/v1/workflows//activate" -H "Authorization: Bearer $ZERNIO_API_KEY"
```
Pause anytime: `POST /v1/workflows//pause`. Edit only while `draft`/`paused`: pause → `PATCH` → activate.

### 5. Test the whole bridge end to end
On the live WhatsApp number: send a message → confirm the text agent replies with memory → reply `CALL`
→ confirm the phone rings, the Retell agent answers, and the conversation flows → hang up → confirm the
`success` post-call text. Then test the failure paths (deny permission → `permission_required`; bad
`forwardTo` → `failed` fallback). Inspect runs: `GET /v1/workflows//executions`.

## Gaps to design around (learned the hard way)
- **`start_call` is WhatsApp-only** and needs a **KYC'd calling number** — this is the long pole. Start KYC early.
- **The contact-number variable** in `start_call.to` — `{{contactPhone}}` is a placeholder. **Verify the
  exact run variable Zernio exposes** for the contact's number against a live execution before trusting it.
- **Always wire the `failed` edge** — a dropped call with no fallback strands the contact. The template
  falls back to text.
- **`permission_required`** — WhatsApp gates calls on contact opt-in (`requirePermissionFirst: true`).
  Handle the edge (ask them to allow calls, loop back) or the escalation silently dies.
- **Recording is off by default** — only `recordingEnabled: true` **with consent + disclosure** (and per
  local two-party-consent law).
- **Two bills, two brains** — Retell bills voice minutes/usage directly to your Retell account, separate
  from Zernio's carrier charges. And the voice prompt ≠ the text prompt; keep their tone consistent.
- **Retell ships fast / Zernio API evolves** — verify SIP endpoint shapes + the WhatsApp calling fields
  against live docs before a production deploy. Both reference files flag the spots to check.
- **Memory** — the text `ai` node has no built-in history; the `remember` set_variable accumulator is what
  gives multi-turn chat memory (same trick as `zernio-workflow-creator`). The Retell agent keeps its own
  per-call context.

## Guardrails
- **Confirm before create + before activate + before the first real call.** Show the graph, both prompts,
  and the `forwardTo` target. Get a yes.
- **Never print the API key.** It lives in env / the user's secret store.
- **Edit only while paused/draft.**
- **Voice = the brand on the phone.** The Retell prompt should sound like a warm human, one ask at a time —
  not a robotic IVR.

## Reference
- `reference/whatsapp-calling-api.md` — Zernio WhatsApp Calling + the `start_call` node (forwardTo, edges, prereqs).
- `reference/retell-voice-api.md` — Retell connection (SIP-bound agent, Register API, WebSocket) + gotchas.
- `templates/whatsapp-voice-agent.workflow.json` — the full Zernio workflow (text qualify → start_call → Retell).
- `templates/retell-voice-agent.base.md` — fill-in-the-blank Retell voice-agent prompt.
- `templates/retell-voice-agent.example.md` — a fully-filled voice prompt (appointment booking).
- Pairs with `zernio-workflow-creator` (the text-only agent + full 16-node Workflow API contract).

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Enriquemarq1](https://github.com/Enriquemarq1)
- **Source:** [Enriquemarq1/zernio-library-skills](https://github.com/Enriquemarq1/zernio-library-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-enriquemarq1-zernio-library-skills-zernio-voice-agent
- Seller: https://agentstack.voostack.com/s/enriquemarq1
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.