Build a voice for your OpenClaw bot.

1. The one thing to understand: your bot defines the voice agent.

Workforce Wave gives every account a voice agent. Your bot supplies that agent's identity by sending a personality and a greeting. The agent's name, its job, its tone, and its rules all live inside those two fields. Changing the bot is just sending new text.

If you run an OpenClaw bot, you literally hand your bot's own persona and task to the voice agent and it becomes the caller. Fill in the identity block below, and the guide turns it into the exact request that defines your bot.

2. Edit this - your bot's identity.

Fill these in. Everything else in the guide reads from them. You can change them anytime by repeating Step 4.

BOT_NAME      = Nova
BOT_ROLE      = an AI scheduling assistant for Acme Plumbing
BOT_TASK      = Call customers to confirm tomorrow's appointments and reschedule if needed.
GREETING      = Hi, this is Nova from Acme Plumbing. I'm calling to confirm your appointment.
VOICE_ID      = (leave blank for the default voice, or paste an ElevenLabs voice id)
TONE_RULES    = Be warm, brief, and natural. One or two short sentences per turn. Never invent facts; if unsure, say you will have someone follow up.

These assemble into the agent's personality (its system prompt) and firstMessage (the opening line it speaks). You can re-send them anytime to rebrand the bot on the fly.

3. Two kinds of access.

Setup calls use your account session. Everything after that uses your bot's scoped key.

Your scoped key controls only your agent. Keep it secret. You can revoke and re-mint it anytime.

4. Step by step.

curl -X POST https://wfw-admin.vercel.app/api/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"name":"My Voice Bot","email":"you@example.com","phoneNumber":"+18435551234","password":"a-strong-password"}'

JAR=cookies.txt
CSRF=$(curl -s -c $JAR https://wfw-admin.vercel.app/api/auth/csrf \
  | python -c "import sys,json;print(json.load(sys.stdin)['csrfToken'])")

curl -s -c $JAR -b $JAR -X POST https://wfw-admin.vercel.app/api/auth/callback/credentials \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "csrfToken=$CSRF" \
  --data-urlencode "email=you@example.com" \
  --data-urlencode "password=a-strong-password" \
  --data-urlencode "json=true"

curl -s -b cookies.txt -X POST https://wfw-admin.vercel.app/api/bots/initialize \
  -H "Content-Type: application/json" -d '{}'

{ "success": true, "apiKey": "wfwk_xxxxxxxx", "agentId": "agent_xxxx", "clientId": 123 }

curl -s -X PATCH https://wfw-admin.vercel.app/api/bots/agent \
  -H "X-Bot-Key: wfwk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "personality": "You are Nova, an AI scheduling assistant for Acme Plumbing. Your job: Call customers to confirm tomorrow\'s appointments and reschedule if needed. Be warm, brief, and natural. One or two short sentences per turn. Never invent facts; if unsure, say you will have someone follow up.",
    "firstMessage": "Hi, this is Nova from Acme Plumbing. I\'m calling to confirm your appointment.",
    "voiceId": ""
  }'

curl -s -X POST https://wfw-admin.vercel.app/api/bots/agent/simulate \
  -H "X-Bot-Key: wfwk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"userInput":"Hi, who is this?"}'

curl -s -X POST https://wfw-admin.vercel.app/api/bots/payment-method/setup \
  -H "X-Bot-Key: wfwk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"lineType":"outbound_shared"}'

curl -s -X POST https://wfw-admin.vercel.app/api/bots/calls \
  -H "X-Bot-Key: wfwk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"phone_number":"+18435559876"}'

# List recent tasks using your session cookie
curl -s -b cookies.txt "https://wfw-admin.vercel.app/api/bots/tasks?limit=10"

# Or read a single task by the ID returned from the calls endpoint
# curl -s -b cookies.txt "https://wfw-admin.vercel.app/api/bots/tasks/{taskId}"

5. Change the bot anytime.

Renaming or repurposing is just Step 4 again with new text. The change is live immediately for the next call.

# Become a friendly survey caller named "Sam"
curl -s -X PATCH https://wfw-admin.vercel.app/api/bots/agent \
  -H "X-Bot-Key: wfwk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "personality": "You are Sam, a cheerful survey caller for Riverside Gym. Your job: ask members three quick questions about their experience. Keep it under a minute.",
    "firstMessage": "Hi, this is Sam from Riverside Gym with a 30-second survey, is now okay?"
  }'

6. Driving it from an OpenClaw bot.

Your OpenClaw bot already has a personality and a task. Hand those straight to Workforce Wave so the phone agent IS your bot. Minimal Python wrapper:

#!/usr/bin/env python3
"""wfwbot - let an OpenClaw bot run a Workforce Wave voice line.
Subcommands:
  define              push this bot's name/personality/task to its WFW voice agent
  call <number>       place a call
  simulate "<text>"   free text test
Env: WFW_BOT_KEY (from /api/bots/initialize). Provisioning (signup/login/initialize)
is done once; see the steps above.
"""
import os, sys, json, urllib.request

BASE = "https://wfw-admin.vercel.app"
KEY  = os.environ["WFW_BOT_KEY"]

# Your bot's identity. An OpenClaw bot can pass its OWN system prompt as PERSONALITY.
BOT_NAME  = os.environ.get("BOT_NAME", "Nova")
BOT_ROLE  = os.environ.get("BOT_ROLE", "an AI assistant for Workforce Wave")
BOT_TASK  = os.environ.get("BOT_TASK", "Help the caller and take a message.")
GREETING  = os.environ.get("BOT_GREETING", f"Hi, this is {BOT_NAME}. How can I help?")
VOICE_ID  = os.environ.get("BOT_VOICE_ID", "")
RULES     = "Be warm, brief, and natural. One or two short sentences per turn. Never invent facts."

def post(path, body, patch=False):
    req = urllib.request.Request(BASE + path, data=json.dumps(body).encode(),
        headers={"X-Bot-Key": KEY, "Content-Type": "application/json"},
        method="PATCH" if patch else "POST")
    return json.load(urllib.request.urlopen(req))

def define():
    personality = f"You are {BOT_NAME}, {BOT_ROLE}. Your job: {BOT_TASK} {RULES}"
    body = {"personality": personality, "firstMessage": GREETING}
    if VOICE_ID:
        body["voiceId"] = VOICE_ID
    print(json.dumps(post("/api/bots/agent", body, patch=True), indent=2))

def call(number):
    print(json.dumps(post("/api/bots/calls", {"phone_number": number}), indent=2))

def simulate(text):
    print(json.dumps(post("/api/bots/agent/simulate", {"userInput": text}), indent=2))

if __name__ == "__main__":
    cmd = sys.argv[1] if len(sys.argv) > 1 else "define"
    if cmd == "define": define()
    elif cmd == "call": call(sys.argv[2])
    elif cmd == "simulate": simulate(sys.argv[2])

Usage:

export WFW_BOT_KEY=wfwk_xxxxxxxx
export BOT_NAME="Nova"  BOT_ROLE="a receptionist for Acme"  BOT_TASK="Book appointments."
python wfwbot.py define
python wfwbot.py simulate "who is this?"
python wfwbot.py call +18435559876

To make an OpenClaw skill out of it, register wfwbot.py as a skill command and let the model call define (with its own persona/task) and call <number>.

7. Editable fields reference.

Every field you can change on the fly, where it goes, and what it controls.

The bot's name is set by the words you put in personality and firstMessage(for example "You are Nova..."). Renaming is just editing those two fields.

8. Good to know.