> ## Documentation Index > Fetch the complete documentation index at: https://docs.voice.wixzel.com/llms.txt > Use this file to discover all available pages before exploring further. # Change a mascot's share id > Gives the agent's mascot a new `public_id`. Its old share link and embed code stop working at once. Requires `agents:write` and `calls:write`. ## OpenAPI ````yaml /openapi.json post /v1/agents/{id}/mascot/rotate-public-id openapi: 3.1.0 info: title: Wixzel Voice API version: '2026-09-01' description: >- APIs for agentic telephony. One API key, one balance, every voice engine. ## Authentication Send your key as `Authorization: Bearer wv_live_...`. Keys are scoped: grant only what an integration needs. There is no admin scope. ## Versioning The `/v1` prefix covers additive changes. Behavioural changes ship behind a dated `Wixzel-Version` header, and existing keys keep the behaviour they were created with. ## Money Amounts are integer **micro-USD** (1,000,000 = $1.00). Voice usage is billed per second, per token and per character, so a float dollar figure cannot represent it without disagreeing with the ledger. ## Errors Every error carries a stable `code` and a `request_id`. Match on `code`; the `message` is for humans and may change. contact: name: Wixzel Voice url: https://voice.wixzel.com servers: - url: https://api.voice.wixzel.com description: Production security: [] tags: - name: Calls description: Place calls and read what happened on them. - name: Realtime description: Talk to an agent from a browser or app, with no phone line. - name: Agents description: >- The prompt, voice and behaviour of a caller, and its mascot: the animated face people see on your share link, your website and in your apps. - name: Leads description: People to call, and data to merge into prompts. - name: Campaigns description: Call a list of leads with one agent. - name: Knowledge bases description: Facts an agent can draw on mid-call. - name: Phone numbers description: Numbers on your SIP trunks. - name: SIP trunks description: Your carrier connections. - name: Appointments description: Bookings, including ones agents make on calls. - name: Usage description: Itemised billing lines. - name: Billing description: Balance, ledger and top-ups. - name: API keys description: Create, scope and rotate keys. - name: Engines description: What the platform can serve, and what it costs. - name: Voices description: Cloned voices, made from your own recordings, for your agents to speak in. - name: Callers description: Who called your agents, where from and on what, and the blocklist. - name: Webhooks description: Where events are sent, and what happened when they got there. - name: MCP servers description: Other apps’ tools, for agents to use while they are on a call. - name: Tools description: >- Your own tools, for agents to use while they are on a call: a webhook to your server, or an action in the caller’s app. - name: WhatsApp description: >- WhatsApp business numbers, the agents that answer their chats, and messages agents send. - name: Meetings description: >- Agents in Zoom, Google Meet and Teams meetings, through your own Attendee account. paths: /v1/agents/{id}/mascot/rotate-public-id: post: tags: - Agents summary: Change a mascot's share id description: >- Gives the agent's mascot a new `public_id`. Its old share link and embed code stop working at once. Requires `agents:write` and `calls:write`. parameters: - schema: type: string pattern: ^[0-9a-f]{24}$ example: 6a96a3ead6e886d42462dd3e required: true name: id in: path responses: '200': description: The agent, its mascot with a new id content: application/json: schema: $ref: '#/components/schemas/Agent' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Key lacks the required scope content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: No such record content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Rate limited. Retry after the interval in `Retry-After`. content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearerAuth: [] components: schemas: Agent: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ example: 6a96a3ead6e886d42462dd3e object: type: string enum: - agent name: type: string system_prompt: type: string opening_message: type: - string - 'null' voice: $ref: '#/components/schemas/VoiceConfig' language: type: string knowledge_base_id: type: - string - 'null' pattern: ^[0-9a-f]{24}$ example: 6a96a3ead6e886d42462dd3e outbound_phone_number_id: type: - string - 'null' pattern: ^[0-9a-f]{24}$ example: 6a96a3ead6e886d42462dd3e appointment_booking_enabled: type: boolean human_transfer: $ref: '#/components/schemas/HumanTransfer' mcp_server_ids: type: array items: type: string pattern: ^[0-9a-f]{24}$ example: 6a96a3ead6e886d42462dd3e description: MCP servers whose enabled tools this agent can use during a call. tool_ids: type: array items: type: string pattern: ^[0-9a-f]{24}$ example: 6a96a3ead6e886d42462dd3e description: >- Your own tools (webhook and client) this agent can use during a call. mascot: $ref: '#/components/schemas/AgentMascot' whatsapp: $ref: '#/components/schemas/AgentWhatsApp' created_at: type: string format: date-time description: ISO 8601, always UTC. example: '2026-09-01T12:00:00.000Z' required: - id - object - name - system_prompt - opening_message - voice - language - knowledge_base_id - outbound_phone_number_id - appointment_booking_enabled - human_transfer - mcp_server_ids - tool_ids - mascot - whatsapp - created_at Error: type: object properties: error: type: object properties: type: type: string enum: - invalid_request_error - authentication_error - permission_error - rate_limit_error - insufficient_credits - not_found_error - conflict_error - api_error code: type: string description: Stable machine-readable code. example: agent_not_found message: type: string description: >- Human-readable explanation. Do not match on this — match on code. param: type: string description: Which field caused the failure, when applicable. doc_url: type: string request_id: type: string description: Quote this when asking for help. example: req_01HXYZ... required: - type - code - message - request_id required: - error VoiceConfig: type: - object - 'null' properties: stt: $ref: '#/components/schemas/SttConfig' llm: $ref: '#/components/schemas/LlmConfig' tts: $ref: '#/components/schemas/TtsConfig' realtime: $ref: '#/components/schemas/RealtimeConfig' turn_taking: $ref: '#/components/schemas/TurnTaking' description: >- Either a composed pipeline (stt + llm + tts) or a single realtime model. Not both. HumanTransfer: type: object properties: enabled: type: boolean default: false mode: type: string enum: - blind default: blind description: >- The caller is handed straight over. Attended transfer, where the agent speaks to the human first, is not built yet. default_destination_id: type: - string - 'null' description: >- Used when the caller asks for "a person" without naming one. Must be an enabled destination. ring_timeout_seconds: type: integer minimum: 5 maximum: 60 default: 20 description: >- How long a destination may ring before the caller is handed back to the agent. max_transfers_per_call: type: integer minimum: 1 maximum: 10 default: 3 description: Stops a loop where the agent keeps re-dialling an unreachable human. return_to_agent_on_failure: type: boolean default: true destinations: type: array items: $ref: '#/components/schemas/HumanTransferDestination' maxItems: 50 description: Replaced as a whole on update, so send the complete list every time. required: - destinations description: >- Hand a live caller to a person. Replaced as a whole on update, never merged. AgentMascot: type: object properties: spec: $ref: '#/components/schemas/MascotSpec' welcome_message: type: - string - 'null' description: >- Shown in its speech bubble on the share page and the website widget before a call. Null uses the agent’s opening line. example: Hi! I’m Molly from Smile Dental. Tap Call to talk to me. status: type: string enum: - ready - building - failed description: >- `building` while a generation runs; poll the agent until it is `ready` or `failed`. A failed build leaves the agent working, with the look it had. status_detail: type: - string - 'null' enum: - reading_website - designing - writing_knowledge - saving description: 'While building: the step it is on.' error: $ref: '#/components/schemas/MascotError' source: $ref: '#/components/schemas/MascotSource' brand: type: object properties: primary_color: type: - string - 'null' site_name: type: - string - 'null' required: - primary_color - site_name description: What was read off the website, when it was made from one. public_id: type: - string - 'null' description: >- The id in its share link and embed code. Null until sharing is first turned on. example: m_4fT9qLx2Bv8K sharing: $ref: '#/components/schemas/MascotSharing' updated_at: type: string format: date-time description: ISO 8601, always UTC. example: '2026-09-01T12:00:00.000Z' required: - spec - welcome_message - status - status_detail - error - source - brand - public_id - sharing - updated_at description: >- The agent’s animated face, for the share link, the website widget and your own apps. Every agent has one. AgentWhatsApp: type: object properties: account_id: type: - string - 'null' pattern: ^[0-9a-f]{24}$ description: >- The WhatsApp number this agent sends from during phone calls. In a WhatsApp chat it always replies from the number the chat is on. example: 6a96a3ead6e886d42462dd3e tools: type: object properties: messages: type: boolean description: >- Send the caller free text on WhatsApp, inside their 24-hour window. templates: type: boolean description: >- Send approved templates from `allowed_templates` and the purpose templates. media: type: boolean description: >- Send knowledge-base files whose original was kept: brochures, photos, videos. schedule: type: boolean description: Schedule a reminder or follow-up template for later. interactive: type: boolean description: Offer reply buttons and lists, in a WhatsApp chat. required: - messages - templates - media - schedule - interactive templates: type: object properties: follow_up: type: - object - 'null' properties: name: type: string minLength: 1 maxLength: 512 language: type: - string - 'null' maxLength: 20 required: - name reminder: type: - object - 'null' properties: name: type: string minLength: 1 maxLength: 512 language: type: - string - 'null' maxLength: 20 required: - name booking_confirmation: type: - object - 'null' properties: name: type: string minLength: 1 maxLength: 512 language: type: - string - 'null' maxLength: 20 required: - name required: - follow_up - reminder - booking_confirmation description: The template used for each purpose. allowed_templates: type: array items: type: string maxLength: 512 maxItems: 20 description: >- Template names the agent may send by its own choice, besides the purpose templates. auto_booking_confirmation: type: boolean description: >- Send `booking_confirmation` as soon as the agent books an appointment. auto_reminder_minutes: type: integer minimum: 0 maximum: 10080 description: >- Send `reminder` this many minutes before each appointment the agent books. 0 is off. chat_model: type: - string - 'null' maxLength: 200 description: >- The text model for WhatsApp chats. Null uses the agent’s own model on the classic engine, or the default. example: openrouter/openai/gpt-4o-mini max_sends_per_call: type: integer minimum: 1 maximum: 10 description: >- The most WhatsApp messages one call or chat turn may send through tools. allow_marketing: type: boolean description: Whether the agent may send marketing-category templates. required: - account_id - tools - templates - allowed_templates - auto_booking_confirmation - auto_reminder_minutes - chat_model - max_sends_per_call - allow_marketing description: 'WhatsApp: the number it sends from on calls, and its WhatsApp tools.' SttConfig: type: object properties: model: type: string pattern: ^[a-z0-9_-]+\/[a-zA-Z0-9._-]+(?:\/[a-zA-Z0-9._-]+)*$ example: deepgram/nova-3 language: type: string default: en-US description: BCP-47 tag, or "multi" for automatic detection. endpointing_ms: type: integer minimum: 100 maximum: 2000 description: >- Silence before a turn is considered finished, in milliseconds. Lower is snappier and more prone to cutting people off. Default 300. required: - model LlmConfig: type: object properties: model: type: string pattern: ^[a-z0-9_-]+\/[a-zA-Z0-9._-]+(?:\/[a-zA-Z0-9._-]+)*$ example: openrouter/gpt-4o-mini temperature: type: number minimum: 0 maximum: 2 max_tokens: type: integer minimum: 1 maximum: 4096 description: >- Caps reply length. Long replies cost the caller waiting time as well as money. required: - model TtsConfig: type: object properties: model: type: string pattern: ^[a-z0-9_-]+\/[a-zA-Z0-9._-]+(?:\/[a-zA-Z0-9._-]+)*$ example: elevenlabs/eleven_flash_v2_5 voice: type: string example: 21m00Tcm4TlvDq8ikWAM stability: type: number minimum: 0 maximum: 1 description: >- Higher is more consistent and flatter; lower is more expressive and more variable. ElevenLabs only. similarity_boost: type: number minimum: 0 maximum: 1 description: >- How closely the output tracks the original voice recording. ElevenLabs only. speed: type: number minimum: 0.7 maximum: 1.2 description: Speaking rate, 1 being the voice's natural pace. ElevenLabs only. required: - model RealtimeConfig: type: object properties: model: type: string pattern: ^[a-z0-9_-]+\/[a-zA-Z0-9._-]+(?:\/[a-zA-Z0-9._-]+)*$ example: google/gemini-live voice: type: string example: Charon language: type: string default: auto required: - model TurnTaking: type: object properties: interrupt_sensitivity: type: string enum: - low - normal - high default: normal description: How readily the agent stops talking when the caller speaks. silence_wait_ms: type: integer minimum: 200 maximum: 3000 description: >- Extra silence tolerated after an utterance that sounded unfinished, in milliseconds. Default 500. HumanTransferDestination: type: object properties: id: type: string pattern: ^[a-z0-9][a-z0-9_-]{0,63}$ description: >- Your own id for this destination. This, and `name`, are all the model is ever told. example: billing name: type: string minLength: 1 maxLength: 100 description: >- What the agent calls this destination when it offers or announces a transfer. example: Billing team type: type: string enum: - phone default: phone description: Only `phone` today. Warm transfer to another agent is not built. phone_number: type: string pattern: ^\+[1-9]\d{6,14}$ description: Dialled server-side. Never sent to the model. example: '+14155550100' enabled: type: boolean default: true ring_timeout_seconds: type: - integer - 'null' minimum: 5 maximum: 60 description: >- Overrides the transfer-wide timeout for this destination. Null inherits it. required: - id - name - phone_number MascotSpec: type: object properties: format: type: string enum: - wixzel.mascot version: type: number enum: - 1 name: type: string color: type: string example: '#1388ff' shape: $ref: '#/components/schemas/MascotShape' eyes: $ref: '#/components/schemas/MascotEyes' mouth: $ref: '#/components/schemas/MascotMouth' personality: type: object properties: bounce: type: number energy: type: number required: - bounce - energy required: - format - version - name - color - shape - eyes - mouth - personality description: >- The whole mascot. Draw it with the mascot runtime, or port the renderer: it is one shape and two eyes. MascotError: type: - object - 'null' properties: code: type: string message: type: string required: - code - message description: Why the last build failed. MascotSource: type: object properties: type: type: string enum: - manual - description - website - surprise description: >- How the mascot was first made. Editing it later does not change this. description: type: - string - 'null' url: type: - string - 'null' required: - type - description - url MascotSharing: type: object properties: link: type: boolean description: >- Anyone with the share link can see the mascot and call it. Calls are billed to you. embed: type: boolean description: >- The website widget works, on the domains in `embed_origins` only. Calls are billed to you. embed_origins: type: array items: type: string description: Sites allowed to embed the mascot, as origins. example: - https://example.com - https://www.example.com max_call_seconds: type: integer description: Longest public call. example: 300 daily_minutes: type: integer description: >- Public call minutes per day across everyone, after which calls are refused until midnight UTC. example: 60 calls_per_visitor_daily: type: integer description: Public calls one visitor (by IP address) may make per day. example: 3 max_concurrent_calls: type: integer description: >- Public calls at once, so a busy page cannot take every call slot your account has. example: 2 caller_info: type: string enum: - none - contact - google description: >- What a caller must give before a call through the share link or website widget: `none`, `contact` (a name and a phone number or email), or `google` (a Google sign-in, which identifies them to you and never creates a Wixzel account). Callers from the app are already signed in. required: - link - embed - embed_origins - max_call_seconds - daily_minutes - calls_per_visitor_daily - max_concurrent_calls - caller_info MascotShape: type: object properties: kind: type: string enum: - circle - drop - triangle - cloud - pill - flower - squircle - blob - heart - custom description: >- The body. `blob` is a random soft blob picked by `seed`; `custom` is your own outline in `points`. example: drop rotation: type: number description: >- Degrees, + clockwise. Clamped to −45…45. A few degrees of tilt makes it feel alive. example: -8 aspect: type: number description: Width relative to height. Clamped to 0.6…1.6. example: 1 seed: type: number description: '`blob` only: which blob.' example: 7 points: type: array items: type: number maxItems: 2000 description: >- `custom` only: a closed outline as x,y pairs in −1…1 (at least three points). required: - kind MascotEyes: type: object properties: style: type: string enum: - pill - round - block - line description: >- `pill` tall capsules, `round` dots, `block` big rounded rectangles, `line` sleepy dashes. example: pill color: type: string example: '#ffffff' width: type: number description: One eye, in body units (the body is 2 units tall). 0.05…0.6. example: 0.2 height: type: number description: 0.05…0.8. example: 0.42 gap: type: number description: Centre to centre. 0.1…1.2. example: 0.42 x: type: number description: Where the pair sits, from the body’s centre. −0.6…0.6. example: 0 'y': type: number description: Negative is up. −0.7…0.6. example: -0.12 tilt: type: number description: Degrees both eyes lean. −60…60. example: 0 turn: type: number description: >- Shrinks one eye so the face looks turned (+ shrinks the right). −0.6…0.6. example: 0 required: - style - color - width - height - gap - x - 'y' - tilt MascotMouth: type: object properties: style: type: string enum: - smile width: type: number description: Worked out from the eye width. 'y': type: number description: Below the body’s centre, worked out from the eyes. required: - style - width - 'y' description: >- Always a smile under the eyes, set by the server. It opens and closes with the voice. securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your Wixzel Voice API key: `Authorization: Bearer wv_live_...`. Keys are scoped; grant only what the integration needs. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.