curl --request POST \
  --url https://app.famulor.io/api/v1/assistants \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "template_id": "a1b2c3d4-0000-4000-8000-000000000010",
  "name": "Website Concierge"
}
'

{
  "data": {
    "id": "a1b2c3d4-0000-4000-8000-000000000001",
    "name": "Support Agent",
    "is_active": true,
    "created_by": "u1b2c3d4-0000-4000-8000-000000000003",
    "system_prompt": "You are a friendly support agent for Acme Corp...",
    "mode": "pipeline",
    "realtime_provider": null,
    "realtime_voice": null,
    "llm_temperature": 0.7,
    "stt_provider": "deepgram",
    "stt_language": "en",
    "tts_provider": "elevenlabs",
    "tts_voice": "21m00Tcm4TlvDq8ikWAM",
    "tts_speed": 1,
    "turn_detection": "multilingual_model",
    "first_message": "Hi! How can I help you today?",
    "greeting_mode": "agent_speaks_first",
    "recording_enabled": true,
    "max_call_duration_sec": 1200,
    "inbound_ringing_timeout_sec": 60,
    "outbound_ringing_timeout_sec": 45,
    "idle_timeout_sec": 30,
    "knowledgebase_id": null,
    "webhook_url": null,
    "metadata": {},
    "created_at": "2026-07-01T09:00:00Z",
    "updated_at": "2026-07-01T09:00:00Z"
  }
}

Assistants

Create an assistant

Creates an assistant. Provide name, or pass a visible catalog template_id to resolve its prompt, greeting, language, variables and optional Flow JSON server-side. Explicit request fields override the template seed. Default agent type is Single prompt (flow_json omitted or null — uses system_prompt + greeting). For Conversational flow, pass a Flow JSON v1 object in flow_json (typically a Start→Agent→End seed). Model fields are validated against the platform model catalog, the workspace assistant limit is enforced, and non-trivial flows may require the Flow Builder feature. Pipeline and Half-cascade assistants are checked against the languages their voice can speak: a request whose voice can’t speak the primary language, a secondary language or a language with its own voice returns 400 invalid_request. Without tts_voice, a default voice that speaks the primary language is chosen. Required scope: assistants:write (keys without scope restrictions have full access).

POST

assistants

curl --request POST \
  --url https://app.famulor.io/api/v1/assistants \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "template_id": "a1b2c3d4-0000-4000-8000-000000000010",
  "name": "Website Concierge"
}
'

{
  "data": {
    "id": "a1b2c3d4-0000-4000-8000-000000000001",
    "name": "Support Agent",
    "is_active": true,
    "created_by": "u1b2c3d4-0000-4000-8000-000000000003",
    "system_prompt": "You are a friendly support agent for Acme Corp...",
    "mode": "pipeline",
    "realtime_provider": null,
    "realtime_voice": null,
    "llm_temperature": 0.7,
    "stt_provider": "deepgram",
    "stt_language": "en",
    "tts_provider": "elevenlabs",
    "tts_voice": "21m00Tcm4TlvDq8ikWAM",
    "tts_speed": 1,
    "turn_detection": "multilingual_model",
    "first_message": "Hi! How can I help you today?",
    "greeting_mode": "agent_speaks_first",
    "recording_enabled": true,
    "max_call_duration_sec": 1200,
    "inbound_ringing_timeout_sec": 60,
    "outbound_ringing_timeout_sec": 45,
    "idle_timeout_sec": 30,
    "knowledgebase_id": null,
    "webhook_url": null,
    "metadata": {},
    "created_at": "2026-07-01T09:00:00Z",
    "updated_at": "2026-07-01T09:00:00Z"
  }
}

Authorizations

Authorization

string

header

required

API key (fam_..., created under Settings → API Keys) or an OAuth 2.0 access token (fam_at_...). REST operations also require API Access for the credential's workspace. Keys can be restricted to scopes such as assistants:read, calls:write, campaigns:write, automations:read, dashboards:read, dashboards:write, leads:write, segments:write, loop:read, loop:write, phone_numbers:write, sip_trunks:write, knowledge:write, voices:read, billing:read, billing:write, settings:write, platform:read, platform:write; a *:write scope implies the matching *:read. Automation and dashboard endpoints also accept the legacy calls:* scope. Keys without scope restrictions have full access within the workspace's available capabilities.

Body

application/json

Assistant creation input. Supply either a non-empty name or a visible template_id. Template values are the base; every explicitly supplied assistant field overrides that value.

name

string

tags

string[]

Free-form workspace tags for filtering assistants. Case-insensitive unique; original spelling is kept.

Maximum array length: 20

Maximum string length: 40

is_active

boolean

system_prompt

string

response_by_channel

object

Versioned manual response instructions for exact output channels. Omit a channel key to use Automatic. Manual instructions supplement and never replace safety, language, tool, or delivery rules. Requires the workspace's Manual channel responses feature.

Show child attributes

mode

enum<string>

Assistant engine: Pipeline, Realtime, Half-cascade, or Translate for a two-person interpreter room. The selected mode must be included in the workspace's current plan.

Available options:

pipeline,

realtime,

half_cascade,

translation

realtime_provider

string | null

realtime_model

string | null

Requires Fallbacks & Guardrails for this workspace. Select a compatible value from the model catalog; null follows workspace then platform defaults. Omitted from responses without this entitlement.

realtime_voice

string | null

Compatible native conversation voice. Use a neutral ID returned by the native voice library. Available for Realtime; the chosen variant controls compatibility.

llm_provider

enum<string> | null

Requires Fallbacks & Guardrails for this workspace. Select a compatible value from the model catalog; null follows workspace then platform defaults. Omitted from responses without this entitlement.

Available options:

openai,

azure,

google,

groq,

anthropic,

null

llm_model

string | null

Requires Fallbacks & Guardrails for this workspace. Select a compatible value from the model catalog; null follows workspace then platform defaults. Omitted from responses without this entitlement.

half_cascade_provider

string | null

Requires Fallbacks & Guardrails for this workspace. Select a compatible value from the model catalog; null follows workspace then platform defaults. Omitted from responses without this entitlement.

half_cascade_model

string | null

Requires Fallbacks & Guardrails for this workspace. Select a compatible value from the model catalog; null follows workspace then platform defaults. Omitted from responses without this entitlement.

llm_temperature

number

stt_language

string

stt_keyterms

string[]

Speech-recognition glossary for customer, product, and proper names. Plan-gated.

Maximum array length: 100

Maximum string length: 100

stt_keyterm_detection_enabled

boolean

Beta: automatically detect additional call-local keyterms. Detected terms are not persisted.

tts_provider

enum<string>

Available options:

cartesia,

elevenlabs,

openai,

google,

azure,

fishaudio,

deepgram,

inworld,

rime,

xai

tts_voice

string | null

Pipeline or Half-Cascade speech voice. For Full Duplex, retained only for a Pipeline fallback; greetings, consent and tool announcements use realtime_voice. Uploaded greeting audio retains its recorded voice. Must be able to speak the primary and secondary languages.

tts_speed

number

tts_emotion

string[]

Legacy array field controlling Dynamic emotions (Expressive Mode) for compatible pipeline and half-cascade voices. Omit on create to enable it when supported. Send [] to disable it or ["calm"] to enable it. Realtime speech models handle expression natively.

Example:

["calm"]

tts_style_prompt

string | null

Optional free-text speaking-style instructions for compatible TTS models. Send null to clear the override.

elevenlabs_stability

number | null

Voice stability override. Send null to use the voice-provider default.

Required range: 0 <= x <= 1

elevenlabs_similarity

number | null

Voice similarity override. Send null to use the voice-provider default.

Required range: 0 <= x <= 1

elevenlabs_style

number | null

Voice-style exaggeration override. Send null to use the voice-provider default.

Required range: 0 <= x <= 1

elevenlabs_speaker_boost

boolean | null

Speaker-boost override. Send null to use the voice-provider default.

affective_dialog

boolean

Realtime mode with a Google realtime model only: match the caller's tone with warmer, more expressive speech.

turn_detection

enum<string>

Available options:

multilingual_model,

english_model,

vad,

stt

vad_min_silence_ms

integer

vad_threshold

number | null

Voice-detection threshold. Null uses the effective engine default: 0.50 for pipeline and adaptive voice detection, 0.50 for web server VAD, and 0.70 for phone server VAD. This detects speech; it does not filter audio.

Required range: 0.1 <= x <= 0.9

allow_interruptions

boolean

min_interruption_duration_ms

integer

response_timing

enum<string>

How quickly the assistant answers once the caller pauses: snappy answers right away, balanced leaves a short pause, patient waits longer for callers who pause mid-sentence. Applies to pipeline mode and adaptive realtime turn handling.

Available options:

snappy,

balanced,

patient

min_interruption_words

integer

Pipeline mode only: ignore barge-ins shorter than this many words, so back-channel sounds like “mhm” don't interrupt the assistant. 0 turns it off; larger values are capped at 10.

Required range: 0 <= x <= 10

noise_cancellation

enum<string>

Available options:

bvc,

bvc_telephony,

none

preemptive_generation

boolean

Begin response generation before turn confirmation. Effective in pipeline mode only.

resume_false_interruption

boolean

Resume interrupted output when an apparent interruption produces no transcript during the two-second false-interruption window. Effective in pipeline mode and adaptive realtime turn handling, and only while interruptions are enabled.

max_tool_steps

integer

first_message

string | null

greeting_mode

enum<string>

Available options:

agent_speaks_first,

user_speaks_first

greeting_allow_interruptions

boolean

When true, the caller may barge in during the opening greeting (first message / audio / silence fallback). Default false = play greeting uninterrupted. Separate from allow_interruptions (rest of the call).

ai_speaks_after_silence

boolean

When greeting_mode is user_speaks_first: after ai_entry_timeout_sec of initial silence, the assistant speaks (static or dynamic). Default false.

silence_greeting_mode

enum<string>

Available options:

static,

dynamic

silence_greeting_message

string

ai_entry_timeout_sec

integer

Required range: 1 <= x <= 20

pre_call

object

iOS/Android Call Screen Handling. Mirrored into flow_json.pre_call when a flow exists.

Show child attributes

flow_json

object | null

Agent type. Omit or null = Single prompt (default). Object = Conversational flow (Flow JSON v1). Seed Start→Agent→End for a basic flow; non-trivial graphs may require the Flow builder feature in the workspace plan. In flow mode, system_prompt is the Advanced / base prompt (agent-node text is appended).

recording_enabled

boolean

Whether audio recording is enabled for calls handled by this assistant. In PATCH and PUT requests, omitting this field leaves the existing setting unchanged. Saving an explicit boolean (true or false) updates the setting. Recording calls is independent of Loop recording and voicemail recording; see /assistants/conversation-quality#consent for caller consent rules and /billing/minutes#call-recording for recording billing.

retranscribe_enabled

boolean

Enhanced transcription: after the call, the recording is transcribed again with a higher-accuracy engine and shown next to the live transcript. Only takes effect while recording_enabled is on. Billed in credits per recorded minute.

card_collect_enabled

boolean

Allows secure payment card collection (the Collect payment card tool and Flow Collect steps of type credit_card). Also needs a connected payment account. Switching it on requires a plan that includes payment card collection; otherwise the request fails with HTTP 403.

max_call_duration_sec

integer | null

Maximum call duration in seconds (60–1800). null = unlimited (budget cap still applies).

Required range: 60 <= x <= 1800

inbound_ringing_timeout_sec

integer

How long inbound callers hear ringing before the call times out (30–120 s, default 60). If every concurrent line is busy, callers keep ringing within this time until a line frees up.

Required range: 30 <= x <= 120

outbound_ringing_timeout_sec

integer

How long outbound SIP/WhatsApp calls ring before no-answer (15–80 s, default 45).

Required range: 15 <= x <= 80

amd_enabled

boolean

default:false

Answering machine detection on direct outbound calls (dashboard, API, automations, callbacks). New assistants default to false: the assistant greets as soon as the call is answered and mailboxes are not detected. Campaign calls use the campaign's amd_enabled.

voicemail_enabled

boolean

default:false

What a direct outbound call does at a detected mailbox: true = speak voicemail_message, then hang up; false = hang up without a message. Takes effect while amd_enabled is on. Campaign calls use the campaign's voicemail settings.

voicemail_message

string | null

Message spoken onto a detected mailbox when voicemail_enabled is true; supports {{variables}}. null or empty = the greeting / first message is used.

idle_timeout_sec

integer

transcription_timeout_sec

number | null

Seconds after VAD detects speech with no STT transcript before asking the caller to repeat. null disables.

Required range: 1 <= x <= 30

knowledgebase_id

string<uuid> | null

knowledge_gap_mode

enum<string>

Available options:

off,

questions_only,

draft_for_review,

tentative_live

webhook_url

string | null

Agent-level post-call webhook URL.

webhook_timeout_sec

integer

Required range: 1 <= x <= 30

webhook_retries

integer

Required range: 0 <= x <= 5

webhook_delivery_mode

enum<string>

none = do not deliver; custom = POST the assistant webhook URL after the call; automation = deliver through the bound automation.

Available options:

none,

custom,

automation

automation_id

string<uuid> | null

Bound automation when webhook delivery is automation.

notification_settings

object

Activity notifications for this assistant, keyed by History channel (call, avatar, live_chat, whatsapp_voice, whatsapp, telegram, slack, messenger, teams, discord, gchat, x, freshdesk, gmail, outlook, zendesk, servicenow, intercom, zoho_mail, agent_mail, instagram, zulip, email; the legacy key messaging applies to every messaging channel). Each channel takes email and push toggles. A missing channel or toggle stays on; set it to false to opt out. Unknown keys are dropped.

Show child attributes

Example:

{
  "call": { "email": false },
  "whatsapp": { "push": false }
}

metadata

object

outbound_phone_number_id

string<uuid> | null

Workspace phone number this assistant calls from on outbound calls (an id from GET /phone-numbers). Several assistants can share one number. A phone_number_id passed when starting a call takes precedence. A number from another workspace or a released number returns HTTP 404. Null clears it.

background_audio

object

BackgroundAudioPlayer config (ambient, ambient_volume, thinking, thinking_volume). {} = off. Hold music is configured on the warm-transfer tool, not here.

adaptive_interruptions

boolean

realtime_turn_mode

enum<string>

Realtime turn handling: robust voice activity, semantic completion, or adaptive barge-in.

Available options:

server_vad,

semantic,

adaptive

realtime_eagerness

enum<string>

How quickly the assistant responds when realtime_turn_mode is semantic.

Available options:

auto,

low,

medium,

high

long_call_memory

enum<string>

Pipeline mode only: context strategy once a call runs long. full keeps the whole conversation in context; recent keeps the latest part in focus for faster responses on calls of 10+ minutes.

Available options:

full,

recent

idle_messages

string[]

Fixed re-engagement phrases on caller inactivity; [] = LLM-generated.

idle_max_rounds

integer

Unanswered idle check-ins before the assistant says goodbye and ends the call (1–10, default 2).

Required range: 1 <= x <= 10

fallback_config

object

Requires Fallbacks & Guardrails. Saved fallback configuration is omitted from responses without this workspace entitlement.

fallbacks_enabled

boolean

Turns on platform-managed model fallbacks, so a call continues on a backup model if a speech or language model fails. Must be a boolean. Switching it on requires Fallbacks & Guardrails; otherwise the request fails with HTTP 403.

pronunciation_map

object

Show child attributes

tts_filter_markdown

boolean

tts_filter_emoji

boolean

What happens when the caller declines consent: no_recording continues the call without recording, hangup says a farewell and ends the call.

Available options:

no_recording,

hangup

Custom farewell spoken before the call ends when the caller declines consent and consent_decline_action is hangup. Null or empty uses the default farewell for the assistant's language.

guardrails

object

language_voices

object

Per-language voice overrides for Pipeline/Half-cascade. Languages without an entry keep the main voice. A private per-language clone is allowed only when the main voice is also a workspace-owned private clone that uses the same provider runtime. Keys must be languages the voice can speak.

Show child attributes

auto_language_switch

boolean

Automatic response-language switching; derived from secondary_languages by the dashboard.

output_volume

number

speaking_rate

number

text_only_enabled

boolean

memory_enabled

boolean

memory_mode

enum<string>

inherit follows the workspace memory default; on/off override it.

Available options:

inherit,

on,

off

memory_scope

enum<string>

workspace = one summary shared across assistants; assistant = one summary private to this assistant; both = two complete summaries, one shared and one assistant-private.

Available options:

workspace,

assistant,

both

lead_attribute_mode

enum<string>

all is an immutable compatibility state for an assistant that already had unrestricted contact-field access. Creating with all or changing selected to all returns HTTP 400. selected exposes only explicit source: lead definitions.

Available options:

all,

selected

memory_read_channels

enum<string>[]

Per-assistant read allowlist intersected with workspace policy. Send [] to disable reads.

Memory channels. Web Chat and Web Voice require a current verified widget email or phone and memory consent. Web and SMS memory require a root workspace. Legacy web configuration expands to both web channels; anonymous sessions remain excluded.

Available options:

voice,

sms,

whatsapp,

email,

web,

telegram,

slack,

messenger,

teams,

discord,

gchat,

x,

freshdesk,

gmail,

outlook,

zendesk,

servicenow,

intercom,

zoho_mail,

agent_mail,

instagram,

zulip,

web_chat,

web_voice

memory_write_channels

enum<string>[]

Per-assistant write allowlist intersected with workspace policy. Send [] to disable writes.

Available options:

voice,

sms,

whatsapp,

email,

web,

telegram,

slack,

messenger,

teams,

discord,

gchat,

x,

freshdesk,

gmail,

outlook,

zendesk,

servicenow,

intercom,

zoho_mail,

agent_mail,

instagram,

zulip,

web_chat,

web_voice

memory_categories

enum<string>[]

Allowed summary categories. Send [] for metadata-only memory with no new content summary.

Available options:

identity,

preferences,

agreements,

open_items

redact_pii

boolean

When true, apply pii_redaction entity filters to stored transcripts.

pii_redaction

object

PII entity categories + optional custom regexes.

analysis_config

object

Post-conversation sentiment, success and structured extraction for voice, chat, messaging and email. Results retain native JSON types in History, webhooks, the public API and MCP.

Show child attributes

qa_scorecard_config

object | null

AI QA scorecard configuration (requires AI QA Scorecards in the workspace plan). null or enabled: false disables scoring.

Show child attributes

timezone

string

IANA timezone of the assistant (e.g. Europe/Berlin, default). Anchors the get_current_time system tool, the {{time}}/{{date}}/{{datetime}}/{{weekday}} system variables, and the check_business_hours built-in tool. On campaign calls the campaign's timezone overrides it per call.

primary_language

string

Language the assistant answers in by default (ISO 639-1 or ISO 639-3, see GET /languages). Pipeline and Half-cascade: must be a language the assistant's voice can speak. If you omit tts_voice when creating, a default voice that speaks this language is chosen. Use gsw for German (Switzerland), spoken as Swiss German through dialect instructions; pronunciation depends on the selected voice. de-CH remains standard German.

secondary_languages

string[]

Languages the assistant may switch to when the caller clearly speaks them (ISO 639-1 or ISO 639-3). Non-empty implies multilingual STT + auto language switch. Each language must be speakable by the assistant's voice (Pipeline and Half-cascade); otherwise the request fails with invalid_request. Do not combine de and gsw: automatic detection cannot distinguish these variants.

variables

object[]

Custom variable definitions, referenced as {{key}} and resolved per call (explicit call values > inbound enrichment > current contact values > remembered value > default_value). Each custom definition can be call-only, workspace-shared, or assistant-private.

Show child attributes

variable_webhook_url

string | null

Optional webhook called on inbound calls to enrich variable values before the conversation starts.

variable_webhook_secret

string | null

write-only

Secret used to sign variable webhook requests (HMAC-SHA256 of the raw body, sent as X-Famulor-Signature: sha256=<hex>). Write-only: never returned. Null clears it.

builtin_tools

object[]

Inline built-in tool configurations (also accepted as tools for compatibility). DTMF Input and Collect Keypad Input run as prompt-session tools here; dedicated Flow nodes bind their reusable central-tool equivalents.

Show child attributes

translation_config

object

Show child attributes

realtime_variant

enum<string>

Realtime conversation variant. Full Duplex requires workspace Beta features, Realtime plan access and compatible defaults available in the selected workspace region; extra credits may apply. Its reasoning model is managed centrally. Existing assistants use standard.

Available options:

standard,

full_duplex

template_id

string<uuid>

ID returned by GET /prompt-templates. Resolves the template server-side and is not stored on the assistant.

Response

The created assistant.

data

object

required

A voice assistant configuration. Nullable model overrides are independent per engine: pipeline uses llm_*, realtime uses realtime_*, and half-cascade uses half_cascade_* for its text-capable realtime input plus tts_* for output.

Show child attributes