Skip to main content
An agent is the configurable AI personality behind a phone call. One agent owns:
  • A system prompt (what the AI says, how it behaves)
  • A voice ID
  • A language
  • Behaviour settings (response length, interruption sensitivity, silence handling)
  • Action configuration (transfer numbers, SMS templates)
  • An optional webhook URL for post-call data
One agent can be attached to many phone numbers. This is the multi-tenant pattern: one “dental receptionist” agent can serve hundreds of clinics, each with their own Twilio number.

​
Architecture

Agent (template/personality)
  ├── Phone Number A → Clinic 1
  ├── Phone Number B → Clinic 2
  └── Phone Number C → Clinic 3
The engine identifies which clinic is calling by the phone number that was dialled, not by which agent. The agent prompt stays the same; the per-customer context comes from the phone number record and any history Nixflex finds.
Agent-level settings are shared by every number on the agent. Fields like voice_id, post_call_sms_template, and transfer_number set on the agent apply to all phone numbers using it. If one agent serves many separate businesses, do not rely on agent-level settings for per-business behaviour - they would apply the same voice, SMS, or transfer to every business at once.For per-business behaviour, set values per phone number where supported (voice_id and custom_prompt via Update phone number, plus per-number integrations), or handle it yourself from the post-call webhook. This keeps each business independent while sharing one agent.

​
Configurable fields

When you POST /v1/agents, you can set:
FieldTypeDefaultPurpose
namestring"Untitled Agent"Display name in dashboard
system_promptstringemptyWhat the agent should do (see below)
welcome_messagestringgenericFirst thing the agent says on inbound calls
voice_idstring"Ashley"voice
languagestring"en"Default language code
response_lengthenum"medium"short, medium, or long
interruption_sensitivityenum"medium"low, medium, high
max_call_duration_secondsint300Hard cap; engine ends call at this
silence_hangup_secondsint10Hang up if caller silent this long. Range 5–45.
pickup_delayint10Seconds to wait after pickup before speaking. Range 5–30.
record_callbooltrueRecord audio to Supabase bucket
webhook_urlstringnullWhere to POST post-call data
transfer_typeenum"cold"cold or warm. Applies to inbound, outbound, and batch calls.
transfer_whisperstringnullWarm transfer briefing. If empty, AI auto-generates.
transfer_numberstringnullDefault destination for [TRANSFER:]
post_call_sms_templatestringnullIf set, sends this SMS after call ends
llm_modelstring"default"LLM used during calls
temperaturefloat0.7Creativity vs predictability
fallback_messagestringsensible defaultSaid when STT confidence is too low
See the full Create Agent API reference for request and response details.

​
Writing a good system prompt

The agent is the brain. The prompt tells it who it is, what to do, and what not to do. For a deeper guide - scenarios, style, and inbound vs outbound - see Writing a good agent prompt. A solid agent prompt has six sections:
1

Role

Who the agent is. “You are the front-desk assistant for Acme Dental in London.”
2

Business facts

Concrete facts the agent must know. Opening hours, address, services, prices. Never invent these.
3

Goal

What success looks like. “Book an appointment, answer a question, or transfer to the dentist if it’s clinical.”
4

Rules

Hard constraints. “Never give medical advice. Never quote prices not in this prompt. If unsure, transfer.”
5

Style

How to speak. “Warm British accent. Short sentences. One question at a time. No bullet points (you’re on a phone call).”
6

Actions

When to use built-in tags like [TRANSFER:], [SEND_SMS:], [END_CALL]. See Agent actions.
You don’t need to teach the agent how to handle interruptions, silence, language switching, or call endings. The engine injects those rules automatically. Just write the business logic.

​
Example prompt

ROLE
You are the front-desk assistant at Acme Dental, a small dental practice in Croydon, London.

BUSINESS FACTS
- Opening hours: Mon-Fri 9am-6pm, Sat 9am-1pm, closed Sun
- Address: 12 High Street, Croydon CR0 1AB
- Services: check-ups (£45), cleaning (£60), whitening (£250)
- Emergency line: transfer to +442087601234

GOAL
Book check-up appointments, answer pricing questions, transfer clinical questions to the dentist.

RULES
- Never give medical or dental advice. Transfer clinical questions.
- Quote only prices listed above. Say "let me check" if asked anything else.
- If caller sounds urgent or in pain, transfer immediately: [TRANSFER:+442087601234]
- Confirm the booking details back to the caller before ending.

STYLE
Friendly, professional, brief. Speak naturally — you're on a phone call.

ACTIONS
- To transfer: [TRANSFER:+442087601234]
- To end the call after a booking: [END_CALL]
- To text booking confirmation: [SEND_SMS: Your appointment with Acme Dental is confirmed for {date} at {time}.]

​
Listing and updating

  • GET /v1/agents — list all your agents
  • GET /v1/agents/:id — fetch one
  • PUT /v1/agents/:id — update any field
  • DELETE /v1/agents/:id — remove (calls in progress finish first)
See the API reference for full schemas.