Agents

Generate an agent

Makes an agent from a website_url (its pages become the agent’s knowledge base, its colour and tone the mascot), a description, or both, and the role it plays. Answers at once with the agent, whose mascot.status is building; it can already talk, with a generic prompt. Poll GET /v1/agents/{id} until the mascot is ready (its name, prompt, opening line, language and knowledge base are written then) or failed (the agent stays as it was, with the default mascot), usually under a minute. Not charged. One build at a time per account, and builds from a website or description are limited (5, then one a minute). Requires agents:write and knowledge_bases:write.

POST

agents

generate

Generate an agent

curl --request POST \
  --url https://api.voice.wixzel.com/v1/agents/generate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "website_url": "https://example.com",
  "description": "A calm, friendly receptionist for a dental clinic in Kochi. Teal.",
  "name": "<string>",
  "role": "receptionist"
}
'

import requests

url = "https://api.voice.wixzel.com/v1/agents/generate"

payload = {
    "website_url": "https://example.com",
    "description": "A calm, friendly receptionist for a dental clinic in Kochi. Teal.",
    "name": "<string>",
    "role": "receptionist"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    website_url: 'https://example.com',
    description: 'A calm, friendly receptionist for a dental clinic in Kochi. Teal.',
    name: '<string>',
    role: 'receptionist'
  })
};

fetch('https://api.voice.wixzel.com/v1/agents/generate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.voice.wixzel.com/v1/agents/generate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'website_url' => 'https://example.com',
    'description' => 'A calm, friendly receptionist for a dental clinic in Kochi. Teal.',
    'name' => '<string>',
    'role' => 'receptionist'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.voice.wixzel.com/v1/agents/generate"

	payload := strings.NewReader("{\n  \"website_url\": \"https://example.com\",\n  \"description\": \"A calm, friendly receptionist for a dental clinic in Kochi. Teal.\",\n  \"name\": \"<string>\",\n  \"role\": \"receptionist\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.voice.wixzel.com/v1/agents/generate")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"website_url\": \"https://example.com\",\n  \"description\": \"A calm, friendly receptionist for a dental clinic in Kochi. Teal.\",\n  \"name\": \"<string>\",\n  \"role\": \"receptionist\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.voice.wixzel.com/v1/agents/generate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"website_url\": \"https://example.com\",\n  \"description\": \"A calm, friendly receptionist for a dental clinic in Kochi. Teal.\",\n  \"name\": \"<string>\",\n  \"role\": \"receptionist\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "6a96a3ead6e886d42462dd3e",
  "object": "agent",
  "name": "<string>",
  "system_prompt": "<string>",
  "opening_message": "<string>",
  "voice": {
    "stt": {
      "model": "deepgram/nova-3",
      "language": "en-US",
      "endpointing_ms": 1050
    },
    "llm": {
      "model": "openrouter/gpt-4o-mini",
      "temperature": 1,
      "max_tokens": 2048
    },
    "tts": {
      "model": "elevenlabs/eleven_flash_v2_5",
      "voice": "21m00Tcm4TlvDq8ikWAM",
      "stability": 0.5,
      "similarity_boost": 0.5,
      "speed": 0.95
    },
    "realtime": {
      "model": "google/gemini-live",
      "voice": "Charon",
      "language": "auto"
    },
    "turn_taking": {
      "interrupt_sensitivity": "normal",
      "silence_wait_ms": 1600
    }
  },
  "language": "<string>",
  "knowledge_base_id": "6a96a3ead6e886d42462dd3e",
  "outbound_phone_number_id": "6a96a3ead6e886d42462dd3e",
  "appointment_booking_enabled": true,
  "human_transfer": {
    "destinations": [
      {
        "id": "billing",
        "name": "Billing team",
        "phone_number": "+14155550100",
        "type": "phone",
        "enabled": true,
        "ring_timeout_seconds": 32
      }
    ],
    "enabled": false,
    "mode": "blind",
    "default_destination_id": "<string>",
    "ring_timeout_seconds": 20,
    "max_transfers_per_call": 3,
    "return_to_agent_on_failure": true
  },
  "mcp_server_ids": [
    "6a96a3ead6e886d42462dd3e"
  ],
  "tool_ids": [
    "6a96a3ead6e886d42462dd3e"
  ],
  "mascot": {
    "spec": {
      "format": "wixzel.mascot",
      "version": 1,
      "name": "<string>",
      "color": "#1388ff",
      "shape": {
        "kind": "drop",
        "rotation": -8,
        "aspect": 1,
        "seed": 7,
        "points": [
          123
        ]
      },
      "eyes": {
        "style": "pill",
        "color": "#ffffff",
        "width": 0.2,
        "height": 0.42,
        "gap": 0.42,
        "x": 0,
        "y": -0.12,
        "tilt": 0,
        "turn": 0
      },
      "mouth": {
        "style": "smile",
        "width": 123,
        "y": 123
      },
      "personality": {
        "bounce": 123,
        "energy": 123
      }
    },
    "welcome_message": "Hi! I’m Molly from Smile Dental. Tap Call to talk to me.",
    "status": "ready",
    "status_detail": "reading_website",
    "error": {
      "code": "<string>",
      "message": "<string>"
    },
    "source": {
      "type": "manual",
      "description": "<string>",
      "url": "<string>"
    },
    "brand": {
      "primary_color": "<string>",
      "site_name": "<string>"
    },
    "public_id": "m_4fT9qLx2Bv8K",
    "sharing": {
      "link": true,
      "embed": true,
      "embed_origins": [
        "https://example.com",
        "https://www.example.com"
      ],
      "max_call_seconds": 300,
      "daily_minutes": 60,
      "calls_per_visitor_daily": 3,
      "max_concurrent_calls": 2,
      "caller_info": "none"
    },
    "updated_at": "2026-09-01T12:00:00.000Z"
  },
  "whatsapp": {
    "account_id": "6a96a3ead6e886d42462dd3e",
    "tools": {
      "messages": true,
      "templates": true,
      "media": true,
      "schedule": true,
      "interactive": true
    },
    "templates": {
      "follow_up": {
        "name": "<string>",
        "language": "<string>"
      },
      "reminder": {
        "name": "<string>",
        "language": "<string>"
      },
      "booking_confirmation": {
        "name": "<string>",
        "language": "<string>"
      }
    },
    "allowed_templates": [
      "<string>"
    ],
    "auto_booking_confirmation": true,
    "auto_reminder_minutes": 5040,
    "chat_model": "openrouter/openai/gpt-4o-mini",
    "max_sends_per_call": 5,
    "allow_marketing": true
  },
  "created_at": "2026-09-01T12:00:00.000Z"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Your Wixzel Voice API key: Authorization: Bearer wv_live_.... Keys are scoped; grant only what the integration needs.

Body

application/json

Make an agent from a website_url (its content becomes the agent’s knowledge base, its colour and tone the mascot), a description, or both. The agent comes back at once with mascot.status: building and a generic prompt it can already talk with; poll it until the mascot is ready.

website_url

string<uri>

A website to take the business’s name, colour, tone and facts from. Read once, not stored.

Maximum string length: 2048

Example:

"https://example.com"

description

string

The business and how it should come across: the brand, its tone, a colour.

Required string length: 1 - 1000

Example:

"A calm, friendly receptionist for a dental clinic in Kochi. Teal."

name

string

What the agent calls itself. Without it, the generator picks a name.

Required string length: 1 - 40

role

string

receptionist, support, sales, guide, or your own words. Shapes what the agent does.

Required string length: 1 - 120

Example:

"receptionist"

Response

The new agent, its mascot building

string

required

Pattern: ^[0-9a-f]{24}$

Example:

"6a96a3ead6e886d42462dd3e"

object

enum<string>

required

Available options:

agent

name

string

required

system_prompt

string

required

opening_message

string | null

required

voice

object | null

required

Either a composed pipeline (stt + llm + tts) or a single realtime model. Not both.

Show child attributes

language

string

required

knowledge_base_id

string | null

required

Pattern: ^[0-9a-f]{24}$

Example:

"6a96a3ead6e886d42462dd3e"

outbound_phone_number_id

string | null

required

Pattern: ^[0-9a-f]{24}$

Example:

"6a96a3ead6e886d42462dd3e"

appointment_booking_enabled

boolean

required

human_transfer

object

required

Hand a live caller to a person. Replaced as a whole on update, never merged.

Show child attributes

mcp_server_ids

string[]

required

MCP servers whose enabled tools this agent can use during a call.

Pattern: ^[0-9a-f]{24}$

tool_ids

string[]

required

Your own tools (webhook and client) this agent can use during a call.

Pattern: ^[0-9a-f]{24}$

mascot

object

required

The agent’s animated face, for the share link, the website widget and your own apps. Every agent has one.

Show child attributes

object

required

WhatsApp: the number it sends from on calls, and its WhatsApp tools.

Show child attributes

created_at

string<date-time>

required

ISO 8601, always UTC.

Example:

"2026-09-01T12:00:00.000Z"

Generate an agent

curl --request POST \
  --url https://api.voice.wixzel.com/v1/agents/generate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "website_url": "https://example.com",
  "description": "A calm, friendly receptionist for a dental clinic in Kochi. Teal.",
  "name": "<string>",
  "role": "receptionist"
}
'

import requests

url = "https://api.voice.wixzel.com/v1/agents/generate"

payload = {
    "website_url": "https://example.com",
    "description": "A calm, friendly receptionist for a dental clinic in Kochi. Teal.",
    "name": "<string>",
    "role": "receptionist"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    website_url: 'https://example.com',
    description: 'A calm, friendly receptionist for a dental clinic in Kochi. Teal.',
    name: '<string>',
    role: 'receptionist'
  })
};

fetch('https://api.voice.wixzel.com/v1/agents/generate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.voice.wixzel.com/v1/agents/generate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'website_url' => 'https://example.com',
    'description' => 'A calm, friendly receptionist for a dental clinic in Kochi. Teal.',
    'name' => '<string>',
    'role' => 'receptionist'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.voice.wixzel.com/v1/agents/generate"

	payload := strings.NewReader("{\n  \"website_url\": \"https://example.com\",\n  \"description\": \"A calm, friendly receptionist for a dental clinic in Kochi. Teal.\",\n  \"name\": \"<string>\",\n  \"role\": \"receptionist\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.voice.wixzel.com/v1/agents/generate")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"website_url\": \"https://example.com\",\n  \"description\": \"A calm, friendly receptionist for a dental clinic in Kochi. Teal.\",\n  \"name\": \"<string>\",\n  \"role\": \"receptionist\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.voice.wixzel.com/v1/agents/generate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"website_url\": \"https://example.com\",\n  \"description\": \"A calm, friendly receptionist for a dental clinic in Kochi. Teal.\",\n  \"name\": \"<string>\",\n  \"role\": \"receptionist\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "6a96a3ead6e886d42462dd3e",
  "object": "agent",
  "name": "<string>",
  "system_prompt": "<string>",
  "opening_message": "<string>",
  "voice": {
    "stt": {
      "model": "deepgram/nova-3",
      "language": "en-US",
      "endpointing_ms": 1050
    },
    "llm": {
      "model": "openrouter/gpt-4o-mini",
      "temperature": 1,
      "max_tokens": 2048
    },
    "tts": {
      "model": "elevenlabs/eleven_flash_v2_5",
      "voice": "21m00Tcm4TlvDq8ikWAM",
      "stability": 0.5,
      "similarity_boost": 0.5,
      "speed": 0.95
    },
    "realtime": {
      "model": "google/gemini-live",
      "voice": "Charon",
      "language": "auto"
    },
    "turn_taking": {
      "interrupt_sensitivity": "normal",
      "silence_wait_ms": 1600
    }
  },
  "language": "<string>",
  "knowledge_base_id": "6a96a3ead6e886d42462dd3e",
  "outbound_phone_number_id": "6a96a3ead6e886d42462dd3e",
  "appointment_booking_enabled": true,
  "human_transfer": {
    "destinations": [
      {
        "id": "billing",
        "name": "Billing team",
        "phone_number": "+14155550100",
        "type": "phone",
        "enabled": true,
        "ring_timeout_seconds": 32
      }
    ],
    "enabled": false,
    "mode": "blind",
    "default_destination_id": "<string>",
    "ring_timeout_seconds": 20,
    "max_transfers_per_call": 3,
    "return_to_agent_on_failure": true
  },
  "mcp_server_ids": [
    "6a96a3ead6e886d42462dd3e"
  ],
  "tool_ids": [
    "6a96a3ead6e886d42462dd3e"
  ],
  "mascot": {
    "spec": {
      "format": "wixzel.mascot",
      "version": 1,
      "name": "<string>",
      "color": "#1388ff",
      "shape": {
        "kind": "drop",
        "rotation": -8,
        "aspect": 1,
        "seed": 7,
        "points": [
          123
        ]
      },
      "eyes": {
        "style": "pill",
        "color": "#ffffff",
        "width": 0.2,
        "height": 0.42,
        "gap": 0.42,
        "x": 0,
        "y": -0.12,
        "tilt": 0,
        "turn": 0
      },
      "mouth": {
        "style": "smile",
        "width": 123,
        "y": 123
      },
      "personality": {
        "bounce": 123,
        "energy": 123
      }
    },
    "welcome_message": "Hi! I’m Molly from Smile Dental. Tap Call to talk to me.",
    "status": "ready",
    "status_detail": "reading_website",
    "error": {
      "code": "<string>",
      "message": "<string>"
    },
    "source": {
      "type": "manual",
      "description": "<string>",
      "url": "<string>"
    },
    "brand": {
      "primary_color": "<string>",
      "site_name": "<string>"
    },
    "public_id": "m_4fT9qLx2Bv8K",
    "sharing": {
      "link": true,
      "embed": true,
      "embed_origins": [
        "https://example.com",
        "https://www.example.com"
      ],
      "max_call_seconds": 300,
      "daily_minutes": 60,
      "calls_per_visitor_daily": 3,
      "max_concurrent_calls": 2,
      "caller_info": "none"
    },
    "updated_at": "2026-09-01T12:00:00.000Z"
  },
  "whatsapp": {
    "account_id": "6a96a3ead6e886d42462dd3e",
    "tools": {
      "messages": true,
      "templates": true,
      "media": true,
      "schedule": true,
      "interactive": true
    },
    "templates": {
      "follow_up": {
        "name": "<string>",
        "language": "<string>"
      },
      "reminder": {
        "name": "<string>",
        "language": "<string>"
      },
      "booking_confirmation": {
        "name": "<string>",
        "language": "<string>"
      }
    },
    "allowed_templates": [
      "<string>"
    ],
    "auto_booking_confirmation": true,
    "auto_reminder_minutes": 5040,
    "chat_model": "openrouter/openai/gpt-4o-mini",
    "max_sends_per_call": 5,
    "allow_marketing": true
  },
  "created_at": "2026-09-01T12:00:00.000Z"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

Getting started

Guides

Carriers

Concepts

API reference

Generate an agent

Authorizations

Body

Response