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"
}
}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).
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
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
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.
Interactive responses for live chat (website widget and Test Chat) and WhatsApp text. One quick_replies.enabled setting applies to both. Live chat can show 2–5 buttons. WhatsApp can show 2–3 buttons in an open customer service window. Quick replies are off by default. PATCH and PUT replace the entire object. Include the instructions to keep your saved guidance.
Show child attributes
Show child attributes
Requires AI Safety & Control for this workspace. Select a compatible value from the model catalog; null follows workspace then platform defaults. Omitted from responses without this entitlement.
openai, azure, google, groq, anthropic, deepseek-ai, moonshotai, xai, null 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.
snappy, balanced, patient 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).
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.
Activity notifications for this assistant, keyed by History channel (call, avatar, live_chat, whatsapp_voice, whatsapp, telegram, slack, messenger, teams, discord, gchat, x, linear, notion, twitch, mattermost, webex, lark, line, sendblue, linq, zernio, 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
Show child attributes
{
"call": { "email": false },
"whatsapp": { "push": false }
}
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.
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
Show child attributes
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.
voice, sms, whatsapp, email, web, telegram, slack, messenger, teams, discord, gchat, x, linear, notion, twitch, mattermost, webex, lark, line, sendblue, linq, zernio, freshdesk, gmail, outlook, zendesk, servicenow, intercom, zoho_mail, agent_mail, instagram, zulip, web_chat, web_voice Per-assistant write allowlist intersected with workspace policy. Send [] to disable writes.
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.
voice, sms, whatsapp, email, web, telegram, slack, messenger, teams, discord, gchat, x, linear, notion, twitch, mattermost, webex, lark, line, sendblue, linq, zernio, freshdesk, gmail, outlook, zendesk, servicenow, intercom, zoho_mail, agent_mail, instagram, zulip, web_chat, web_voice IANA timezone of the assistant (e.g. Europe/Berlin). When omitted during creation, the workspace timezone is copied as the initial value; later workspace timezone changes do not override the saved assistant setting. Omit it on updates to preserve the current value. Anchors the get_current_time system tool, the {{time}}/{{date}}/{{datetime}}/{{weekday}} system variables, the check_business_hours built-in tool, and the transfer hours of transfer tools that set no timezone. On campaign calls the campaign's timezone overrides it per call, except for transfer hours.
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.
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.
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.
standard, full_duplex