Skip to main content

​
How creating an agent works

The three create tools start a build and answer at once with a build_id. The build reads the business’s website (if given), writes the agent’s instructions and greeting, and creates the agent. It takes a minute or two. The AI app then calls get_agent_build_status every few seconds until the agent is ready or the build failed. Every create needs:
  • business_name, and
  • either website or a 2–3 sentence description of the business.
Everything else is optional. The AI app asks once for the optional details and skips what you don’t know.
A build follows the same rules as the agent builder in the VoiceAIWrapper app: your plan, your credits and the daily build limit. Voices are chosen in the VoiceAIWrapper app.

​
create_inbound_receptionist

Create an AI receptionist that answers phone calls for a business. It greets callers, answers questions about the business and handles the jobs you choose, such as taking a message or collecting caller details. Scope: agents.write · Hints: open world

​
Inputs

​
string
required
The business’s name.
​
string
The business’s own website, for example lakesidedental.com. Required unless you give description.
​
string
2–3 sentences on what the business does. Required without a website.
​
string
For example Healthcare & Medical or Home services.
​
string
For example Mon-Fri 8am-5pm.
​
string[]
What it does on a call, for example answer questions, take messages, collect details.
​
string[]
Details to collect from callers, for example name, reason for calling.
​
string[]
Things the agent must never say.
​
string
The language it speaks, by name or code, for example English or es.
​
string
The agent’s name. A default is used if you skip it.
​
string
For example friendly, calm, professional.
​
string
Your own id for this request, up to 128 characters. Repeat it on retries so the agent is never built twice. See Repeating a request safely.

​
Returns

​
string
Pass it to get_agent_build_status.
​
string
Always building.
Example

​
create_outbound_agent

Create an AI agent that places phone calls for a business, for example to follow up on leads or confirm appointments. The person called speaks first. Calls are started from a campaign in the VoiceAIWrapper app. The agent has no calling number of its own: the campaign picks the number it calls from. Scope: agents.write · Hints: open world

​
Inputs

Takes everything create_inbound_receptionist takes, plus:
​
string
required
What the calls are for, for example remind patients of check-ups.
​
string
Who it calls, for example new leads.
​
string
What counts as a successful call, for example appointment booked.
For an outbound agent, jobs means anything else it does on a call, and collect means details to find out on the call.

​
Returns

Same as create_inbound_receptionist: a build_id and status: "building".

​
create_website_chatbot

Create an AI chatbot for a website: an agent that talks with visitors by chat or voice and answers questions about the business, plus the web widget that puts it on the site. When the build is ready, get_agent_build_status returns the embed code. To add a widget to an agent that already exists, use create_web_widget instead. Scope: agents.write · Hints: open world

​
Inputs

Same as create_inbound_receptionist. Here jobs and collect refer to conversations with site visitors.

​
Returns

Same as create_inbound_receptionist: a build_id and status: "building".

​
list_agents

List the organization’s agents, newest first. Scope: agents.read · Hints: read-only

​
Inputs

None.

​
Returns

​
object[]
Example

​
get_agent

Show one agent: name, type, greeting, language, the start of its instructions, its phone number and its widget embed code. Scope: agents.read · Hints: read-only

​
Inputs

​
string
required
The agent_id from list_agents.

​
Returns

Everything list_agents returns for the agent, plus:
​
string
What it says first. Empty for none.
​
string
For example English, or Auto-detect.
​
string
The first 300 or so characters of its instructions.
​
string | null
The connected number, if any.
​
string | null
The widget’s embed code, if it has a widget.

​
update_agent

Change an agent’s name, greeting, instructions or language. Give only what changes. The same checks as the VoiceAIWrapper app apply. The change applies to the live agent straight away, and there is no undo from the chat, so the AI app asks you to confirm first. Voices are changed in the VoiceAIWrapper app. Scope: agents.write · Hints: destructive

​
Inputs

​
string
required
The agent_id from list_agents.
​
string
The new name. Can’t be empty.
​
string
What it says first. Send an empty string for no greeting.
​
string
Its full new instructions. This replaces the old instructions entirely.
​
string
By name or code, for example English, Spanish, es, or auto to detect the caller’s language.
At least one of name, greeting, instructions or language is required.

​
Returns

​
string
​
string
​
string[]
What changed: any of name, greeting, instructions, language. Empty if the agent already had those settings.
​
string
The agent’s page in the VoiceAIWrapper app.