Agents

An agent bundles a system prompt, greeting, voice, and call-handling behavior. Every number and call belongs to an agent. JavaScript examples call https://api.agentline.cloud with fetch and a Bearer al_live_... key. The Node package is not on npm.

Create an agent

agent = client.agents.create(
    name="Support Bot",
    system_prompt="You are a helpful assistant. Be concise.",
    initial_greeting="Hi, this is Support. How can I help?",
    voice_id="female-1",
    voicemail_message="Hi, this is Support calling about your request. Please call us back at 555-0100.",
)

const agent = await fetch("https://api.agentline.cloud/v1/agents", {
  method: "POST",
  headers: {
    Authorization: "Bearer al_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Support Bot",
    system_prompt: "You are a helpful assistant. Be concise.",
    initial_greeting: "Hi, this is Support. How can I help?",
    voice_id: "female-1",
    voicemail_message: "Hi, this is Support calling about your request. Please call us back at 555-0100.",
  }),
}).then((res) => res.json());

Field	Purpose
`name`	Display name
`system_prompt`	Default instructions for all calls
`initial_greeting`	Opening line spoken when a call connects
`voice_id`	Voice support depends on the number service. Presets and custom UUIDs need a configured mapping where required; omit the field to use the service default. Presets: `female-1` (friendly), `female-2` (reassuring), `female-3` (guide), `male-1` (supportive), `male-2` (thinker), `male-3` (helpful)
`transfer_number`	Must be the owner’s phone. A different number is rejected. Live transfers dial only `owner_phone`.
`voicemail_message`	Spoken message left on outbound voicemail. Required if the agent should leave a mailbox message; without it the agent hangs up.
`owner_phone`	Owner number in E.164. Calls from it enter task mode, and it is the only live-call transfer destination. Setting it also sets `transfer_number`.

Leaving voicemail

On outbound calls the pipeline detects a mailbox and leaves voicemail_message:

Greeting — “You’ve reached…”, “12418174 is not available”, “leave a message after the beep”. The agent does not press keys. It waits for the beep, speaks the message, and hangs up.
Record-key menu — “To disconnect, press 1. To record your message, press 2.” The agent presses 2, waits for the beep, then leaves the same message. If voicemail_message is unset it presses disconnect instead.

Include who you are, why you’re calling, and a callback number. Do not add “stay silent on automated messages” or “hang up if you hear press 1” to the system prompt — that fights the built-in handler.

client.agents.update(
    agent.id,
    voicemail_message="Hi, this is Alex calling about the apartment. Please call me back at 555-0100.",
)

await fetch(`https://api.agentline.cloud/v1/agents/${agent.id}`, {
  method: "PATCH",
  headers: {
    Authorization: "Bearer al_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    voicemail_message: "Hi, this is Alex calling about the apartment. Please call me back at 555-0100.",
  }),
});

Manage agents

client.agents.list()
client.agents.get(agent.id)
client.agents.update(agent.id, voice_id="male-1")
client.agents.delete(agent.id)

const headers = { Authorization: "Bearer al_live_..." };

await fetch("https://api.agentline.cloud/v1/agents", { headers });
await fetch(`https://api.agentline.cloud/v1/agents/${agent.id}`, { headers });
await fetch(`https://api.agentline.cloud/v1/agents/${agent.id}`, {
  method: "PATCH",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ voice_id: "male-1" }),
});
await fetch(`https://api.agentline.cloud/v1/agents/${agent.id}`, {
  method: "DELETE",
  headers,
});

Per-call overrides: when making a call you can pass system_prompt, initial_greeting, and voice_id to override the agent defaults for that single call.

See the Create Agent endpoint in the API Reference.