{"openapi":"3.1.0","info":{"title":"Famulor API","summary":"REST API für AI-Assistenten, Anrufe, Konversationen, Leads und omnichannel Kundenkommunikation.","description":"Die Famulor Produkt-API unter `https://app.famulor.de/api`. Damit steuerst du\nAI-Assistenten, startest und liest Anrufe, verwaltest Leads und Kampagnen,\nversendest SMS und WhatsApp-Nachrichten, pflegst Wissensdatenbanken und\nautomatisierst Prozesse.\n\n## Authentifizierung\n\nAlle Endpunkte erwarten einen API-Key als Bearer-Token:\n\n```\nAuthorization: Bearer YOUR_API_KEY\n```\n\nDen Key erstellst du in deinem Account unter <https://app.famulor.de> im\nBereich API-Keys. Der Key wird nur einmal angezeigt.\n\n## Webhooks\n\nFamulor sendet Ereignisse (Post-Call, Conversation Ended, Read Receipts) an\ndeine URL. Die Payloads stehen im Abschnitt `webhooks` dieser Spec.\n\nDiese Datei wird aus der offiziellen Dokumentation generiert:\n<https://docs.famulor.io/api-v1/introduction>","version":"1.0.0","contact":{"name":"Famulor Support","email":"support@famulor.io","url":"https://www.famulor.io/support"},"license":{"name":"Proprietary","url":"https://www.famulor.io/terms"},"termsOfService":"https://www.famulor.io/terms"},"externalDocs":{"description":"Famulor API-Dokumentation","url":"https://docs.famulor.io/api-v1/introduction"},"servers":[{"url":"https://app.famulor.de/api","description":"Production"}],"security":[{"BearerAuth":[]}],"tags":[{"name":"Account","description":"Account-Informationen, Guthaben und einzelne Calls."},{"name":"Assistants","description":"AI-Assistenten anlegen, konfigurieren und Metadaten abrufen."},{"name":"Calls","description":"Anrufe starten, auflisten und löschen."},{"name":"Campaigns","description":"Outbound-Kampagnen verwalten und steuern."},{"name":"Leads","description":"Leads anlegen, aktualisieren und auflisten."},{"name":"Conversations","description":"Konversationen auflisten und die KI pro Konversation steuern."},{"name":"AI Chatbot","description":"Chat-Konversationen für Web-Widget und Chatbot-Kanäle."},{"name":"AI Replies","description":"KI-generierte Antwortvorschläge für Konversationen."},{"name":"WhatsApp","description":"WhatsApp-Sender, Templates und Nachrichtenversand."},{"name":"SMS","description":"SMS-Versand."},{"name":"Phone Numbers","description":"Rufnummern suchen, kaufen, konfigurieren und freigeben."},{"name":"SIP Trunks","description":"Eigene SIP-Trunks anbinden und verwalten."},{"name":"Knowledge Bases","description":"Wissensdatenbanken und deren Dokumente."},{"name":"Mid-Call Tools","description":"Mid-Call-Aktionen, die der Assistent während eines Gesprächs auslöst."},{"name":"Automations","description":"Automations-Flows, Templates und Runs."},{"name":"Folders","description":"Ordner zur Organisation von Assistenten."},{"name":"Labels","description":"Labels für Leads und Konversationen."},{"name":"Webhooks","description":"Ereignis-Callbacks, die Famulor an deine URL sendet."}],"paths":{"/automate/conversations/{uuid}/disable-ai":{"post":{"tags":["Conversations"],"summary":"Disable AI","operationId":"disableAI","description":"Disable AI replies for a specific conversation and hand over to a human\n\n[Docs](https://docs.famulor.io/api-v1/conversations/disable-ai)","externalDocs":{"description":"Disable AI","url":"https://docs.famulor.io/api-v1/conversations/disable-ai"},"parameters":[{"name":"uuid","in":"path","required":true,"description":"The unique UUID identifier of the conversation","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"status":true,"ai_enabled":false},"schema":{"type":"object","properties":{"status":{"type":"boolean","description":"`false` when an error occurs"},"ai_enabled":{"type":"boolean","description":"Always `false` on success"},"error":{"type":"string","description":"Error message. Possible values:\n\n* `Conversation not found` — the UUID does not exist or belongs to a different account"}},"additionalProperties":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":"Unauthorized"}}}},"404":{"description":"Not Found","content":{"application/json":{"example":{"status":false,"error":"Conversation not found"}}}},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/automate/conversations/{uuid}/enable-ai":{"post":{"tags":["Conversations"],"summary":"Enable AI","operationId":"enableAI","description":"Re-enable AI replies for a conversation after a human takeover\n\n[Docs](https://docs.famulor.io/api-v1/conversations/enable-ai)","externalDocs":{"description":"Enable AI","url":"https://docs.famulor.io/api-v1/conversations/enable-ai"},"parameters":[{"name":"uuid","in":"path","required":true,"description":"The unique UUID identifier of the conversation","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"status":true,"ai_enabled":true},"schema":{"type":"object","properties":{"status":{"type":"boolean","description":"`false` when an error occurs"},"ai_enabled":{"type":"boolean","description":"Always `true` on success"},"error":{"type":"string","description":"Error message. Possible values:\n\n* `Conversation not found` — the UUID does not exist or belongs to a different account"}},"additionalProperties":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":"Unauthorized"}}}},"404":{"description":"Not Found","content":{"application/json":{"example":{"status":false,"error":"Conversation not found"}}}},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/conversations":{"post":{"tags":["AI Chatbot"],"summary":"Create conversation","operationId":"createConversation","description":"Start a new conversation session with a Famulor AI chatbot via API. Initialise context, user metadata and channel for WhatsApp, web chat or voice chat.\n\n[Docs](https://docs.famulor.io/api-v1/ai-chatbot/create-conversation)","externalDocs":{"description":"Create conversation","url":"https://docs.famulor.io/api-v1/ai-chatbot/create-conversation"},"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assistant_id":{"type":"string","description":"UUID of the assistant that should handle the conversation"},"type":{"type":"string","description":"Conversation type. Options: `widget` (paid) or `test` (free for development)","default":"widget"},"variables":{"type":"object","description":"Custom variables injected into the assistant context (accessible via `{{variable_name}}`)","properties":{"customer_name":{"type":"string","description":"Name for greeting or personalization"},"company":{"type":"string","description":"Company name to reference in replies"},"source":{"type":"string","description":"Traffic or page source (e.g., `pricing_page`)"}}}},"required":["assistant_id"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"examples":{"success":{"summary":"Success","value":{"status":true,"conversation_id":"7c9e6679-7425-40de-944b-e07fc1f90ae7","history":[{"role":"assistant","content":"Hello John Smith! Welcome to Acme Corp support. How can I help you today?"}]}},"success-no-initial-message":{"summary":"Success (no initial message)","value":{"status":true,"conversation_id":"7c9e6679-7425-40de-944b-e07fc1f90ae7","history":[]}}},"schema":{"type":"object","properties":{"status":{"type":"boolean","description":"Indicates whether the request succeeded"},"conversation_id":{"type":"string","description":"UUID of the created conversation; use it for subsequent messages"},"history":{"type":"array","description":"Initial conversation history. Empty if the assistant has no initial message.","items":{"type":"object","properties":{"role":{"type":"string","description":"Message role (`assistant` or `user`)"},"content":{"type":"string","description":"Message text content"}},"additionalProperties":true}}},"required":["status","conversation_id"],"additionalProperties":true}}}},"400":{"description":"Insufficient Balance","content":{"application/json":{"example":{"status":false,"error":"Insufficient balance. Please top up your account."}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Assistant Not Found","content":{"application/json":{"example":{"status":false,"error":"Assistant not found"}}}},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/conversations/{uuid}":{"get":{"tags":["AI Chatbot"],"summary":"Get conversation","operationId":"getConversation","description":"Retrieve full message history for an existing conversation\n\n[Docs](https://docs.famulor.io/api-v1/ai-chatbot/get-conversation)","externalDocs":{"description":"Get conversation","url":"https://docs.famulor.io/api-v1/ai-chatbot/get-conversation"},"security":[],"parameters":[{"name":"uuid","in":"path","required":true,"description":"UUID of the conversation to retrieve","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"examples":{"success":{"summary":"Success","value":{"status":true,"history":[{"role":"assistant","content":"Hello! Welcome to our support. How can I help you today?"},{"role":"user","content":"I'd like to schedule a demo"},{"role":"assistant","content":"I'd be happy to help you schedule a demo! I have availability tomorrow at 2 PM or Thursday at 10 AM. Which works better for you?","function_calls":[{"name":"check_calendar_availability","arguments":{"date_range":"next_7_days"},"result":{"available_slots":["2025-01-10 14:00","2025-01-12 10:00"]}}]},{"role":"user","content":"Thursday at 10 AM works for me"},{"role":"assistant","content":"I've scheduled your demo for Thursday, January 12th at 10 AM. You'll receive a calendar invitation shortly. Is there anything specific you'd like us to cover during the demo?","function_calls":[{"name":"book_appointment","arguments":{"datetime":"2025-01-12T10:00:00","title":"Product Demo"},"result":{"success":true,"booking_id":"abc123"}}]}],"variables":{"user_name":"Jane Smith","plan":"premium"}}},"api-conversation-with-external-id":{"summary":"API Conversation with External ID","value":{"status":true,"history":[{"role":"assistant","content":"Hi! I'm following up on your recent inquiry. How can I help you today?"},{"role":"user","content":"I wanted to know more about your enterprise plan"}],"variables":{"lead_id":"12345","source":"website"},"external_identifier":"crm-lead-12345"}},"whatsapp-conversation":{"summary":"WhatsApp Conversation","value":{"status":true,"history":[{"role":"user","content":"Hi, I need help with my order"},{"role":"assistant","content":"Hello! I'd be happy to help you with your order. Could you please provide your order number?"}],"variables":null,"whatsapp_sender":{"name":"Acme Corp Support","phone":"+14155551234"},"customer":{"name":"John Doe","phone":"+14155559876"}}}},"schema":{"type":"object","properties":{"status":{"type":"boolean","description":"Will be `false` when an error occurs"},"error":{"type":"string","description":"Error message. Possible values:\n\n* `Conversation not found` - The provided UUID does not match any conversation"}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not Found","content":{"application/json":{"example":{"status":false,"error":"Conversation not found"}}}},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/conversations/{uuid}/messages":{"post":{"tags":["AI Chatbot"],"summary":"Send message","operationId":"sendMessage","description":"Send a user message to an existing conversation and receive the assistant's response\n\n[Docs](https://docs.famulor.io/api-v1/ai-chatbot/send-conversation)","externalDocs":{"description":"Send message","url":"https://docs.famulor.io/api-v1/ai-chatbot/send-conversation"},"security":[],"parameters":[{"name":"uuid","in":"path","required":true,"description":"UUID of the existing conversation","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"User message to send (max 2000 characters)"}},"required":["message"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"examples":{"success":{"summary":"Success","value":{"status":true,"message":"I'd be happy to help you schedule a demo! I have availability on Monday at 2 PM, Wednesday at 10 AM, or Friday at 3 PM. Which time works best for you?","function_calls":[]}},"success-with-function-calls":{"summary":"Success (with function calls)","value":{"status":true,"message":"I found two slots. Which one do you prefer?","function_calls":[{"name":"check_calendar_availability","arguments":{"date_range":"next_week"},"result":{"available_slots":["2025-01-10 14:00","2025-01-12 10:00"]}}]}}},"schema":{"type":"object","properties":{"status":{"type":"boolean","description":"Indicates whether the request succeeded"},"message":{"type":"string","description":"Assistant's response text"},"function_calls":{"type":"array","description":"Function calls executed during this message (empty if none)","items":{"type":"object","properties":{"name":{"type":"string","description":"Function name"},"arguments":{"type":"object","description":"Arguments passed to the function","additionalProperties":true},"result":{"type":"object","description":"Return value from the function","additionalProperties":true}},"additionalProperties":true}}},"required":["status","message"],"additionalProperties":true}}}},"400":{"description":"Bad Request","content":{"application/json":{"examples":{"insufficient-balance":{"summary":"Insufficient Balance","value":{"status":false,"error":"Insufficient balance. Please top up your account."}},"processing-error":{"summary":"Processing Error","value":{"status":false,"error":"Failed to process message: invalid tool output"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not Found","content":{"application/json":{"example":{"status":false,"error":"Conversation not found"}}}},"422":{"description":"Validation Error","content":{"application/json":{"example":{"status":false,"error":"message is required"}}}}}}},"/user/ai/generate-reply":{"post":{"tags":["AI Replies"],"summary":"Generate AI Reply","operationId":"generateAIReply","description":"Generates an AI reply using an assistant based on a customer identifier\n\n[Docs](https://docs.famulor.io/api-v1/ai-replies/generate-reply)","externalDocs":{"description":"Generate AI Reply","url":"https://docs.famulor.io/api-v1/ai-replies/generate-reply"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assistant_id":{"type":"integer","description":"The ID of the assistant to use for reply generation. Must belong to your account."},"customer_identifier":{"type":"string","description":"A unique identifier for the customer. This is used to maintain conversation context across multiple messages.\n\n**Examples**: Phone number, email address, CRM contact ID, Facebook user ID.\n\n**Maximum length**: 255 characters.\n\n**Important**: Always use the same format for the same customer to ensure context is correctly mapped."},"message":{"type":"string","description":"The customer's message to reply to."},"variables":{"type":"object","description":"Optional context variables to pass to the assistant. These are merged with existing conversation variables.\n\nUseful for passing customer data, session context, or other metadata that can personalize the reply.","properties":{"customer_name":{"type":"string","description":"Customer name for personalized addressing"},"source":{"type":"string","description":"Message source (e.g. `whatsapp`, `facebook`, `sms`)"},"order_id":{"type":"string","description":"Order number for support requests"}}}},"required":["assistant_id","customer_identifier","message"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"examples":{"success":{"summary":"Success","value":{"success":true,"conversation_id":"7c9e6679-7425-40de-944b-e07fc1f90ae7","customer_identifier":"+14155551234","reply":"Hi John! I'd be happy to help you schedule an appointment. What day and time work best for you?","function_calls":[],"ai_disabled":false}},"success-with-function-calls":{"summary":"Success (With Function Calls)","value":{"success":true,"conversation_id":"7c9e6679-7425-40de-944b-e07fc1f90ae7","customer_identifier":"+14155551234","reply":"I've checked our calendar and we have availability tomorrow at 2 PM and Friday at 10 AM. Which works better for you?","function_calls":[{"name":"check_availability","arguments":{"start_date":"2025-01-08","days":7},"result":{"slots":["2025-01-08 14:00","2025-01-10 10:00"]}}],"ai_disabled":false}}},"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Will be `false` when an error occurs"},"conversation_id":{"type":"string","description":"The UUID of the conversation. Use this to track or reference the conversation later."},"customer_identifier":{"type":"string","description":"The customer identifier provided in the request"},"reply":{"type":"string","description":"The AI-generated reply to the customer message"},"function_calls":{"type":"array","description":"Array of function calls the assistant made while processing the message. Empty array if no functions were called.","items":{"type":"object","properties":{"name":{"type":"string","description":"The name of the function that was called"},"arguments":{"type":"object","description":"The arguments passed to the function","additionalProperties":true},"result":{"type":"object","description":"The result of the function call","additionalProperties":true}},"additionalProperties":true}},"ai_disabled":{"type":"boolean","description":"Indicates whether AI replies are disabled for this conversation (e.g. due to manual takeover)"},"error":{"type":"string","description":"Error message describing what went wrong"},"error_code":{"type":"string","description":"Machine-readable error code. Possible values:\n\n- `ASSISTANT_NOT_FOUND` - The assistant ID is invalid or does not belong to your account\n- `INSUFFICIENT_BALANCE` - Your account balance is too low to process the message"}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"Insufficient Balance","content":{"application/json":{"example":{"success":false,"error":"Insufficient balance. Please top up your account.","error_code":"INSUFFICIENT_BALANCE"}}}},"404":{"description":"Assistant Not Found","content":{"application/json":{"example":{"success":false,"error":"Assistant not found or does not belong to you","error_code":"ASSISTANT_NOT_FOUND"}}}},"422":{"description":"Validation Error","content":{"application/json":{"example":{"message":"The assistant id field is required.","errors":{"assistant_id":["The assistant id field is required."]}}}}},"429":{"description":"Rate Limited","content":{"application/json":{"example":{"message":"Too Many Attempts.","retry_after":60}}}}}}},"/user/assistant":{"post":{"tags":["Assistants"],"summary":"Create Assistants","operationId":"createAssistants","description":"Create a new AI assistant with specified configuration\n\n[Docs](https://docs.famulor.io/api-v1/assistants/create)","externalDocs":{"description":"Create Assistants","url":"https://docs.famulor.io/api-v1/assistants/create"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The name of the assistant (max. 255 characters)"},"voice_id":{"type":"integer","description":"The voice ID for the assistant. Use the endpoint [Retrieve Voices](/en/api-reference/assistants/voices) with the query parameter `mode` to get compatible voices for your engine mode."},"language_id":{"type":"integer","description":"The language ID for the assistant. Use the endpoint [Retrieve Languages](/en/api-reference/assistants/languages) to get available languages."},"type":{"type":"string","description":"The assistant type. Options: `inbound`, `outbound`","enum":["inbound","outbound"]},"mode":{"type":"string","description":"The engine mode. Options: `pipeline`, `multimodal`, `dualplex`","enum":["pipeline","multimodal","dualplex"]},"timezone":{"type":"string","description":"The time zone of the assistant (e.g., \"Europe/Berlin\", \"America/New_York\")"},"initial_message":{"type":"string","description":"The first message the assistant speaks at the start of the call (max. 200 characters)"},"system_prompt":{"type":"string","description":"The system prompt that defines the assistant’s behavior and personality"},"llm_model_id":{"type":"integer","description":"The LLM model ID. **Required for mode `pipeline`.**\n\nUse the endpoint [Retrieve Models](/en/api-reference/assistants/models) to get available models."},"multimodal_model_id":{"type":"integer","description":"The multimodal model ID. **Required for modes `multimodal` and `dualplex`.**\n\nUse the endpoint [Retrieve Models](/en/api-reference/assistants/models) to get available multimodal models."},"chat_llm_fallback_id":{"type":"integer","description":"Fallback LLM model ID for tool calls in `multimodal`/`dualplex`. Optional."},"turn_detection_threshold":{"type":"number","description":"Sensitivity of turn detection in `multimodal`/`dualplex` (0-1). Default: auto"},"secondary_language_ids":{"type":"array","items":{"type":"integer"},"description":"Array of additional language IDs that the assistant can speak. The assistant automatically recognizes the language and switches accordingly."},"knowledgebase_id":{"type":"integer","description":"The knowledgebase ID to attach to this assistant"},"knowledgebase_mode":{"type":"string","description":"How to use the knowledgebase. Options:\n\n* `function_call` - AI calls a function to search (required for multimodal/dualplex)\n* `prompt` - Knowledge is injected into prompt (pipeline only)"},"folder_id":{"type":"integer","description":"ID of a [folder](/en/api-reference/folders/create) to place this assistant in. Must belong to your account. Send `null` to leave the assistant uncategorized."},"label_ids":{"type":"array","items":{"type":"integer"},"description":"Array of [label](/en/api-reference/labels/create) IDs to apply to this assistant. Each label must belong to your account."},"phone_number_id":{"type":"integer","description":"The ID of a phone number to assign to the assistant. Must belong to your account.\n\n<Warning>\nFor `inbound` assistants, the phone number must not be a caller ID type and must not already be assigned to another `inbound` assistant.\n</Warning>"},"tool_ids":{"type":"array","items":{"type":"integer"},"description":"Array of IDs for custom mid-call tools to attach. Each tool must belong to your account."},"tools":{"type":"array","description":"Array of built-in tools. Each tool has a `type` field and tool-specific fields. On [Update Assistant](/en/api-reference/assistants/update), this **replaces all existing built-in tools** — pass an empty array `[]` to remove all tools.\n\n\n\n<Note>\nWhen you [list assistants](/en/api-reference/assistants/list), each configured tool is returned as `{ \"type\": \"...\", \"data\": { ... } }` with the same field names nested under `data` (not top-level).\n</Note>","items":{}},"tts_emotion_enabled":{"type":"boolean","description":"Whether emotional text-to-speech synthesis is enabled","default":true},"voice_stability":{"type":"number","description":"Voice stability (0-1). Higher = more consistent","default":0.7},"voice_similarity":{"type":"number","description":"Voice similarity (0-1). Higher = closer to the original","default":0.5},"speech_speed":{"type":"number","description":"Speech speed multiplier (0.7-1.2)","default":1},"llm_temperature":{"type":"number","description":"LLM temperature (0-1). Lower = more deterministic","default":0.1},"synthesizer_provider_id":{"type":"integer","description":"Custom TTS provider ID. If not set, selected automatically based on language. See [Retrieve Synthesizer Providers](/en/api-reference/assistants/synthesizer-providers)."},"transcriber_provider_id":{"type":"integer","description":"Custom STT provider ID. If not set, selected automatically based on language. Only for `pipeline`. See [Retrieve Transcriber Providers](/en/api-reference/assistants/transcriber-providers)."},"allow_interruptions":{"type":"boolean","description":"Whether interruptions from the caller are allowed.\n\n<Warning>Cannot be disabled for `multimodal` and `dualplex`.</Warning>","default":true},"fillers":{"type":"boolean","description":"Whether filler audio should be used during processing (e.g., \"uh\", \"just a moment\").\n\n<Warning>Only available in `pipeline` mode.</Warning>","default":false},"filler_config":{"type":"object","description":"Custom filler profiles per category. If not specified, language-dependent defaults are used. Each category is an array of short phrases.\n\n* `positive`: Fillers for affirmative responses (e.g., \"Great!\", \"Perfect!\")\n* `negative`: Fillers for negative/neutral responses (e.g., \"Hmm.\", \"Mhm.\")\n* `question`: Fillers while processing a question (e.g., \"Good question.\", \"One moment.\")\n* `neutral`: Fillers for neutral acknowledgments (e.g., \"Okay.\", \"Understood.\")","additionalProperties":true},"record":{"type":"boolean","description":"Whether the call should be recorded","default":false},"enable_noise_cancellation":{"type":"boolean","description":"Whether noise cancellation should be enabled","default":true},"wait_for_customer":{"type":"boolean","description":"If true, the assistant waits for the customer to speak first","default":false},"max_duration":{"type":"integer","description":"Maximum call duration in seconds (20-1200)","default":600},"max_silence_duration":{"type":"integer","description":"Maximum silence duration until re-engagement in seconds (1-360)","default":40},"max_initial_silence_duration":{"type":"integer","description":"Maximum silence directly after call start before termination (1-120 seconds). Optional."},"ringing_time":{"type":"integer","description":"Maximum ringing time before canceling (1-60 seconds)","default":30},"reengagement_interval":{"type":"integer","description":"Re-engagement interval in seconds (7-600)","default":30},"reengagement_prompt":{"type":"string","description":"Custom prompt for re-engagement messages (max. 1000 characters)\n\nExample: `\"Are you still there? Do you have any other questions?\"`"},"end_call_on_voicemail":{"type":"boolean","description":"Whether to end the call if voicemail is detected","default":true},"voice_mail_message":{"type":"string","description":"Message to leave on voicemail (max. 1000 characters)"},"endpoint_type":{"type":"string","description":"Voice activity detection type. Options: `vad`, `ai`","enum":["vad","ai"],"default":"vad"},"endpoint_sensitivity":{"type":"number","description":"Endpoint sensitivity (0-5)","default":0.5},"interrupt_sensitivity":{"type":"number","description":"Interrupt sensitivity (0-5)","default":0.5},"min_interrupt_words":{"type":"integer","description":"Minimum number of words before interruption is allowed (0-10). Set to enable."},"ambient_sound":{"type":"string","description":"Background ambient sound. Options: `off`, `office`, `city`, `forest`, `crowded_room`, `cafe`, `nature`","enum":["off","office","city","forest","crowded_room","cafe","nature"]},"ambient_sound_volume":{"type":"number","description":"Ambient sound volume (0-1)","default":0.5},"is_webhook_active":{"type":"boolean","description":"Whether webhook notifications are enabled","default":false},"webhook_url":{"type":"string","description":"The webhook URL for post-call notifications. **Required if `is_webhook_active` is true.**"},"send_webhook_only_on_completed":{"type":"boolean","description":"Whether to send webhooks only for completed calls (not for failed/no-answer)","default":true},"include_recording_in_webhook":{"type":"boolean","description":"Whether to include the recording URL in the webhook payload","default":true},"post_call_evaluation":{"type":"boolean","description":"Whether AI post-call evaluation is enabled","default":true},"post_call_schema":{"type":"array","description":"Schema definition for post-call data extraction","items":{"type":"object","properties":{"name":{"type":"string","description":"Field name (3-16 characters, lowercase, alphanumeric and underscores only)"},"type":{"type":"string","description":"Data type. Options: `string`, `number`, `bool`","enum":["string","number","bool"]},"description":{"type":"string","description":"Description of what this field represents (3-255 characters)"}},"required":["name","type","description"]}},"variables":{"type":"object","description":"Key-value pairs of custom variables that can be used in prompts via `{{variable_name}}`","additionalProperties":true},"conversation_inactivity_timeout":{"type":"integer","description":"Minutes of chat inactivity before the conversation is considered ended (1–1440)","default":30},"conversation_ended_retrigger":{"type":"boolean","description":"Whether the conversation can be restarted after inactivity end","default":false},"conversation_ended_webhook_url":{"type":"string","description":"Webhook URL invoked when a chat conversation ends due to inactivity. Separate from the call webhook."}},"required":["name","voice_id","language_id","type","mode","timezone","initial_message","system_prompt"]}}}},"responses":{"201":{"description":"Success Response","content":{"application/json":{"example":{"message":"Assistant created successfully","data":{"id":789,"name":"Sales Assistant","status":"inactive","type":"outbound","mode":"pipeline"}},"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message confirming the creation of the assistant"},"data":{"type":"object","properties":{"id":{"type":"integer","description":"The unique ID of the created assistant"},"name":{"type":"string","description":"The name of the assistant"},"status":{"type":"string","description":"The current status (`inactive` for newly created assistants)"},"type":{"type":"string","description":"The type (`inbound` or `outbound`)"},"mode":{"type":"string","description":"The engine mode (`pipeline`, `multimodal`, or `dualplex`)"}},"additionalProperties":true}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"description":"Validation Error","content":{"application/json":{"example":{"message":"Validation failed","errors":{"name":["The name field is required."],"voice_id":["The selected voice is not compatible with the chosen engine type."],"knowledgebase_mode":["Only function_call mode is available for multimodal assistants."]}}}}}}}},"/user/assistant/{id}":{"delete":{"tags":["Assistants"],"summary":"Delete Assistant","operationId":"deleteAssistant","description":"Permanently delete a specific Famulor AI voice assistant via API, including its prompt, configuration and call history. This action cannot be reversed.\n\n[Docs](https://docs.famulor.io/api-v1/assistants/delete)","externalDocs":{"description":"Delete Assistant","url":"https://docs.famulor.io/api-v1/assistants/delete"},"parameters":[{"name":"id","in":"path","required":true,"description":"The unique identifier of the assistant to be deleted","schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"message":"Assistant deleted successfully"},"schema":{"type":"object","properties":{"message":{"type":"string","description":"Error message if the assistant was not found or does not belong to the authenticated user"}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not Found","content":{"application/json":{"example":{"message":"Assistant not found or does not belong to the authenticated user"}}}},"422":{"$ref":"#/components/responses/ValidationError"},"500":{"description":"Internal Server Error","content":{"application/json":{"example":{"message":"Assistant deletion failed"}}}}}},"put":{"tags":["Assistants"],"summary":"Update Assistant","operationId":"updateAssistant","description":"Update the configuration of an existing AI assistant\n\n[Docs](https://docs.famulor.io/api-v1/assistants/update)","externalDocs":{"description":"Update Assistant","url":"https://docs.famulor.io/api-v1/assistants/update"},"parameters":[{"name":"id","in":"path","required":true,"description":"The unique identifier of the assistant to be updated","schema":{"type":"integer"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The name of the assistant (max. 255 characters)"},"voice_id":{"type":"integer","description":"The voice ID to be used for the assistant. Use the [Get Voices](/en/api-reference/assistants/voices) endpoint with the `mode` parameter to get voices compatible with your engine mode."},"language_id":{"type":"integer","description":"The language ID for the assistant. Use the [Get Languages](/en/api-reference/assistants/languages) endpoint to retrieve available languages."},"type":{"type":"string","description":"The assistant type. Options: `inbound`, `outbound`","enum":["inbound","outbound"]},"mode":{"type":"string","description":"The engine mode. Options: `pipeline`, `multimodal`, `dualplex`\n\n<Warning>\nChanging the mode resets mode-specific settings to their default values for the new mode.\n</Warning>","enum":["pipeline","multimodal","dualplex"]},"timezone":{"type":"string","description":"The timezone for the assistant (e.g., \"Europe/Berlin\", \"America/New_York\")"},"initial_message":{"type":"string","description":"The initial message the assistant will speak at call start (max. 200 characters)"},"system_prompt":{"type":"string","description":"The system prompt defining the assistant's behaviour and personality"},"llm_model_id":{"type":"integer","description":"The LLM model ID to use. Only applicable in `pipeline` mode.\n\nUse the [Get Models](/en/api-reference/assistants/models) endpoint to retrieve available models."},"multimodal_model_id":{"type":"integer","description":"The multimodal model ID. Applicable only in `multimodal` and `dualplex` modes.\n\nUse the [Get Models](/en/api-reference/assistants/models) endpoint to retrieve available multimodal models."},"chat_llm_fallback_id":{"type":"integer","description":"Fallback LLM model ID for tool calls in multimodal/dualplex modes. Set to `null` to remove."},"turn_detection_threshold":{"type":"number","description":"Sensitivity of speaker turn detection for multimodal/dualplex modes (0-1). Set to `null` for automatic."},"secondary_language_ids":{"type":"array","items":{"type":"integer"},"description":"Array of additional language IDs the assistant can speak. Replaces existing secondary languages. Pass an empty array `[]` to remove all secondary languages."},"knowledgebase_id":{"type":"integer","description":"The ID of the knowledgebase to link. Set to `null` to remove."},"knowledgebase_mode":{"type":"string","description":"How to use the knowledgebase. Options:\n\n* `function_call` - AI calls a function to search (required for multimodal/dualplex)\n* `prompt` - Knowledge is injected into prompt (pipeline only)"},"folder_id":{"type":"integer","description":"ID of a [folder](/en/api-reference/folders/create) to move this assistant into. Must belong to your account. Set to `null` to make it uncategorized. Omit to leave the folder unchanged."},"label_ids":{"type":"array","items":{"type":"integer"},"description":"Array of [label](/en/api-reference/labels/create) IDs for this assistant. Each label must belong to your account. When provided, this **replaces** the assistant's current labels. Omit to leave labels unchanged; send `[]` to remove all labels."},"phone_number_id":{"type":"integer","description":"The ID of a phone number to assign. Set to `null` to unassign. Must belong to your account.\n\n<Warning>\nFor `inbound` assistants, the phone number cannot be a caller ID type and must not already be assigned to another inbound assistant.\n</Warning>"},"tool_ids":{"type":"array","items":{"type":"integer"},"description":"Array of custom mid-call tool IDs to synchronize. **Replaces all existing tool assignments.** Pass an empty array `[]` to remove all tools. Each tool must belong to your account."},"tools":{"type":"array","description":"Array of built-in tools. **Replaces all existing built-in tools.** Pass an empty array `[]` to remove all tools.\n\n\n\n<Note>\nWhen you [list assistants](/en/api-reference/assistants/list), each configured tool is returned as `{ \"type\": \"...\", \"data\": { ... } }` with the same field names nested under `data` (not top-level).\n</Note>","items":{}},"tts_emotion_enabled":{"type":"boolean","description":"Whether emotional text-to-speech synthesis is enabled"},"voice_stability":{"type":"number","description":"Voice stability setting (0-1). Higher = more consistent voice"},"voice_similarity":{"type":"number","description":"Voice similarity setting (0-1). Higher = closer to original voice"},"speech_speed":{"type":"number","description":"Speech speed multiplier (0.7-1.2)"},"llm_temperature":{"type":"number","description":"LLM temperature setting (0-1). Lower = more deterministic"},"synthesizer_provider_id":{"type":"integer","description":"Custom TTS provider ID. Set to `null` to use the system default voice. See [Get Synthesizer Providers](/en/api-reference/assistants/synthesizer-providers)."},"transcriber_provider_id":{"type":"integer","description":"Custom STT provider ID. Pipeline mode only. Set to `null` to use the system default voice. See [Get Transcriber Providers](/en/api-reference/assistants/transcriber-providers)."},"allow_interruptions":{"type":"boolean","description":"Whether caller interruptions are allowed.\n\n<Warning>Cannot be disabled in `multimodal` and `dualplex` modes.</Warning>"},"fillers":{"type":"boolean","description":"Whether filler audio should be used during processing.\n\n<Warning>Available only in `pipeline` mode.</Warning>"},"filler_config":{"type":"object","description":"Custom filler profiles per category. Replaces the existing filler configuration. Each category is an array of short phrases.\n\n* `positive`: Fillers for affirmative responses\n* `negative`: Fillers for negative/neutral responses\n* `question`: Fillers when processing a question\n* `neutral`: Fillers for neutral confirmations","additionalProperties":true},"record":{"type":"boolean","description":"Whether the call should be recorded"},"enable_noise_cancellation":{"type":"boolean","description":"Whether noise cancellation should be enabled"},"wait_for_customer":{"type":"boolean","description":"If true, the assistant waits for the customer to speak first"},"max_duration":{"type":"integer","description":"Maximum call duration in seconds (20-1200)"},"max_silence_duration":{"type":"integer","description":"Maximum silence duration before re-engagement in seconds (1-360)"},"max_initial_silence_duration":{"type":"integer","description":"Maximum silence at the start of the call before termination (1-120 seconds). Set to `null` to disable."},"ringing_time":{"type":"integer","description":"Maximum ringing time before aborting (1-60 seconds)"},"reengagement_interval":{"type":"integer","description":"Interval for re-engagement in seconds (7-600)"},"reengagement_prompt":{"type":"string","description":"Custom prompt for re-engagement messages (max. 1000 characters). Set to `null` to use the default."},"end_call_on_voicemail":{"type":"boolean","description":"Whether to end the call when voicemail is detected"},"voice_mail_message":{"type":"string","description":"Message to leave on voicemail before hanging up (max. 1000 characters). Set to `null` to disable."},"endpoint_type":{"type":"string","description":"Type of voice activity detection. Options: `vad`, `ai`","enum":["vad","ai"]},"endpoint_sensitivity":{"type":"number","description":"Endpoint sensitivity level (0-5)"},"interrupt_sensitivity":{"type":"number","description":"Interruption sensitivity level (0-5)"},"min_interrupt_words":{"type":"integer","description":"Minimum number of words before interruption is allowed (0-10). Set to `null` to disable."},"ambient_sound":{"type":"string","description":"Background ambient sound. Options: `off`, `office`, `city`, `forest`, `crowded_room`, `cafe`, `nature`","enum":["off","office","city","forest","crowded_room","cafe","nature"]},"ambient_sound_volume":{"type":"number","description":"Volume of the ambient sound (0-1)"},"is_webhook_active":{"type":"boolean","description":"Whether webhook notifications are enabled"},"webhook_url":{"type":"string","description":"The webhook URL for post-call notifications. Set to `null` to remove."},"send_webhook_only_on_completed":{"type":"boolean","description":"Whether webhooks should be sent only for successfully completed calls (not on failed/no-answer)"},"include_recording_in_webhook":{"type":"boolean","description":"Whether the recording URL should be included in the webhook payload"},"post_call_evaluation":{"type":"boolean","description":"Whether AI-based post-call evaluation is enabled"},"post_call_schema":{"type":"array","description":"Schema definition for extracting post-call data. Replaces the existing schema.","items":{"type":"object","properties":{"name":{"type":"string","description":"Field name (3-16 characters, lowercase, alphanumeric and underscores only)"},"type":{"type":"string","description":"Data type. Options: `string`, `number`, `bool`","enum":["string","number","bool"]},"description":{"type":"string","description":"Description of what this field represents (3-255 characters)"}},"required":["name","type","description"]}},"variables":{"type":"object","description":"Key-value pairs for custom variables. **Replaces all existing variables.**","additionalProperties":true}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"message":"Assistant updated successfully","data":{"id":789,"name":"Updated Sales Assistant","status":"active","type":"outbound","mode":"pipeline"}},"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message confirming the assistant update"},"data":{"type":"object","properties":{"id":{"type":"integer","description":"The unique ID of the updated assistant"},"name":{"type":"string","description":"The assistant’s name"},"status":{"type":"string","description":"The current status of the assistant"},"type":{"type":"string","description":"The type (`inbound` or `outbound`)"},"mode":{"type":"string","description":"The engine mode (`pipeline`, `multimodal`, or `dualplex`)"}},"additionalProperties":true}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not Found","content":{"application/json":{"example":{"message":"Assistant not found"}}}},"422":{"description":"Validation Error","content":{"application/json":{"example":{"message":"Validation failed","errors":{"speech_speed":["Speech speed must be between 0.7 and 1.2."],"voice_id":["The selected voice is not compatible with the selected engine type."],"allow_interruptions":["Interruptions cannot be disabled in multimodal or dualplex mode."]}}}}}}}},"/user/assistants/disable-conversation-ended-webhook":{"post":{"tags":["Assistants"],"summary":"Disable conversation ended webhook","operationId":"disableConversationEndedWebhook","description":"Disable conversation ended webhook notifications for an assistant\n\n[Docs](https://docs.famulor.io/api-v1/assistants/disable-conversation-ended-webhook)","externalDocs":{"description":"Disable conversation ended webhook","url":"https://docs.famulor.io/api-v1/assistants/disable-conversation-ended-webhook"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assistant_id":{"type":"integer","description":"The ID of the assistant to disable the conversation ended webhook for"}},"required":["assistant_id"]}}}},"responses":{"200":{"description":"Success Response","content":{"application/json":{"example":{"message":"Conversation ended webhook disabled successfully","data":[]},"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message confirming webhook was disabled"},"data":{"type":"array","description":"Empty array (reserved for future use)","items":{}},"404 Not Found":{"type":"string"},"422 Validation Error":{"type":"string"}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not Found","content":{"application/json":{"example":{"message":"Assistant not found"}}}},"422":{"description":"Validation Error","content":{"application/json":{"example":{"message":"The given data was invalid.","errors":{"assistant_id":["The assistant id field is required."]}}}}}}}},"/user/assistants/disable-inbound-webhook":{"post":{"tags":["Assistants"],"summary":"Disable assistant inbound webhook","operationId":"disableAssistantInboundWebhook","description":"Turn off inbound webhook notifications for an assistant\n\n[Docs](https://docs.famulor.io/api-v1/assistants/disable-inbound-webhook)","externalDocs":{"description":"Disable assistant inbound webhook","url":"https://docs.famulor.io/api-v1/assistants/disable-inbound-webhook"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assistant_id":{"type":"integer","description":"The identifier of the assistant to disable inbound webhooks for"}},"required":["assistant_id"]}}}},"responses":{"200":{"description":"Success Response","content":{"application/json":{"example":{"message":"Inbound webhook disabled successfully","data":[]},"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success confirmation message"},"data":{"type":"array","description":"Empty array (reserved for future functionality)","items":{}},"404 Not Found":{"type":"string"},"422 Validation Error":{"type":"string"}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not Found","content":{"application/json":{"example":{"message":"Assistant not found"}}}},"422":{"description":"Validation Error","content":{"application/json":{"example":{"message":"The given data was invalid.","errors":{"assistant_id":["The assistant id field is required."]}}}}}}}},"/user/assistants/disable-webhook":{"post":{"tags":["Assistants"],"summary":"Disable assistant webhook","operationId":"disableAssistantWebhook","description":"Turn off webhook notifications for a specific Famulor AI assistant via API. Stops automated event delivery for call ended, lead created, and other triggers.\n\n[Docs](https://docs.famulor.io/api-v1/assistants/disable-webhook)","externalDocs":{"description":"Disable assistant webhook","url":"https://docs.famulor.io/api-v1/assistants/disable-webhook"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assistant_id":{"type":"integer","description":"The identifier of the assistant to disable webhooks for"}},"required":["assistant_id"]}}}},"responses":{"200":{"description":"Success Response","content":{"application/json":{"example":{"message":"Webhook disabled successfully","data":[]},"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success confirmation message"},"data":{"type":"array","description":"Empty array (reserved for future functionality)","items":{}},"404 Not Found":{"type":"string"},"422 Validation Error":{"type":"string"}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not Found","content":{"application/json":{"example":{"message":"Assistant not found"}}}},"422":{"description":"Validation Error","content":{"application/json":{"example":{"message":"The given data was invalid.","errors":{"assistant_id":["The assistant id field is required."]}}}}}}}},"/user/assistants/enable-conversation-ended-webhook":{"post":{"tags":["Assistants"],"summary":"Enable Conversation Ended Webhook","operationId":"enableConversationEndedWebhook","description":"Enable conversation-ended webhook notifications for chat conversations\n\n[Docs](https://docs.famulor.io/api-v1/assistants/enable-conversation-ended-webhook)","externalDocs":{"description":"Enable Conversation Ended Webhook","url":"https://docs.famulor.io/api-v1/assistants/enable-conversation-ended-webhook"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assistant_id":{"type":"integer","description":"The assistant ID for which the webhook should be enabled"},"webhook_url":{"type":"string","description":"HTTPS URL that will receive conversation-ended webhook payloads"}},"required":["assistant_id","webhook_url"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"message":"Conversation ended webhook enabled successfully","data":[]},"schema":{"type":"object","properties":{"message":{"type":"string","description":"Confirmation that the webhook has been enabled"},"data":{"type":"array","description":"Empty array (reserved for future extensions)","items":{}}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/user/assistants/enable-inbound-webhook":{"post":{"tags":["Assistants"],"summary":"Enable assistant inbound webhook","operationId":"enableAssistantInboundWebhook","description":"Activate inbound webhook notifications for an assistant\n\n[Docs](https://docs.famulor.io/api-v1/assistants/enable-inbound-webhook)","externalDocs":{"description":"Enable assistant inbound webhook","url":"https://docs.famulor.io/api-v1/assistants/enable-inbound-webhook"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assistant_id":{"type":"integer","description":"The identifier of the assistant to enable webhooks for"},"webhook_url":{"type":"string","description":"The endpoint URL where notifications will be sent"}},"required":["assistant_id","webhook_url"]}}}},"responses":{"200":{"description":"Success Response","content":{"application/json":{"example":{"message":"Webhook enabled successfully","data":[]},"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success confirmation message"},"data":{"type":"array","description":"Empty array (reserved for future functionality)","items":{}},"404 Not Found":{"type":"string"},"422 Validation Error":{"type":"string"}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not Found","content":{"application/json":{"example":{"message":"Assistant not found"}}}},"422":{"description":"Validation Error","content":{"application/json":{"example":{"message":"The given data was invalid.","errors":{"assistant_id":["The assistant id field is required."],"webhook_url":["The webhook url field is required."]}}}}}}}},"/user/assistants/get":{"get":{"tags":["Assistants"],"summary":"List Assistants","operationId":"listAssistants","description":"List all assistants for the authenticated user with pagination\n\n[Docs](https://docs.famulor.io/api-v1/assistants/list)","externalDocs":{"description":"List Assistants","url":"https://docs.famulor.io/api-v1/assistants/list"},"parameters":[{"name":"per_page","in":"query","required":false,"description":"Number of assistants per page (1-100, default: 10)","schema":{"type":"integer"}},{"name":"page","in":"query","required":false,"description":"Page number (default: 1)","schema":{"type":"integer"}}],"responses":{"200":{"description":"Response","content":{"application/json":{"example":{"data":[{"id":123,"user_id":456,"phone_number_id":789,"engine_id":1,"synthesizer_id":2,"transcriber_id":3,"voice_id":4,"instance_id":5,"name":"Sales Assistant","variables":{"company_name":"Famulor","product_focus":"AI Telephony"},"post_call_evaluation":true,"fillers":1,"post_call_schema":[{"name":"customer_interested","type":"boolean","description":"Is the customer interested?"}],"tools":[{"type":"end_call","data":{"description":"End call when done"}},{"type":"assistant_transfer","data":{"description":"Transfer to the Support Assistant when the customer needs technical help.","assistant_id":13766,"message_before_transfer":"Sure — let me transfer you to our support specialist.","speak_transfer_greeting":true}},{"type":"warm_call_transfer","data":{"supervisor_phone":"+14155552001","outbound_phone_id":"7","description":"Transfer the call to a human supervisor when the customer requests to speak with a real person.","custom_sip":false,"caller_id_mode":"outbound_number","hold_music":"hold_music","hold_music_volume":80,"hold_message":"Please hold while I connect you with a supervisor.","summary_instructions":"Introduce the conversation from your perspective:\n- WHO is calling (name, company if mentioned)\n- WHY they called (their goal or problem)\n- WHY a human is needed at this point\n\nKeep it brief (2-3 sentences).","briefing_initial_message":"Hello! I have a caller on the line who needs your assistance. May I brief you on the situation?","connected_message":"You are now connected with a supervisor. I'll leave you to it."}}],"is_webhook_active":true,"webhook_url":"https://example.com/webhook","inbound_webhook_url":"https://example.com/inbound-webhook","language":"de","type":"outbound","status":"active","max_duration":1800,"record":true,"initial_message":"Good day! I'm calling from Famulor...","system_prompt":"You are a friendly sales assistant...","flows_platform_id":null,"timezone":"Europe/Berlin","created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-15T10:30:00Z","max_silence_duration":3,"reengagement_interval":5,"deleted_at":null,"end_call_on_voicemail":1,"llm_temperature":"0.7","voice_stability":"0.8","voice_similarity":"0.9","allow_interruptions":true,"enable_noise_cancellation":true,"endpoint_sensitivity":0.5,"speech_speed":"1.0","endpoint_type":"vad","wait_for_customer":false,"mode":"pipeline","language_id":1,"transcriber_provider_id":1,"synthesizer_provider_id":1,"llm_model_id":1,"multimodal_model_id":null,"ambient_sound":"office","uuid":"550e8400-e29b-41d4-a716-446655440000","send_webhook_only_on_completed":true,"include_recording_in_webhook":false,"interrupt_sensitivity":0.3,"filler_config":{"enabled":true,"phrases":["Hmm...","I understand..."]},"knowledgebase_id":100,"knowledgebase_mode":"semantic","min_interrupt_words":2,"ambient_sound_volume":"0.3","widget_settings":{"enabled":false}}],"current_page":1,"per_page":10,"total":1,"last_page":1},"schema":{"type":"object","properties":{"data":{"type":"array","description":"Array of assistants","items":{"type":"object","properties":{"id":{"type":"integer","description":"The unique identifier of the assistant"},"user_id":{"type":"integer","description":"The ID of the user who owns this assistant"},"phone_number_id":{"type":"integer","description":"The ID of the phone number assigned to the assistant"},"engine_id":{"type":"integer","description":"Engine ID"},"synthesizer_id":{"type":"integer","description":"Synthesizer ID"},"transcriber_id":{"type":"integer","description":"Transcriber ID"},"voice_id":{"type":"integer","description":"The ID of the voice used by the assistant"},"instance_id":{"type":"integer","description":"The instance ID for the assistant"},"name":{"type":"string","description":"The name of the assistant"},"variables":{"type":"object","description":"Custom variables for the assistant","additionalProperties":true},"post_call_evaluation":{"type":"boolean","description":"Whether post-call evaluation is enabled"},"fillers":{"type":"integer","description":"Whether filler audio is enabled (1 = enabled, 0 = disabled)"},"post_call_schema":{"type":"array","description":"Schema definition for post-call data extraction","items":{}},"tools":{"type":"array","description":"Array of built-in tools configured on the assistant. Each item has `type` (tool identifier) and `data` (tool-specific settings). This response shape differs from the flat object used in [Create](/en/api-reference/assistants/create) and [Update](/en/api-reference/assistants/update) requests.","items":{}},"is_webhook_active":{"type":"boolean","description":"Whether webhook notifications are enabled"},"webhook_url":{"type":"string","description":"The webhook URL for post-call notifications"},"inbound_webhook_url":{"type":"string","description":"The webhook URL for inbound call notifications"},"language":{"type":"string","description":"Language"},"type":{"type":"string","description":"The type of assistant (inbound or outbound)"},"status":{"type":"string","description":"The current status of the assistant (active or inactive)"},"max_duration":{"type":"integer","description":"Maximum call duration in seconds"},"record":{"type":"boolean","description":"Whether calls should be recorded"},"initial_message":{"type":"string","description":"The first message the assistant will speak"},"system_prompt":{"type":"string","description":"The system prompt that defines the assistant's behavior"},"flows_platform_id":{"type":["integer","null"],"description":"ID for Flows platform integration"},"timezone":{"type":"string","description":"The timezone setting for the assistant"},"created_at":{"type":"string","description":"Date and time when the assistant was created"},"updated_at":{"type":"string","description":"Date and time of the last update to the assistant"},"max_silence_duration":{"type":"integer","description":"Maximum silence duration in seconds before re-engagement"},"reengagement_interval":{"type":"integer","description":"Re-engagement interval in seconds"},"deleted_at":{"type":["string","null"],"description":"Soft deletion timestamp (null if not deleted)"},"end_call_on_voicemail":{"type":"integer","description":"Whether the call should end upon voicemail detection (1 = yes, 0 = no)"},"llm_temperature":{"type":"string","description":"LLM temperature setting as a string"},"voice_stability":{"type":"string","description":"Voice stability setting as a string"},"voice_similarity":{"type":"string","description":"Voice similarity setting as a string"},"allow_interruptions":{"type":"boolean","description":"Whether interruptions by the caller are allowed"},"enable_noise_cancellation":{"type":"boolean","description":"Whether noise cancellation is enabled"},"endpoint_sensitivity":{"type":"number","description":"Endpoint sensitivity level"},"speech_speed":{"type":"string","description":"Speech speed multiplier as a string"},"endpoint_type":{"type":"string","description":"Voice activity detection type (vad or ai)"},"wait_for_customer":{"type":"boolean","description":"Whether to wait for the first customer speech input"},"mode":{"type":"string","description":"The engine mode (pipeline or multimodal)"},"language_id":{"type":"integer","description":"The ID of the language used by the assistant"},"transcriber_provider_id":{"type":"integer","description":"ID of the transcriber provider"},"synthesizer_provider_id":{"type":"integer","description":"ID of the synthesizer provider"},"llm_model_id":{"type":"integer","description":"ID of the LLM model used"},"multimodal_model_id":{"type":["integer","null"],"description":"ID of the multimodal model used"},"ambient_sound":{"type":"string","description":"Ambient sound setting"},"uuid":{"type":"string","description":"Unique UUID for the assistant"},"send_webhook_only_on_completed":{"type":"boolean","description":"Whether webhooks are sent only for completed calls"},"include_recording_in_webhook":{"type":"boolean","description":"Whether recording URL should be included in webhook payload"},"interrupt_sensitivity":{"type":"number","description":"Interruption sensitivity level"},"filler_config":{"type":"object","description":"Configuration for filler audio responses","additionalProperties":true},"knowledgebase_id":{"type":"integer","description":"ID of the associated knowledge base"},"knowledgebase_mode":{"type":"string","description":"Knowledge base mode setting"},"min_interrupt_words":{"type":"integer","description":"Minimum number of words before interruption is allowed"},"ambient_sound_volume":{"type":"string","description":"Ambient sound volume as a string"},"widget_settings":{"type":"object","description":"Settings for web widget integration","additionalProperties":true},"ringing_time":{"type":"integer","description":"Ring time in seconds before ending the call"},"max_initial_silence_duration":{"type":"integer","description":"Maximum initial silence duration in seconds"}},"additionalProperties":true}},"current_page":{"type":"integer","description":"The current page number"},"per_page":{"type":"integer","description":"Number of items per page"},"total":{"type":"integer","description":"Total number of assistants"},"last_page":{"type":"integer","description":"The last page number"}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/user/assistants/languages":{"get":{"tags":["Assistants"],"summary":"Retrieve Available Languages","operationId":"retrieveAvailableLanguages","description":"Retrieve all available languages for assistant configuration\n\n[Docs](https://docs.famulor.io/api-v1/assistants/languages)","externalDocs":{"description":"Retrieve Available Languages","url":"https://docs.famulor.io/api-v1/assistants/languages"},"responses":{"200":{"description":"Response","content":{"application/json":{"example":[{"id":1,"name":"English","iso_2":"en"},{"id":2,"name":"Romanian","iso_2":"ro"},{"id":3,"name":"French","iso_2":"fr"},{"id":4,"name":"Spanish","iso_2":"es"},{"id":5,"name":"German","iso_2":"de"},{"id":6,"name":"Lithuanian","iso_2":"lt"},{"id":7,"name":"Italian","iso_2":"it"},{"id":8,"name":"Arabic","iso_2":"ar"},{"id":9,"name":"Portuguese","iso_2":"pt"},{"id":10,"name":"Danish","iso_2":"da"}],"schema":{"type":"array","items":{"type":"object","properties":{"array":{"type":"array","description":"Array of available languages","items":{"type":"object","properties":{"id":{"type":"integer","description":"The unique identifier of the language"},"name":{"type":"string","description":"The display name of the language"},"iso_2":{"type":"string","description":"The ISO 639-1 two-letter language code"}},"additionalProperties":true}}},"additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/user/assistants/models":{"get":{"tags":["Assistants"],"summary":"Retrieve Available Models","operationId":"retrieveAvailableModels","description":"Retrieve available AI models for assistant configuration\n\n[Docs](https://docs.famulor.io/api-v1/assistants/models)","externalDocs":{"description":"Retrieve Available Models","url":"https://docs.famulor.io/api-v1/assistants/models"},"parameters":[{"name":"type","in":"query","required":false,"description":"The type of models to retrieve, based on the engine mode:\n\n* `llm` - LLM models for the **pipeline** mode (default)\n* `multimodal` - Multimodal models for the **multimodal** mode\n* `dualplex` - Multimodal models for the **dualplex** mode","schema":{"type":"string","default":"llm"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"examples":{"llm-models-type-llm":{"summary":"LLM Models (type=llm)","value":[{"id":1,"name":"GPT-4o-mini"},{"id":2,"name":"GPT-4.1-mini"}]},"multimodal-dualplex-models-type-multimodal-or-type-dualplex":{"summary":"Multimodal/Dualplex Models (type=multimodal or type=dualplex)","value":[{"id":1,"name":"GPT-4o","code":"gpt-4o-realtime"},{"id":4,"name":"GPT Realtime","code":"gpt-realtime"}]}},"schema":{"type":"array","items":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"The unique identifier of the model"},"name":{"type":"string","description":"The display name of the model"},"code":{"type":"string","description":"The internal code (only for multimodal/dualplex models)"}},"additionalProperties":true}}},"additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/user/assistants/outbound":{"get":{"tags":["Assistants"],"summary":"Get outbound assistants","operationId":"getOutboundAssistants","description":"Retrieve all outbound assistants for the authenticated user\n\n[Docs](https://docs.famulor.io/api-v1/assistants/outbound)","externalDocs":{"description":"Get outbound assistants","url":"https://docs.famulor.io/api-v1/assistants/outbound"},"responses":{"200":{"description":"Response","content":{"application/json":{"example":[{"id":123,"user_id":1,"name":"Sales Outbound Assistant","type":"outbound","mode":"pipeline","status":"active","voice_id":8,"language_id":1,"timezone":"America/New_York","initial_message":"Hi, this is Sarah from Your Company. I hope I'm catching you at a good time. How are you doing today?","system_prompt":"You are a sales representative for Your Company. Be professional, friendly, and focus on qualifying leads.","variables":{"company_name":"Your Company","product_line":"Premium Services"},"webhook_url":"https://yourcompany.com/api/webhooks/outbound-calls","is_webhook_active":true,"created_at":"2025-07-15T14:32:15.000000Z","updated_at":"2025-08-02T09:18:42.000000Z"},{"id":124,"user_id":1,"name":"Follow-up Assistant","type":"outbound","mode":"multimodal","status":"inactive","voice_id":12,"language_id":1,"timezone":"America/Los_Angeles","initial_message":"Hello! I'm calling to follow up on our previous conversation. Do you have a few minutes to chat?","system_prompt":"You are a follow-up specialist. Be warm and professional while gathering feedback and next steps.","variables":{"purpose":"follow_up","max_duration":"5_minutes"},"webhook_url":null,"is_webhook_active":false,"created_at":"2025-07-20T10:15:30.000000Z","updated_at":"2025-07-25T16:45:22.000000Z"}],"schema":{"type":"array","items":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"The unique identifier of the assistant"},"user_id":{"type":"integer","description":"The ID of the user who owns this assistant"},"name":{"type":"string","description":"The name of the assistant"},"type":{"type":"string","description":"The type of assistant (will always be \"outbound\" for this endpoint)"},"mode":{"type":"string","description":"The engine mode (`pipeline` or `multimodal`)"},"status":{"type":"string","description":"The current status of the assistant"},"voice_id":{"type":"integer","description":"The ID of the voice used by the assistant"},"language_id":{"type":"integer","description":"The ID of the language used by the assistant"},"timezone":{"type":"string","description":"The timezone setting for the assistant"},"initial_message":{"type":"string","description":"The initial message the assistant will speak"},"system_prompt":{"type":"string","description":"The system prompt that defines the assistant's behavior"},"variables":{"type":"object","description":"Custom variables defined for the assistant","additionalProperties":true},"webhook_url":{"type":"string","description":"The webhook URL for post-call notifications"},"is_webhook_active":{"type":"boolean","description":"Whether webhook notifications are enabled"},"created_at":{"type":"string","description":"The date and time when the assistant was created"},"updated_at":{"type":"string","description":"The date and time when the assistant was last updated"}},"additionalProperties":true}}},"additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/user/assistants/phone-numbers":{"get":{"tags":["Assistants"],"summary":"Retrieve Available Phone Numbers","operationId":"retrieveAvailablePhoneNumbers","description":"Retrieve all available phone numbers for assistant assignment\n\n[Docs](https://docs.famulor.io/api-v1/assistants/phone-numbers)","externalDocs":{"description":"Retrieve Available Phone Numbers","url":"https://docs.famulor.io/api-v1/assistants/phone-numbers"},"parameters":[{"name":"type","in":"query","required":false,"description":"Filter phone numbers by assistant type. Options: `inbound`, `outbound`","schema":{"type":"string","enum":["inbound","outbound"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"examples":{"response":{"summary":"Response","value":[{"id":2103,"phone_number":"+491748236179","country_code":"DE","type_label":"Caller ID","is_available":true},{"id":2131,"phone_number":"+4915792613301","country_code":"DE","type_label":"Caller ID","is_available":true}]},"inbound-only-available-numbers":{"summary":"Inbound-only available numbers","value":[{"id":2103,"phone_number":"+491748236179","country_code":"DE","type_label":"Caller ID","is_available":true},{"id":2131,"phone_number":"+4915792613301","country_code":"DE","type_label":"Caller ID","is_available":true}]}},"schema":{"type":"array","items":{"type":"object","properties":{"array":{"type":"array","description":"Array of available phone numbers","items":{"type":"object","properties":{"id":{"type":"integer","description":"The unique identifier of the phone number"},"phone_number":{"type":"string","description":"The phone number in E.164 format"},"country_code":{"type":"string","description":"The country code of the phone number"},"type_label":{"type":"string","description":"The human-readable type label for the phone number"},"is_available":{"type":"boolean","description":"Whether the phone number is available for assignment (not currently assigned to an inbound assistant)"}},"additionalProperties":true}}},"additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/user/assistants/synthesizer-providers":{"get":{"tags":["Assistants"],"summary":"List synthesizer providers","operationId":"listSynthesizerProviders","description":"Retrieve available TTS (text-to-speech) synthesizer providers\n\n[Docs](https://docs.famulor.io/api-v1/assistants/synthesizer-providers)","externalDocs":{"description":"List synthesizer providers","url":"https://docs.famulor.io/api-v1/assistants/synthesizer-providers"},"parameters":[{"name":"language_id","in":"query","required":false,"description":"Filter providers by language support. Only providers that support the given language are returned. Use the [Get Languages](/en/api-reference/assistants/languages) endpoint to fetch available language IDs.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"examples":{"response":{"summary":"Response","value":[{"id":1,"name":"ElevenLabs","code":"elevenlabs"},{"id":2,"name":"Azure","code":"azure"},{"id":3,"name":"Cartesia","code":"cartesia"}]},"filtered-by-language":{"summary":"Filtered by language","value":[{"id":1,"name":"ElevenLabs","code":"elevenlabs"},{"id":3,"name":"Cartesia","code":"cartesia"}]}},"schema":{"type":"array","items":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier of the provider. Use this as `synthesizer_provider_id` when creating or updating assistants."},"name":{"type":"string","description":"Display name of the provider (e.g. \"ElevenLabs\", \"Azure\", \"Cartesia\")."},"code":{"type":"string","description":"Internal code of the provider."}},"additionalProperties":true}}},"additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/user/assistants/transcriber-providers":{"get":{"tags":["Assistants"],"summary":"List transcriber providers","operationId":"listTranscriberProviders","description":"Retrieve available STT (speech-to-text) transcriber providers\n\n[Docs](https://docs.famulor.io/api-v1/assistants/transcriber-providers)","externalDocs":{"description":"List transcriber providers","url":"https://docs.famulor.io/api-v1/assistants/transcriber-providers"},"parameters":[{"name":"language_id","in":"query","required":false,"description":"Filter providers by language support. Only providers that support the given language are returned. Use the [Get Languages](/en/api-reference/assistants/languages) endpoint to fetch available language IDs.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Response","content":{"application/json":{"example":[{"id":1,"name":"Deepgram","code":"deepgram"},{"id":2,"name":"Azure","code":"azure"},{"id":3,"name":"Gladia","code":"gladia"}],"schema":{"type":"array","items":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier of the provider. Use this as `transcriber_provider_id` when creating or updating assistants."},"name":{"type":"string","description":"Display name of the provider (e.g. \"Deepgram\", \"Azure\", \"Gladia\")."},"code":{"type":"string","description":"Internal code of the provider."}},"additionalProperties":true}}},"additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/user/assistants/voices":{"get":{"tags":["Assistants"],"summary":"Retrieve Available Voices","operationId":"retrieveAvailableVoices","description":"Retrieve all available voices for assistant configuration\n\n[Docs](https://docs.famulor.io/api-v1/assistants/voices)","externalDocs":{"description":"Retrieve Available Voices","url":"https://docs.famulor.io/api-v1/assistants/voices"},"parameters":[{"name":"mode","in":"query","required":false,"description":"Filter voices by assistant mode. Options: `pipeline`, `multimodal`, `dualplex`","schema":{"type":"string","enum":["pipeline","multimodal","dualplex"]}},{"name":"language_id","in":"query","required":false,"description":"Filter voices by language ID. Use the [Retrieve Languages](/en/api-reference/assistants/languages) endpoint to get available language IDs.","schema":{"type":"integer"}}],"responses":{"200":{"description":"response","content":{"application/json":{"example":[{"id":1,"name":"Alloy","language_id":1,"gender":"female","preview_url":"https://cdn.openai.com/API/voice-previews/alloy.flac","accent":null,"age":"Middle aged","synthesizer_provider_id":null},{"id":10,"name":"Zephyr","language_id":1,"gender":"female","preview_url":"https://gstatic.com/aistudio/voices/samples/Zephyr.wav","accent":null,"age":"Middle aged","synthesizer_provider_id":1},{"id":11,"name":"Puck","language_id":1,"gender":"male","preview_url":"https://gstatic.com/aistudio/voices/samples/Puck.wav","accent":null,"age":"Middle aged","synthesizer_provider_id":1}],"schema":{"type":"array","items":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"The unique identifier of the voice"},"name":{"type":"string","description":"The display name of the voice"},"language_id":{"type":"integer","description":"The language ID associated with this voice"},"gender":{"type":"string","description":"The gender of the voice (male/female)"},"preview_url":{"type":"string","description":"URL to an audio sample of the voice. Can be used to allow users to preview the voice before selecting it."},"accent":{"type":"string","description":"The accent of the voice (e.g., \"American\", \"British\"). Can be `null`."},"age":{"type":"string","description":"The age category of the voice (e.g., \"Young\", \"Middle aged\"). Can be `null`."},"synthesizer_provider_id":{"type":"integer","description":"The TTS provider ID to which this voice belongs. Use the [Retrieve Synthesizer Providers](/en/api-reference/assistants/synthesizer-providers) endpoint to resolve provider names. Can be `null`."}},"additionalProperties":true}}},"additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/user/automate/flows":{"post":{"tags":["Automations"],"summary":"Create automation","operationId":"createAutomation","description":"Create a Famulor automation from a definition, activate it, and prove it with a real test run.\n\n[Docs](https://docs.famulor.io/api-v1/automations/create)","externalDocs":{"description":"Create automation","url":"https://docs.famulor.io/api-v1/automations/create"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"A short human name for the automation (max 255 characters)"},"flow":{"type":"object","description":"The automation definition — `{\"trigger\": {...}, \"steps\": [...]}` as described above. Max 1 MB.","additionalProperties":true},"sample":{"type":"object","description":"A realistically-shaped sample payload for the test run (what the trigger will receive). For assistant events, a canonical sample built from the assistant’s own variables is used when omitted. Max 256 KB.","additionalProperties":true},"assistant_id":{"type":"integer","description":"Required for assistant-event automations (`phoneCallEnded`, `inboundCall`, `newConversation`, and `bind_webhook`): the assistant this automation attaches to. It starts receiving that assistant’s real events after the test passes. (For the platform triggers, selecting the assistant inside the trigger’s `settings.input.assistant` also works — the explicit parameter wins.)"},"bind_webhook":{"type":"string","description":"For a webhook-triggered definition only: attach it to the assistant’s conversation-ended event. The only supported value is `conversation_ended`. Requires `assistant_id`."},"confirm_side_effects":{"type":"boolean","description":"Required (`true`) when the definition contains steps that send messages or emails, start calls, or make non-GET HTTP requests — the test run executes them for real."}},"required":["name","flow"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"examples":{"created-webhook-test-passed":{"summary":"Created (webhook, test passed)","value":{"automation_id":"f4EaLhOW2zoEsXXSOJP2r","webhook_url":"https://automate.famulor.ai/api/v1/webhooks/f4EaLhOW2zoEsXXSOJP2r","status":"active","test":{"run_status":"SUCCEEDED","steps":[{"name":"trigger","status":"SUCCEEDED","classification":"ok","error":null},{"name":"step_1","status":"SUCCEEDED","classification":"ok","error":null}]},"response":{"ok":"true","echo":"hello"},"binding":null}},"created-schedule-active-untested":{"summary":"Created (schedule, active_untested)","value":{"automation_id":"aB3xYz01MnOpQrStUvWxY","webhook_url":null,"status":"active_untested","test":{"run_status":"not_tested","steps":[]},"response":null,"binding":null}}},"schema":{"type":"object","properties":{"automation_id":{"type":"string","description":"The ID of the created automation"},"webhook_url":{"type":["string","null"],"description":"For webhook-triggered automations (including conversation-ended ones): the URL external systems call to fire it. `null` for assistant-event and schedule automations."},"status":{"type":"string","description":"`active` — the test run passed; the automation is live (and attached, for assistant events).\n`active_untested` — the trigger cannot be fired on demand (schedules, external integrations); the automation is live and armed, and the first real event is the proof.\n`test_failed` — the test run failed; the automation was left disabled. Read `test.steps` for the per-step classification."},"test":{"type":"object","description":"The test run result","properties":{"run_status":{"type":"string","description":"`SUCCEEDED`, `PAUSED`, `FAILED`, or `not_tested` (untestable triggers); rarely `no_run` when the test produced no execution record. `PAUSED` counts as success: the run is parked at a Delay step waiting for its target time — every step before the delay already ran."},"steps":{"type":"array","description":"Per-step outcome of the test run","items":{"type":"object","properties":{"name":{"type":"string","description":"The step name (`trigger`, `step_1`, …)"},"status":{"type":"string","description":"`SUCCEEDED`, `FAILED` or `PAUSED`"},"classification":{"type":"string","description":"`ok`, `paused_at_delay`, or — for failures — `wiring_error` (the definition is wrong: fix it and repair via [Update automation](/en/api-reference/automations/update)), `missing_connection` (an account must be connected in the Famulor app first), `missing_record` (the sample referenced data that does not exist — often fine)."},"error":{"type":["string","null"],"description":"The step’s error message, when it failed"}},"additionalProperties":true}}},"additionalProperties":true},"response":{"type":["object","string","null"],"description":"For synchronously-tested automations (webhook and inbound triggers): what the automation responded during the test run","additionalProperties":true},"binding":{"type":["object","null"],"description":"For assistant-event automations: `{\"type\": \"post_call\" | \"inbound\" | \"conversation\" | \"conversation_ended\", \"assistant_id\": <id>, \"bound\": <bool>}`. `bound` is `true` only after a green test.","additionalProperties":true}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"description":"Validation Error","content":{"application/json":{"example":{"message":"This automation contains steps that would REALLY send messages, emails or start calls during the test run: Send SMS. Confirm with the user first — point those steps at a safe recipient the user owns — then retry with confirm_side_effects set to true.","error":"side_effects_require_confirmation"}}}}}},"get":{"tags":["Automations"],"summary":"List automations","operationId":"listAutomations","description":"List every Famulor automation in your account, including status and assistant bindings.\n\n[Docs](https://docs.famulor.io/api-v1/automations/list)","externalDocs":{"description":"List automations","url":"https://docs.famulor.io/api-v1/automations/list"},"responses":{"200":{"description":"Response","content":{"application/json":{"example":{"data":[{"id":"OaeThAHzIjAPTmMJAhgwm","name":"Qualified leads to Google Sheets","status":"enabled","binding":{"type":"post_call","assistant_id":123,"assistant_name":"Sales Assistant"}},{"id":"nCazgFt1COAmGVgCWkvxY","name":"Daily call report (17:00)","status":"disabled","binding":null}]},"schema":{"type":"object","properties":{"data":{"type":"array","description":"The list of automations","items":{"type":"object","properties":{"id":{"type":"string","description":"The unique ID of the automation. Use it with the other automation endpoints."},"name":{"type":"string","description":"The display name of the automation"},"status":{"type":"string","description":"`enabled` (live, reacting to events) or `disabled` (off — a failed test run or an explicit disable)"},"binding":{"type":["object","null"],"description":"Present when the automation is attached to one of your assistants’ events, otherwise `null`","properties":{"type":{"type":"string","description":"The assistant event this automation reacts to: `post_call`, `inbound`, `conversation` or `conversation_ended`"},"assistant_id":{"type":"integer","description":"The ID of the assistant it is attached to"},"assistant_name":{"type":"string","description":"The name of the assistant it is attached to"}},"additionalProperties":true}},"additionalProperties":true}}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/user/automate/flows/{id}":{"delete":{"tags":["Automations"],"summary":"Delete automation","operationId":"deleteAutomation","description":"Permanently delete a Famulor automation from your account.\n\n[Docs](https://docs.famulor.io/api-v1/automations/delete)","externalDocs":{"description":"Delete automation","url":"https://docs.famulor.io/api-v1/automations/delete"},"parameters":[{"name":"id","in":"path","required":true,"description":"The ID of the automation (from [List automations](/en/api-reference/automations/list))","schema":{"type":"string"}}],"responses":{"200":{"description":"Response","content":{"application/json":{"example":{"message":"Automation deleted successfully"},"schema":{"type":"object","properties":{"message":{"type":"string","description":"`Automation deleted successfully`"}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not Found","content":{"application/json":{"example":{"message":"Automation not found"}}}},"422":{"$ref":"#/components/responses/ValidationError"}}},"get":{"tags":["Automations"],"summary":"Get automation","operationId":"getAutomation","description":"Get a single Famulor automation, including its full definition (trigger and chained steps).\n\n[Docs](https://docs.famulor.io/api-v1/automations/get)","externalDocs":{"description":"Get automation","url":"https://docs.famulor.io/api-v1/automations/get"},"parameters":[{"name":"id","in":"path","required":true,"description":"The ID of the automation (from [List automations](/en/api-reference/automations/list))","schema":{"type":"string"}},{"name":"include_secrets","in":"query","required":false,"description":"By default, credential-bearing values inside the definition (API keys, tokens, Authorization headers) are masked as `••• hidden`. Pass `true` to return them unmasked.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Response","content":{"application/json":{"example":{"data":{"id":"f4EaLhOW2zoEsXXSOJP2r","name":"Order lookup","status":"enabled","updated_at":"2026-07-24T18:23:57.259Z","definition":{"name":"trigger","type":"PIECE_TRIGGER","displayName":"Catch Webhook","settings":{"pieceName":"@activepieces/piece-webhook","triggerName":"catch_webhook"},"nextAction":{"name":"step_1","type":"PIECE","displayName":"Look up the order","settings":{"pieceName":"@activepieces/piece-http","actionName":"send_request","input":{"url":"https://api.example.com/orders","method":"GET","headers":{"Authorization":"••• hidden"}}}}},"binding":null}},"schema":{"type":"object","properties":{"data":{"type":"object","description":"The automation","properties":{"id":{"type":"string","description":"The unique ID of the automation"},"name":{"type":"string","description":"The display name of the automation"},"status":{"type":"string","description":"`enabled` or `disabled`"},"updated_at":{"type":"string","description":"When the automation was last updated"},"definition":{"type":"object","description":"The automation’s definition: the trigger object with its steps chained under `nextAction`. This is the artifact you edit and send back through [Update automation](/en/api-reference/automations/update) to repair or extend the automation. See [Create automation](/en/api-reference/automations/create) for the definition format.","additionalProperties":true},"binding":{"type":["object","null"],"description":"When the automation is attached to an assistant event: `{type, assistant_id, assistant_name}` (see [List automations](/en/api-reference/automations/list)). Otherwise `null`.","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not Found","content":{"application/json":{"example":{"message":"Automation not found"}}}},"422":{"$ref":"#/components/responses/ValidationError"}}},"put":{"tags":["Automations"],"summary":"Update automation","operationId":"updateAutomation","description":"Rename a Famulor automation, turn it on or off, or repair it with a corrected definition.\n\n[Docs](https://docs.famulor.io/api-v1/automations/update)","externalDocs":{"description":"Update automation","url":"https://docs.famulor.io/api-v1/automations/update"},"parameters":[{"name":"id","in":"path","required":true,"description":"The ID of the automation (from [List automations](/en/api-reference/automations/list))","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"A new name for the automation (max 255 characters). In repair mode, the current name is kept when omitted."},"enabled":{"type":"boolean","description":"`true` to turn the automation on, `false` to turn it off"},"flow":{"type":"object","description":"Repair mode: the corrected full definition, in the same format as [Create automation](/en/api-reference/automations/create) (`{\"trigger\": {...}, \"steps\": [...]}`). Max 1 MB.","additionalProperties":true},"sample":{"type":"object","description":"Sample payload for the repair test run (for assistant events, the canonical sample is used when omitted). Max 256 KB.","additionalProperties":true},"assistant_id":{"type":"integer","description":"For repairs of assistant-event automations: the assistant to (re)attach to. Usually already carried inside the definition’s trigger."},"confirm_side_effects":{"type":"boolean","description":"Required (`true`) when the corrected definition contains steps that send messages or emails, start calls, or make non-GET HTTP requests"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"examples":{"response-rename-disable":{"summary":"Response (rename + disable)","value":{"data":{"id":"f4EaLhOW2zoEsXXSOJP2r","name":"Order lookup v2","status":"disabled","updated":true}}},"response-repair-test-passed":{"summary":"Response (repair, test passed)","value":{"automation_id":"f4EaLhOW2zoEsXXSOJP2r","status":"active","test":{"run_status":"SUCCEEDED","steps":[]},"response":null,"binding":null}}},"schema":{"type":"object","properties":{"data":{"type":"object","description":"The refreshed automation summary","properties":{"id":{"type":"string","description":"The automation ID"},"name":{"type":"string","description":"The automation’s (possibly new) name"},"status":{"type":"string","description":"`enabled` or `disabled`"},"updated":{"type":"boolean","description":"Whether every requested change was applied"}},"additionalProperties":true}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not Found","content":{"application/json":{"example":{"message":"Automation not found"}}}},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/user/automate/flows/{id}/restore":{"post":{"tags":["Automations"],"summary":"Restore previous version","operationId":"restorePreviousVersion","description":"Roll a Famulor automation back to its previous published version.\n\n[Docs](https://docs.famulor.io/api-v1/automations/restore)","externalDocs":{"description":"Restore previous version","url":"https://docs.famulor.io/api-v1/automations/restore"},"parameters":[{"name":"id","in":"path","required":true,"description":"The ID of the automation (from [List automations](/en/api-reference/automations/list))","schema":{"type":"string"}}],"responses":{"200":{"description":"Response","content":{"application/json":{"example":{"automation_id":"f4EaLhOW2zoEsXXSOJP2r","name":"Order lookup","status":"enabled","restored_version_id":"8auMJQtqBnE1X8ZP7WVnI","note":"Rolled back to the previous published version and re-published it live."},"schema":{"type":"object","properties":{"automation_id":{"type":"string","description":"The automation’s ID"},"name":{"type":"string","description":"The automation’s name after the restore"},"status":{"type":"string","description":"`enabled` or `disabled` — the on/off state the automation had going into the restore is preserved"},"restored_version_id":{"type":"string","description":"The ID of the version that is now live"},"note":{"type":"string","description":"Confirmation that the previous version was restored and re-published"}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not Found","content":{"application/json":{"example":{"message":"Automation not found, or it does not belong to your account.","error":"not_found"}}}},"422":{"description":"Validation Error","content":{"application/json":{"example":{"message":"There is no earlier version of this automation to roll back to.","error":"no_previous_version"}}}}}}},"/user/automate/flows/{id}/runs":{"get":{"tags":["Automations"],"summary":"List automation runs","operationId":"listAutomationRuns","description":"List a Famulor automation’s recent executions, or one execution’s step-by-step detail.\n\n[Docs](https://docs.famulor.io/api-v1/automations/list-runs)","externalDocs":{"description":"List automation runs","url":"https://docs.famulor.io/api-v1/automations/list-runs"},"parameters":[{"name":"id","in":"path","required":true,"description":"The ID of the automation (from [List automations](/en/api-reference/automations/list))","schema":{"type":"string"}},{"name":"run_id","in":"query","required":false,"description":"A run ID from the list — returns that run’s step-by-step detail instead of the list","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"How many recent runs to list (1–20, default 10)","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"examples":{"response-list":{"summary":"Response (list)","value":{"runs":[{"id":"yHhXbqWj3zJZ5ztDNfUry","status":"SUCCEEDED","start_time":"2026-07-24T18:23:59.634Z","duration_ms":1},{"id":"x2PqLm90AbCdEfGhIjKlM","status":"FAILED","start_time":"2026-07-24T17:10:12.000Z","duration_ms":410}]}},"response-detail":{"summary":"Response (detail)","value":{"run":{"id":"x2PqLm90AbCdEfGhIjKlM","status":"FAILED","start_time":"2026-07-24T17:10:12.000Z","duration_ms":410,"steps":[{"name":"trigger","status":"SUCCEEDED","classification":"ok","error":null},{"name":"step_1","status":"FAILED","classification":"missing_connection","error":"Request failed with status code 401"}]}}}},"schema":{"type":"object","properties":{"runs":{"type":"array","description":"The automation’s recent executions, newest first","items":{"type":"object","properties":{"id":{"type":"string","description":"The run ID — pass it back as `run_id` for the step-by-step detail, or to [Retry automation run](/en/api-reference/automations/retry-run) for a failed run"},"status":{"type":"string","description":"`SUCCEEDED`, `FAILED`, `PAUSED` (parked at a Delay step waiting for its target time — not a failure) or `RUNNING`"},"start_time":{"type":"string","description":"When the run started"},"duration_ms":{"type":"integer","description":"The run’s duration in milliseconds"}},"additionalProperties":true}},"run":{"type":"object","description":"The execution’s detail","properties":{"id":{"type":"string","description":"The run ID"},"status":{"type":"string","description":"`SUCCEEDED`, `FAILED`, `PAUSED` or `RUNNING`"},"start_time":{"type":"string","description":"When the run started"},"duration_ms":{"type":"integer","description":"The run’s duration in milliseconds"},"steps":{"type":"array","description":"Per-step outcome — same shape as the `test.steps` of [Create automation](/en/api-reference/automations/create): `{name, status, classification, error}`, where `classification` is `ok`, `paused_at_delay`, `wiring_error`, `missing_connection` or `missing_record`","items":{}}},"additionalProperties":true}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not Found","content":{"application/json":{"example":{"message":"Run not found for this automation"}}}},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/user/automate/flows/{id}/runs/{run_id}/retry":{"post":{"tags":["Automations"],"summary":"Retry automation run","operationId":"retryAutomationRun","description":"Retry a failed Famulor automation run from its failed step without re-executing succeeded steps.\n\n[Docs](https://docs.famulor.io/api-v1/automations/retry-run)","externalDocs":{"description":"Retry automation run","url":"https://docs.famulor.io/api-v1/automations/retry-run"},"parameters":[{"name":"id","in":"path","required":true,"description":"The ID of the automation (from [List automations](/en/api-reference/automations/list))","schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"description":"The ID of the failed run (from [List automation runs](/en/api-reference/automations/list-runs))","schema":{"type":"string"}}],"responses":{"200":{"description":"Response","content":{"application/json":{"example":{"run_id":"yHhXbqWj3zJZ5ztDNfUry","status":"RUNNING","note":"Retried FROM the failed step — steps that already succeeded were NOT re-executed, so their side effects were not repeated."},"schema":{"type":"object","properties":{"run_id":{"type":"string","description":"The retried run’s ID (the same run that was passed in)"},"status":{"type":"string","description":"The run’s status right after the retry (e.g. `RUNNING`, or `SUCCEEDED` when it finished instantly)"},"note":{"type":"string","description":"Confirmation that already-succeeded steps were not re-executed"}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not Found","content":{"application/json":{"example":{"message":"Run not found for this automation.","error":"not_found"}}}},"422":{"description":"Validation Error","content":{"application/json":{"example":{"message":"The retry did not resume this run (its status is still 'FAILED') — its saved state is likely stale, most commonly because the run passed through a Delay step before failing. This run cannot be resumed as-is. To force a fresh full run (re-executes EVERY step, including any that already sent a message/email/call — get the user's explicit confirmation first, then rebuild via update-automation's repair path), or otherwise wait for the automation's next real trigger event.","error":"retry_no_op"}}}}}}},"/user/automate/templates":{"get":{"tags":["Automations"],"summary":"List automation templates","operationId":"listAutomationTemplates","description":"List ready-made Famulor automation templates and the parameters each one needs.\n\n[Docs](https://docs.famulor.io/api-v1/automations/list-templates)","externalDocs":{"description":"List automation templates","url":"https://docs.famulor.io/api-v1/automations/list-templates"},"responses":{"200":{"description":"Response (truncated)","content":{"application/json":{"example":{"data":[{"key":"post-call-qualified-to-sheets","name":"Save qualified leads to Google Sheets","description":"After each call, if the AI marked the caller as qualified, appends a row (phone, name, summary, status) to your Google Sheet.","use_when":"The user wants qualified calls or call outcomes collected in a spreadsheet automatically.","binding":"post_call","requires_assistant":true,"required_connections":["google-sheets"],"side_effects":false,"params":[{"key":"spreadsheet_id","label":"Google Spreadsheet ID","description":"The spreadsheet to append rows to.","required":true,"example":"1AbCdEfGhIjKlMnOpQrStUvWxYz"},{"key":"qualified_variable","label":"Qualified variable name","description":"The post-call variable checked for true before saving (the assistant must extract it).","required":false,"default":"status","example":"qualified"}]}]},"schema":{"type":"object","properties":{"data":{"type":"array","description":"The template library","items":{"type":"object","properties":{"key":{"type":"string","description":"The template key — pass it in the URL of [Apply automation template](/en/api-reference/automations/apply-template)"},"name":{"type":"string","description":"The template’s name (also the default name of the automation it creates)"},"description":{"type":"string","description":"What the resulting automation does"},"use_when":{"type":"string","description":"When this template is the right choice"},"binding":{"type":["string","null"],"description":"The assistant event the resulting automation attaches to (`post_call`, `inbound`, `conversation_ended`), or `null` for templates that do not attach to an assistant event"},"requires_assistant":{"type":"boolean","description":"Whether `assistant_id` is required when applying it"},"required_connections":{"type":"array","description":"Account connections that must exist before applying (e.g. `google-sheets`, `gmail`)","items":{}},"side_effects":{"type":"boolean","description":"Whether the resulting automation really sends messages / starts calls — applying it requires `confirm_side_effects: true`"},"params":{"type":"array","description":"The parameters the template needs","items":{"type":"object","properties":{"key":{"type":"string","description":"The parameter key to send in `params` when applying"},"label":{"type":"string","description":"Human-readable label"},"description":{"type":"string","description":"What the value is and where to find it"},"required":{"type":"boolean","description":"Whether the parameter must be supplied"},"default":{"type":"string","description":"The value used when the parameter is omitted (optional parameters only)"},"example":{"type":"string","description":"An example value — for illustration only, never apply a template with example values"},"auto":{"type":"string","description":"Present on some optional parameters: how the value is filled automatically when omitted (e.g. `assistant_timezone` — the supplied assistant’s own timezone)"}},"additionalProperties":true}},"test_sample":{"type":"object","description":"Present on some templates: the sample payload their test run uses","additionalProperties":true}},"additionalProperties":true}}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/user/automate/templates/{key}":{"post":{"tags":["Automations"],"summary":"Apply automation template","operationId":"applyAutomationTemplate","description":"Create a Famulor automation from a ready-made template and prove it with a real test run.\n\n[Docs](https://docs.famulor.io/api-v1/automations/apply-template)","externalDocs":{"description":"Apply automation template","url":"https://docs.famulor.io/api-v1/automations/apply-template"},"parameters":[{"name":"key","in":"path","required":true,"description":"The template key (from [List automation templates](/en/api-reference/automations/list-templates)). An unknown key returns a `404`.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"params":{"type":"object","description":"The template’s parameters as key-value pairs — see the template’s `params` list for what each one needs. Missing required parameters return a `422` (`missing_params`) listing exactly what is needed. Max 64 KB.","additionalProperties":true},"assistant_id":{"type":"integer","description":"The assistant the resulting automation attaches to. Required for templates with `requires_assistant: true`."},"name":{"type":"string","description":"A custom name for the automation (max 255 characters); defaults to the template name"},"confirm_side_effects":{"type":"boolean","description":"Required (`true`) for templates marked `side_effects: true`"}}}}}},"responses":{"201":{"description":"Created (test passed and attached)","content":{"application/json":{"example":{"automation_id":"aB3xYz01MnOpQrStUvWxY","webhook_url":null,"status":"active","test":{"run_status":"SUCCEEDED","steps":[]},"response":null,"binding":{"type":"post_call","assistant_id":123,"bound":true}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not Found","content":{"application/json":{"example":{"message":"No template with that key — call the template list first.","error":"template_not_found","params":null}}}},"422":{"description":"Validation Error","content":{"application/json":{"example":{"message":"These values are required: spreadsheet_id. Ask the user for them — never guess or reuse example values.","error":"missing_params","params":[{"key":"spreadsheet_id","label":"Google Spreadsheet ID","description":"The spreadsheet to append rows to.","required":true,"example":"1AbCdEfGhIjKlMnOpQrStUvWxYz"}]}}}}}}},"/user/calls":{"get":{"tags":["Calls"],"summary":"List Calls","operationId":"listCalls","description":"List all calls for the authenticated user with filtering options\n\n[Docs](https://docs.famulor.io/api-v1/calls/list)","externalDocs":{"description":"List Calls","url":"https://docs.famulor.io/api-v1/calls/list"},"parameters":[{"name":"status","in":"query","required":false,"description":"Filter calls by status. Possible values: `initiated`, `ringing`, `busy`, `in-progress`, `ended`, `completed`, `ended_by_customer`, `ended_by_assistant`, `no-answer`, `failed`","schema":{"type":"string","enum":["initiated","ringing","busy","in-progress","ended","completed","ended_by_customer","ended_by_assistant","no-answer","failed"]}},{"name":"type","in":"query","required":false,"description":"Filter calls by type. Possible values: `inbound`, `outbound`, `web`","schema":{"type":"string","enum":["inbound","outbound","web"]}},{"name":"phone_number","in":"query","required":false,"description":"Filter calls by client phone number","schema":{"type":"string"}},{"name":"assistant_id","in":"query","required":false,"description":"Filter calls by assistant ID","schema":{"type":"integer"}},{"name":"campaign_id","in":"query","required":false,"description":"Filter calls by campaign ID","schema":{"type":"integer"}},{"name":"date_from","in":"query","required":false,"description":"Filter calls from this date (YYYY-MM-DD format)","schema":{"type":"string"}},{"name":"date_to","in":"query","required":false,"description":"Filter calls up to this date (YYYY-MM-DD format)","schema":{"type":"string"}},{"name":"per_page","in":"query","required":false,"description":"Number of calls per page (1-100, default: 15)","schema":{"type":"integer"}},{"name":"page","in":"query","required":false,"description":"Page number (default: 1)","schema":{"type":"integer"}}],"responses":{"200":{"description":"Response","content":{"application/json":{"example":{"data":[{"id":123456,"assistant_name":"Sales Assistant","campaign_name":"Neukundenakquise Q1 2024","type":"outbound","duration":180,"assistant_phone_number":"+4912345678","client_phone_number":"+4915123456789","status":"completed","transcript":[{"text":"Hallo, mein Name ist Maximilian, ich melde mich im Auftrag eines IT-Unternehmens.","type":"transcript","sender":"bot","timestamp":1754055268.525861},{"text":"Hallo?","type":"transcript","sender":"human","timestamp":1754055272.069057}],"variables":{"customer_name":"John"},"evaluation":[{"name":"status","type":"bool","value":true,"description":"Whether the call objective was achieved or not."},{"name":"summary","type":"string","value":"Connected to the customer, obtained name of the person responsible for IT.","description":"Call summary in a few words."}],"webhook_response":{"crm_updated":true,"lead_score":75},"carrier_cost":"0.08000000","total_cost":"0.12000000","answered_by":"human","recording_url":"https://recordings.famulor.de/call-123456.mp3","created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-15T10:33:00Z"},{"id":123457,"assistant_name":"Support Assistant","campaign_name":null,"type":"inbound","duration":120,"assistant_phone_number":"+4912345678","client_phone_number":"+4917123456789","status":"ended_by_customer","transcript":[{"text":"Kunde: Hallo, ich habe eine Frage zu meinem Konto.","type":"transcript","sender":"human","timestamp":1754055300.123456},{"text":"Gerne helfe ich Ihnen dabei. Was kann ich für Sie tun?","type":"transcript","sender":"bot","timestamp":1754055302.789012}],"variables":{"issue_resolved":true,"satisfaction_rating":9},"evaluation":[{"name":"issue_resolved","type":"bool","value":true,"description":"Whether the customer's issue was resolved."},{"name":"satisfaction_rating","type":"integer","value":9,"description":"Customer satisfaction rating from 1-10."}],"webhook_response":null,"carrier_cost":"0.05000000","total_cost":"0.08000000","answered_by":"human","recording_url":null,"created_at":"2024-01-15T14:20:00Z","updated_at":"2024-01-15T14:22:00Z"}],"current_page":1,"first_page_url":"https://app.famulor.de/api/user/calls?page=1","from":1,"last_page":4,"last_page_url":"https://app.famulor.de/api/user/calls?page=4","links":[{"url":null,"label":"&laquo; Previous","active":false},{"url":"https://app.famulor.de/api/user/calls?page=1","label":"1","active":true}],"next_page_url":"https://app.famulor.de/api/user/calls?page=2","path":"https://app.famulor.de/api/user/calls","per_page":15,"prev_page_url":null,"to":15,"total":52},"schema":{"type":"object","properties":{"data":{"type":"array","description":"Array of calls","items":{"type":"object","properties":{"id":{"type":"integer","description":"The unique identifier of the call"},"assistant_name":{"type":"string","description":"The name of the assistant who handled the call"},"campaign_name":{"type":["string","null"],"description":"The name of the campaign to which this call belongs (if applicable)"},"type":{"type":"string","description":"The type of the call (inbound, outbound, or web)"},"duration":{"type":"integer","description":"The duration of the call in seconds"},"assistant_phone_number":{"type":"string","description":"The phone number used by the assistant"},"client_phone_number":{"type":"string","description":"The client's phone number"},"status":{"type":"string","description":"The current status of the call"},"transcript":{"type":"array","description":"The transcript of the call conversation as an array of objects containing text, type, sender, and timestamp","items":{}},"variables":{"type":"object","description":"Variables collected during the call","additionalProperties":true},"evaluation":{"type":"array","description":"Evaluation data for call performance as an array of objects with name, type, value, and description","items":{}},"webhook_response":{"type":["object","null"],"description":"Response from configured webhooks","additionalProperties":true},"carrier_cost":{"type":"string","description":"The cost charged by the carrier for this call"},"total_cost":{"type":"string","description":"The total cost of the call including all fees"},"answered_by":{"type":"string","description":"Who answered the call (human, machine, or unknown)"},"recording_url":{"type":["string","null"],"description":"URL to the call recording (if available and enabled)"},"created_at":{"type":"string","description":"Date and time when the call was created"},"updated_at":{"type":"string","description":"Date and time of the last update to the call"}},"additionalProperties":true}},"current_page":{"type":"integer","description":"The current page number"},"per_page":{"type":"integer","description":"Number of items per page"},"total":{"type":"integer","description":"Total number of calls matching the criteria"},"last_page":{"type":"integer","description":"The last page number"},"first_page_url":{"type":"string","description":"URL of the first page"},"last_page_url":{"type":"string","description":"URL of the last page"},"next_page_url":{"type":"string","description":"URL of the next page, or `null`"},"prev_page_url":{"type":["string","null"],"description":"URL of the previous page, or `null`"},"path":{"type":"string","description":"Base pagination path"}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/user/calls/{id}":{"get":{"tags":["Account"],"summary":"Get Call","operationId":"getCall","description":"Retrieve full details of a specific Famulor call by ID via API, including transcript, recording URL, duration, status and metadata from the AI voice assistant.\n\n[Docs](https://docs.famulor.io/api-v1/user/calls/get)","externalDocs":{"description":"Get Call","url":"https://docs.famulor.io/api-v1/user/calls/get"},"parameters":[{"name":"id","in":"path","required":true,"description":"The unique identifier of the call","schema":{"type":"integer"}}],"responses":{"200":{"description":"Response","content":{"application/json":{"example":{"id":123,"assistant_name":"Sales Assistant","campaign_name":"Q4 Outreach Campaign","type":"outbound","duration":245,"assistant_phone_number":"+1234567890","client_phone_number":"+1987654321","status":"completed","transcript":[{"text":"Hello, this is Sarah from Famulor. How are you doing today?","type":"transcript","sender":"bot","timestamp":1754055268.525861}],"variables":[],"evaluation":[{"name":"status","type":"string","value":"qualified_lead","description":"Outcome of the call"}],"webhook_response":{"status":"success","data":{"crm_contact_id":"abc123"}},"carrier_cost":"0.02000000","total_cost":"0.02500000","answered_by":null,"recording_url":"https://app.famulor.de/media/public/123/call_+491234567890_example.mp4","created_at":"2025-08-04 14:30:00","updated_at":"2025-08-04 14:34:05"},"schema":{"type":"object","properties":{"id":{"type":"integer","description":"The unique identifier of the call"},"assistant_name":{"type":"string","description":"The name of the assistant that handled the call"},"campaign_name":{"type":"string","description":"The name of the campaign this call belongs to (if applicable)"},"type":{"type":"string","description":"The type of call (inbound, outbound or web)"},"duration":{"type":"integer","description":"The duration of the call in seconds"},"assistant_phone_number":{"type":"string","description":"The phone number used by the assistant"},"client_phone_number":{"type":"string","description":"The customer's phone number"},"status":{"type":"string","description":"The current status of the call"},"transcript":{"type":"array","description":"The transcript of the call conversation as an array of entries","items":{}},"variables":{"type":["object","array"],"description":"Variables collected during the call","additionalProperties":true},"evaluation":{"type":"array","description":"Evaluation data for call performance as an array of fields","items":{}},"webhook_response":{"type":"object","description":"Response from configured webhooks","additionalProperties":true},"carrier_cost":{"type":"string","description":"The carrier-calculated costs for this call"},"total_cost":{"type":"string","description":"The total cost of the call including all fees"},"answered_by":{"type":["string","null"],"description":"Who answered the call (human, machine or unknown), or `null`"},"recording_url":{"type":"string","description":"URL to the call recording (if available and enabled)"},"created_at":{"type":"string","description":"Date and time the call was created"},"updated_at":{"type":"string","description":"Date and time the call was last updated"}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Response","content":{"application/json":{"example":{"message":"Call not found"}}}},"422":{"$ref":"#/components/responses/ValidationError"}}},"delete":{"tags":["Calls"],"summary":"Delete Call","operationId":"deleteCall","description":"Delete a specific call record from the Famulor system via API. Permanently removes transcripts, recordings and metadata for that voice agent call.\n\n[Docs](https://docs.famulor.io/api-v1/calls/delete)","externalDocs":{"description":"Delete Call","url":"https://docs.famulor.io/api-v1/calls/delete"},"parameters":[{"name":"id","in":"path","required":true,"description":"The unique identifier of the call to be deleted","schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"message":"Call deleted successfully"},"schema":{"type":"object","properties":{"message":{"type":"string","description":"Error message if the call was not found or does not belong to the authenticated user"}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not Found","content":{"application/json":{"example":{"message":"Call not found or does not belong to the authenticated user"}}}},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/user/campaign":{"post":{"tags":["Campaigns"],"summary":"Create campaign","operationId":"createCampaign","description":"Create a draft call, WhatsApp, or SMS campaign in Famulor via API. Add leads, then start with Update campaign status.\n\n[Docs](https://docs.famulor.io/api-v1/campaigns/create)","externalDocs":{"description":"Create campaign","url":"https://docs.famulor.io/api-v1/campaigns/create"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Campaign name. Maximum 255 characters."},"channel":{"type":"string","description":"`call`, `whatsapp`, or `sms`.","default":"call"},"timezone":{"type":"string","description":"IANA timezone for the send/call window (e.g. `America/New_York`). Defaults to the assistant timezone for call campaigns, otherwise your account timezone."},"schedule_windows":{"type":"array","description":"Preferred schedule: one or more daily windows as objects with `start` and `end` in `HH:MM`. Overnight windows are supported when `end` is earlier than `start` (e.g. `16:00` → `02:00`).","items":{}},"allowed_hours_start_time":{"type":"string","description":"Legacy single-window start (`HH:MM`). Used if `schedule_windows` is omitted.","default":"00:00"},"allowed_hours_end_time":{"type":"string","description":"Legacy single-window end (`HH:MM`). Overnight when `end` &lt; `start`.","default":"23:59"},"scheduled_start_at":{"type":"string","description":"Optional ISO datetime. When set, the campaign can be scheduled to auto-start at that time."},"allowed_days":{"type":"array","description":"Weekdays: `monday` … `sunday`.","items":{}},"max_retries":{"type":"integer","description":"Max retry attempts per lead. Range: 1–5.","default":3},"retry_interval":{"type":"integer","description":"Minutes between retries. Range: 10–4320.","default":60},"mark_complete_when_no_leads":{"type":"boolean","description":"Automatically mark the campaign complete when no remaining work is left.","default":true},"assistant_id":{"type":"integer","description":"Required for `channel=call`. Must be an OUTBOUND assistant you own."},"max_calls_in_parallel":{"type":"integer","description":"Concurrent calls (plan-bounded, max 10).","default":3},"phone_number_ids":{"type":"array","description":"Outbound from-number IDs available to your account.","items":{}},"retry_on_voicemail":{"type":"boolean","description":"Retry when a call hits voicemail."},"retry_on_goal_incomplete":{"type":"boolean","description":"Keep retrying until a boolean post-call goal variable is true."},"goal_completion_variable":{"type":"string","description":"Boolean post-call schema variable name used with `retry_on_goal_incomplete`."},"fallback_channel":{"type":"string","description":"Optional call→text follow-up after max call retries: `whatsapp` or `sms`."},"fallback_whatsapp_sender_id":{"type":"integer","description":"Required when `fallback_channel=whatsapp`."},"fallback_whatsapp_template_id":{"type":"integer","description":"Required when `fallback_channel=whatsapp`. Must be an approved template on that sender."},"fallback_sms_from_phone_number_id":{"type":"integer","description":"Required when `fallback_channel=sms`."},"fallback_sms_body":{"type":"string","description":"Required when `fallback_channel=sms`. Supports `{{variable}}` placeholders."},"fallback_variable_mapping":{"type":"object","description":"Maps WhatsApp template placeholders (e.g. `\"1\"`) to lead variable keys for the fallback send.","additionalProperties":true},"whatsapp_sender_id":{"type":"integer","description":"Required for `channel=whatsapp`. Sender you own."},"whatsapp_template_id":{"type":"integer","description":"Required for `channel=whatsapp`. Approved template on that sender."},"text_variable_mapping":{"type":"object","description":"Maps template placeholders (e.g. `\"1\"`) to lead variable keys.","additionalProperties":true},"messages_per_minute":{"type":"integer","description":"Per-campaign send rate (1–10). WhatsApp campaigns also share a user-wide pool of 10 in-flight sends across all your active WhatsApp campaigns."},"sms_from_phone_number_id":{"type":"integer","description":"Required for `channel=sms`. Must be SMS-capable and available to you."},"sms_body":{"type":"string","description":"Required for `channel=sms`. Max 1600 characters. Supports `{{variable}}` placeholders."}},"required":["name"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"example":{"message":"Campaign created successfully","data":{"id":1,"name":"Product Demo Campaign","channel":"call","status":"draft","assistant_id":42,"timezone":"Europe/Berlin","max_calls_in_parallel":3,"messages_per_minute":null,"schedule_windows":[{"start":"09:00","end":"17:00"}],"scheduled_start_at":null,"allowed_hours_start_time":"09:00","allowed_hours_end_time":"17:00","allowed_days":["monday","tuesday","wednesday","thursday","friday"],"max_retries":3,"retry_interval":60,"retry_on_voicemail":false,"retry_on_goal_incomplete":false,"goal_completion_variable":null,"mark_complete_when_no_leads":true,"phone_number_ids":[101],"whatsapp_sender_id":null,"whatsapp_template_id":null,"sms_from_phone_number_id":null,"sms_body":null,"text_variable_mapping":null,"fallback_channel":null,"fallback_whatsapp_sender_id":null,"fallback_whatsapp_template_id":null,"fallback_sms_from_phone_number_id":null,"fallback_sms_body":null,"fallback_variable_mapping":null,"created_at":"2026-02-23T10:00:00.000000Z","updated_at":"2026-02-23T10:00:00.000000Z"}},"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message"},"data":{"type":"object","description":"Created campaign (same shape as [Get campaign](/en/api-reference/campaigns/get)), including channel, schedule, text config, and fallback fields.","additionalProperties":true},"422 Unprocessable Entity":{"type":"string","description":"Plan limit, invalid assistant/sender/template, disabled channel, or validation errors."}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"description":"Unprocessable Entity","content":{"application/json":{"example":{"message":"The given data was invalid.","errors":{"name":["The name field is required."],"assistant_id":["The assistant id field is required."]}}}}}}}},"/user/campaign/{id}":{"delete":{"tags":["Campaigns"],"summary":"Delete campaign","operationId":"deleteCampaign","description":"Delete an outbound calling campaign via API. Running campaigns are stopped automatically before removal; leads and phone number assignments are released.\n\n[Docs](https://docs.famulor.io/api-v1/campaigns/delete)","externalDocs":{"description":"Delete campaign","url":"https://docs.famulor.io/api-v1/campaigns/delete"},"parameters":[{"name":"id","in":"path","required":true,"description":"The unique identifier of the campaign to delete","schema":{"type":"integer"}}],"responses":{"200":{"description":"Success Response","content":{"application/json":{"example":{"message":"Campaign deleted successfully"},"schema":{"type":"object","properties":{"message":{"type":"string","description":"Confirmation message indicating the campaign was deleted successfully"},"404 Not Found":{"type":"string"}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not Found","content":{"application/json":{"example":{"message":"Campaign not found"}}}},"422":{"$ref":"#/components/responses/ValidationError"}}},"get":{"tags":["Campaigns"],"summary":"Get campaign","operationId":"getCampaign","description":"Get a single Famulor campaign by ID via API. Returns channel, schedule windows, WhatsApp/SMS config, and optional call→text fallback fields.\n\n[Docs](https://docs.famulor.io/api-v1/campaigns/get)","externalDocs":{"description":"Get campaign","url":"https://docs.famulor.io/api-v1/campaigns/get"},"parameters":[{"name":"id","in":"path","required":true,"description":"Campaign ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"Response","content":{"application/json":{"example":{"data":{"id":1,"name":"New Customer Acquisition Q1 2026","channel":"call","status":"draft","assistant_id":42,"timezone":"Europe/Berlin","max_calls_in_parallel":3,"messages_per_minute":null,"schedule_windows":[{"start":"09:00","end":"18:00"}],"scheduled_start_at":null,"allowed_hours_start_time":"09:00","allowed_hours_end_time":"18:00","allowed_days":["monday","tuesday","wednesday","thursday","friday"],"max_retries":3,"retry_interval":60,"retry_on_voicemail":true,"retry_on_goal_incomplete":false,"goal_completion_variable":null,"mark_complete_when_no_leads":true,"phone_number_ids":[101],"whatsapp_sender_id":null,"whatsapp_template_id":null,"sms_from_phone_number_id":null,"sms_body":null,"text_variable_mapping":null,"fallback_channel":null,"fallback_whatsapp_sender_id":null,"fallback_whatsapp_template_id":null,"fallback_sms_from_phone_number_id":null,"fallback_sms_body":null,"fallback_variable_mapping":null,"created_at":"2026-01-10T08:00:00Z","updated_at":"2026-01-10T08:00:00Z"}},"schema":{"type":"object","properties":{"data":{"type":"object","description":"Full campaign object including channel, `schedule_windows`, WhatsApp/SMS config, and fallback fields.","additionalProperties":true},"404 Not Found":{"type":"string","description":"Campaign does not exist or does not belong to you."}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not Found","content":{"application/json":{"example":{"message":"Campaign not found"}}}},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/user/campaigns":{"get":{"tags":["Campaigns"],"summary":"List Campaigns","operationId":"listCampaigns","description":"List all campaigns (call, WhatsApp, SMS) in your Famulor account via API. View channel, schedule windows, WhatsApp/SMS config, and optional call→text fallback settings.\n\n[Docs](https://docs.famulor.io/api-v1/campaigns/list)","externalDocs":{"description":"List Campaigns","url":"https://docs.famulor.io/api-v1/campaigns/list"},"responses":{"200":{"description":"Response","content":{"application/json":{"example":[{"id":1,"name":"New Customer Acquisition Q1 2026","channel":"call","status":"in-progress","assistant_id":42,"timezone":"Europe/Berlin","max_calls_in_parallel":5,"messages_per_minute":null,"schedule_windows":[{"start":"09:00","end":"18:00"}],"scheduled_start_at":null,"allowed_hours_start_time":"09:00","allowed_hours_end_time":"18:00","allowed_days":["monday","tuesday","wednesday","thursday","friday"],"max_retries":3,"retry_interval":60,"retry_on_voicemail":true,"retry_on_goal_incomplete":false,"goal_completion_variable":null,"mark_complete_when_no_leads":true,"phone_number_ids":[101,102],"whatsapp_sender_id":null,"whatsapp_template_id":null,"sms_from_phone_number_id":null,"sms_body":null,"text_variable_mapping":null,"fallback_channel":"whatsapp","fallback_whatsapp_sender_id":7,"fallback_whatsapp_template_id":15,"fallback_sms_from_phone_number_id":null,"fallback_sms_body":null,"fallback_variable_mapping":{"1":"first_name"},"created_at":"2026-01-10T08:00:00Z","updated_at":"2026-01-15T14:30:00Z"}],"schema":{"type":"array","items":{"type":"object","properties":{"array":{"type":"array","description":"Array of all campaigns","items":{"type":"object","properties":{"id":{"type":"integer","description":"Campaign ID"},"name":{"type":"string","description":"Campaign name"},"channel":{"type":"string","description":"`call`, `whatsapp`, or `sms`"},"status":{"type":"string","description":"e.g. `draft`, `scheduled`, `in-progress`, `paused`, `completed`"},"assistant_id":{"type":"integer","description":"OUTBOUND assistant ID (call campaigns). `null` for text campaigns."},"timezone":{"type":"string","description":"IANA timezone for the send/call window"},"max_calls_in_parallel":{"type":"integer","description":"Concurrent call slots (call campaigns)"},"messages_per_minute":{"type":"integer","description":"Per-campaign text send rate (WhatsApp/SMS). WhatsApp also uses a user-wide in-flight pool of 10."},"schedule_windows":{"type":"array","description":"Daily windows `[{ \"start\": \"HH:MM\", \"end\": \"HH:MM\" }]`. Overnight allowed when `end` &lt; `start`.","items":{}},"scheduled_start_at":{"type":"string","description":"ISO datetime for auto-start, or `null`"},"allowed_hours_start_time":{"type":"string","description":"Legacy window start (kept in sync with the first schedule window)"},"allowed_hours_end_time":{"type":"string","description":"Legacy window end"},"allowed_days":{"type":"array","description":"Weekdays when sending/calling is allowed","items":{}},"max_retries":{"type":"integer","description":"Max retries per lead"},"retry_interval":{"type":"integer","description":"Minutes between retries"},"retry_on_voicemail":{"type":"boolean","description":"Call campaigns: retry on voicemail"},"retry_on_goal_incomplete":{"type":"boolean","description":"Call campaigns: retry until goal variable is true"},"goal_completion_variable":{"type":"string","description":"Boolean post-call variable name, or `null`"},"mark_complete_when_no_leads":{"type":"boolean","description":"Auto-complete when no work remains"},"phone_number_ids":{"type":"array","description":"Outbound from-number IDs (call campaigns)","items":{}},"whatsapp_sender_id":{"type":"integer","description":"WhatsApp sender ID, or `null`"},"whatsapp_template_id":{"type":"integer","description":"WhatsApp template ID, or `null`"},"sms_from_phone_number_id":{"type":"integer","description":"SMS from-number ID, or `null`"},"sms_body":{"type":"string","description":"SMS body, or `null`"},"text_variable_mapping":{"type":"object","description":"WhatsApp template placeholder → lead variable map, or `null`","additionalProperties":true},"fallback_channel":{"type":"string","description":"Call→text fallback channel (`whatsapp` / `sms`), or `null`"},"fallback_whatsapp_sender_id":{"type":"integer","description":"Fallback WhatsApp sender, or `null`"},"fallback_whatsapp_template_id":{"type":"integer","description":"Fallback WhatsApp template, or `null`"},"fallback_sms_from_phone_number_id":{"type":"integer","description":"Fallback SMS from-number, or `null`"},"fallback_sms_body":{"type":"string","description":"Fallback SMS body, or `null`"},"fallback_variable_mapping":{"type":"object","description":"Fallback WhatsApp variable map, or `null`","additionalProperties":true},"created_at":{"type":"string","description":"Created timestamp in your account timezone"},"updated_at":{"type":"string","description":"Updated timestamp in your account timezone"}},"additionalProperties":true}}},"additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/user/campaigns/update-status":{"post":{"tags":["Campaigns"],"summary":"Update campaign status","operationId":"updateCampaignStatus","description":"Start or stop a call, WhatsApp, or SMS campaign via API. Starting validates channel config, schedule, and balance.\n\n[Docs](https://docs.famulor.io/api-v1/campaigns/update-status)","externalDocs":{"description":"Update campaign status","url":"https://docs.famulor.io/api-v1/campaigns/update-status"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"campaign_id":{"type":"integer","description":"The ID of the campaign to update"},"action":{"type":"string","description":"`start` or `stop`"}},"required":["campaign_id","action"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"examples":{"campaign-started":{"summary":"Campaign started","value":{"message":"Campaign started successfully.","success":true,"data":{"campaign_id":2324,"status":"in-progress","channel":"call"}}},"campaign-stopped":{"summary":"Campaign stopped","value":{"message":"Campaign stopped successfully.","success":true,"data":{"campaign_id":2324,"status":"paused","channel":"whatsapp"}}}},"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable outcome","default":"Campaign started successfully."},"success":{"type":"boolean","description":"Whether the operation succeeded","default":true},"data":{"type":"object","properties":{"campaign_id":{"type":"integer","description":"Campaign ID"},"status":{"type":"string","description":"New status (e.g. `in-progress`, `paused`)","default":"in-progress"},"channel":{"type":"string","description":"`call`, `whatsapp`, or `sms`"}},"additionalProperties":true}},"additionalProperties":true}}}},"400":{"description":"Bad Request","content":{"application/json":{"examples":{"invalid-action":{"summary":"Invalid action","value":{"message":"Invalid action. Must be either 'start' or 'stop'.","success":false}},"insufficient-balance":{"summary":"Insufficient balance","value":{"message":"Insufficient balance to start the campaign. Please top up your account.","success":false,"data":{"campaign_id":2324,"status":"draft","channel":"call"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Campaign not found","content":{"application/json":{"example":{"message":"Campaign not found.","success":false}}}},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/user/conversations":{"get":{"tags":["Conversations"],"summary":"List Conversations","operationId":"listConversations","description":"List all conversations of the authenticated user with filtering and cursor pagination\n\n[Docs](https://docs.famulor.io/api-v1/conversations/list)","externalDocs":{"description":"List Conversations","url":"https://docs.famulor.io/api-v1/conversations/list"},"parameters":[{"name":"type","in":"query","required":false,"description":"Filters conversations by type. Possible values: `test`, `widget`, `whatsapp`, `api`","schema":{"type":"string","enum":["test","widget","whatsapp","api"]}},{"name":"assistant_id","in":"query","required":false,"description":"Filters conversations by assistant ID (must belong to the authenticated user)","schema":{"type":"integer"}},{"name":"customer_phone","in":"query","required":false,"description":"Filters conversations by the customer's phone number (exact match). Useful for finding all conversations with a specific customer.","schema":{"type":"string"}},{"name":"whatsapp_sender_phone","in":"query","required":false,"description":"Filters conversations by WhatsApp sender phone number (exact match). Useful for finding all conversations from a specific WhatsApp Business number.","schema":{"type":"string"}},{"name":"external_identifier","in":"query","required":false,"description":"Filters conversations by an external identifier. Useful for finding conversations linked to records in your external system.","schema":{"type":"string"}},{"name":"per_page","in":"query","required":false,"description":"Number of conversations per page (1-100, default: 15)","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Cursor for pagination. Use `next_cursor` or `prev_cursor` from a previous response.","schema":{"type":"string"}}],"responses":{"200":{"description":"response","content":{"application/json":{"example":{"data":[{"id":"7c9e6679-7425-40de-944b-e07fc1f90ae7","assistant_id":"a1b2c3d4-5678-90ab-cdef-1234567890ab","assistant_name":"Support Assistant","type":"widget","variables":{"user_name":"Jane Smith","plan":"premium"},"message_count":12,"total_cost":0.0045,"ai_enabled":true,"created_at":"2025-01-25 14:30:00","updated_at":"2025-01-25 14:45:22"},{"id":"8d0f7780-8536-51ef-055c-f18fd2g01bf8","assistant_id":"a1b2c3d4-5678-90ab-cdef-1234567890ab","assistant_name":"Support Assistant","type":"whatsapp","variables":null,"message_count":8,"total_cost":0.0032,"ai_enabled":true,"created_at":"2025-01-25 10:15:00","updated_at":"2025-01-25 10:28:45","whatsapp_sender":{"name":"Acme Corp Support","phone":"+14155551234"},"customer":{"name":"John Doe","phone":"+14155559876"}},{"id":"9e1g8891-9647-62fg-166d-g29ge3h12cg9","assistant_id":"a1b2c3d4-5678-90ab-cdef-1234567890ab","assistant_name":"Support Assistant","type":"api","variables":{"lead_id":"12345","source":"website"},"external_identifier":"crm-lead-12345","message_count":5,"total_cost":0.0021,"ai_enabled":true,"created_at":"2025-01-25 09:00:00","updated_at":"2025-01-25 09:15:30"}],"path":"https://app.famulor.de/api/user/conversations","per_page":15,"next_cursor":"eyJpZCI6MTAwLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9","prev_cursor":null},"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The unique UUID of the conversation"},"assistant_id":{"type":"string","description":"The UUID of the assistant handling this conversation"},"assistant_name":{"type":"string","description":"The name of the assistant handling this conversation"},"type":{"type":"string","description":"The conversation type: `test`, `widget`, `whatsapp`, or `api`"},"variables":{"type":["object","null"],"description":"Custom variables associated with the conversation (key-value pairs)","additionalProperties":true},"external_identifier":{"type":"string","description":"The identifier from your external system for this conversation. Only present for conversations of type `api` if an external identifier was set."},"message_count":{"type":"integer","description":"Total number of messages in the conversation"},"total_cost":{"type":"number","description":"The total cost of the conversation in USD"},"ai_enabled":{"type":"boolean","description":"Indicates if AI responses are enabled for this conversation"},"created_at":{"type":"string","description":"Date and time when the conversation was created"},"updated_at":{"type":"string","description":"Date and time when the conversation was last updated"},"whatsapp_sender":{"type":"object","description":"Information about the WhatsApp Business sender. Only present for conversations of type `whatsapp`.","properties":{"name":{"type":"string","description":"Display name of the WhatsApp sender (company name)"},"phone":{"type":"string","description":"Phone number of the WhatsApp sender"}},"additionalProperties":true},"customer":{"type":"object","description":"Customer information. Only present for conversations of type `whatsapp`.","properties":{"name":{"type":"string","description":"Name of the customer (if available)"},"phone":{"type":"string","description":"Phone number of the customer"}},"additionalProperties":true}},"additionalProperties":true}},"next_cursor":{"type":"string","description":"Cursor to fetch the next page of results. Pass this as the `cursor` parameter in your next request. `null` if there are no further results."},"prev_cursor":{"type":["string","null"],"description":"Cursor to fetch the previous page of results. `null` if this is the first page."},"per_page":{"type":"integer","description":"Number of items per page"}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/user/folder":{"post":{"tags":["Folders"],"summary":"Create Folder","operationId":"createFolder","description":"Create a folder to organize your assistants\n\n[Docs](https://docs.famulor.io/api-v1/folders/create)","externalDocs":{"description":"Create Folder","url":"https://docs.famulor.io/api-v1/folders/create"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The folder name (max 255 characters). Must be unique within your account."},"color":{"type":"string","description":"A color for the folder badge. One of: `gray`, `slate`, `red`, `orange`, `amber`, `green`, `teal`, `blue`, `purple`, `pink`.","enum":["gray","slate","red","orange","amber","green","teal","blue","purple","pink"]}},"required":["name"]}}}},"responses":{"201":{"description":"Success Response","content":{"application/json":{"example":{"message":"Folder created successfully","data":{"id":12,"name":"Acme Corp","color":"blue","assistants_count":0}},"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message"},"data":{"type":"object","properties":{"id":{"type":"integer","description":"The unique identifier of the created folder"},"name":{"type":"string","description":"The folder name"},"color":{"type":"string","description":"The folder color (or `null`)"},"assistants_count":{"type":"integer","description":"Number of assistants in this folder (always `0` for a new folder)"}},"additionalProperties":true}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"description":"Validation Error","content":{"application/json":{"example":{"message":"The name has already been taken.","errors":{"name":["The name has already been taken."]}}}}}}}},"/user/folder/{id}":{"delete":{"tags":["Folders"],"summary":"Delete Folder","operationId":"deleteFolder","description":"Delete a folder\n\n[Docs](https://docs.famulor.io/api-v1/folders/delete)","externalDocs":{"description":"Delete Folder","url":"https://docs.famulor.io/api-v1/folders/delete"},"parameters":[{"name":"id","in":"path","required":true,"description":"The folder ID. Must belong to your account.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Success Response","content":{"application/json":{"example":{"message":"Folder deleted successfully"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not Found","content":{"application/json":{"example":{"message":"Folder not found"}}}},"422":{"$ref":"#/components/responses/ValidationError"}}},"put":{"tags":["Folders"],"summary":"Update Folder","operationId":"updateFolder","description":"Rename a folder or change its color\n\n[Docs](https://docs.famulor.io/api-v1/folders/update)","externalDocs":{"description":"Update Folder","url":"https://docs.famulor.io/api-v1/folders/update"},"parameters":[{"name":"id","in":"path","required":true,"description":"The folder ID. Must belong to your account.","schema":{"type":"integer"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"New name (max 255 characters). Must be unique within your account."},"color":{"type":"string","description":"New color. One of: `gray`, `slate`, `red`, `orange`, `amber`, `green`, `teal`, `blue`, `purple`, `pink`. Send `null` to clear it.","enum":["gray","slate","red","orange","amber","green","teal","blue","purple","pink"]}}}}}},"responses":{"200":{"description":"Success Response","content":{"application/json":{"example":{"message":"Folder updated successfully","data":{"id":12,"name":"Acme Inc.","color":"pink","assistants_count":4}},"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message"},"data":{"type":"object","properties":{"id":{"type":"integer","description":"The folder ID"},"name":{"type":"string","description":"The folder name"},"color":{"type":"string","description":"The folder color (or `null`)"},"assistants_count":{"type":"integer","description":"Number of assistants in this folder"}},"additionalProperties":true}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not Found","content":{"application/json":{"example":{"message":"Folder not found"}}}},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/user/folders":{"get":{"tags":["Folders"],"summary":"List Folders","operationId":"listFolders","description":"List the folders in your account\n\n[Docs](https://docs.famulor.io/api-v1/folders/list)","externalDocs":{"description":"List Folders","url":"https://docs.famulor.io/api-v1/folders/list"},"parameters":[{"name":"per_page","in":"query","required":false,"description":"Number of folders per page (1-100, default: 15)","schema":{"type":"integer"}},{"name":"page","in":"query","required":false,"description":"Page number (default: 1)","schema":{"type":"integer"}}],"responses":{"200":{"description":"Success Response","content":{"application/json":{"example":{"data":[{"id":12,"name":"Acme Corp","color":"blue","assistants_count":4},{"id":18,"name":"Globex","color":"teal","assistants_count":0}],"current_page":1,"per_page":15,"total":2},"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"The unique identifier of the folder"},"name":{"type":"string","description":"The folder name"},"color":{"type":"string","description":"The folder color (or `null`)"},"assistants_count":{"type":"integer","description":"Number of assistants in this folder"}},"additionalProperties":true}}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/user/knowledgebases":{"post":{"tags":["Knowledge Bases"],"summary":"Create Knowledge Base","operationId":"createKnowledgeBase","description":"Create a new knowledge base in Famulor via API to power your AI voice assistants with company information, FAQs, product details and reference documents.\n\n[Docs](https://docs.famulor.io/api-v1/knowledgebases/create)","externalDocs":{"description":"Create Knowledge Base","url":"https://docs.famulor.io/api-v1/knowledgebases/create"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The name of the knowledge base (max. 255 characters)"},"description":{"type":"string","description":"Optional description of the knowledge base (max. 255 characters)"}},"required":["name"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"example":{"message":"Knowledgebase created successfully.","data":{"id":1,"name":"Product Documentation","description":"Technical documentation for our products","status":"empty","status_label":"Empty","created_at":"2025-01-08T10:30:00.000000Z","updated_at":"2025-01-08T10:30:00.000000Z"}},"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message"},"data":{"type":"object","description":"The created knowledge base object","properties":{"id":{"type":"integer","description":"The unique identifier of the knowledge base"},"name":{"type":"string","description":"The name of the knowledge base"},"description":{"type":"string","description":"Description of the knowledge base"},"status":{"type":"string","description":"Current status (will be `empty` for new knowledge bases)"},"status_label":{"type":"string","description":"Human-readable status label"},"created_at":{"type":"string","description":"ISO 8601 timestamp of creation"},"updated_at":{"type":"string","description":"ISO 8601 timestamp of last update"}},"additionalProperties":true}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"description":"Validation Error","content":{"application/json":{"example":{"message":"The name field is required.","errors":{"name":["The name field is required."]}}}}},"500":{"description":"Error","content":{"application/json":{"example":{"error":"Failed to create knowledgebase. Please try again."}}}}}},"get":{"tags":["Knowledge Bases"],"summary":"List Knowledge Bases","operationId":"listKnowledgeBases","description":"Retrieves all knowledge bases of the authenticated user\n\n[Docs](https://docs.famulor.io/api-v1/knowledgebases/list)","externalDocs":{"description":"List Knowledge Bases","url":"https://docs.famulor.io/api-v1/knowledgebases/list"},"responses":{"200":{"description":"OK","content":{"application/json":{"examples":{"success":{"summary":"Success","value":{"data":[{"id":1,"name":"Product Documentation","description":"Technical documentation for our products","status":"active","status_label":"Active","documents_count":5,"assistants_count":2,"created_at":"2025-01-05T10:30:00.000000Z","updated_at":"2025-01-08T14:20:00.000000Z"},{"id":2,"name":"FAQ Knowledge","description":"Frequently asked questions and answers","status":"processing","status_label":"Processing","documents_count":1,"assistants_count":0,"created_at":"2025-01-08T09:00:00.000000Z","updated_at":"2025-01-08T09:05:00.000000Z"}]}},"empty-response":{"summary":"Empty Response","value":{"data":[]}}},"schema":{"type":"object","properties":{"data":{"type":"array","description":"Array of knowledge base objects","items":{"type":"object","properties":{"id":{"type":"integer","description":"The unique identifier of the knowledge base"},"name":{"type":"string","description":"The name of the knowledge base"},"description":{"type":"string","description":"Optional description of the knowledge base"},"status":{"type":"string","description":"Current status: `empty`, `processing`, `active` or `failed`"},"status_label":{"type":"string","description":"Human-readable status label"},"documents_count":{"type":"integer","description":"Number of documents in this knowledge base"},"assistants_count":{"type":"integer","description":"Number of assistants using this knowledge base"},"created_at":{"type":"string","description":"ISO 8601 timestamp of creation"},"updated_at":{"type":"string","description":"ISO 8601 timestamp of last update"}},"additionalProperties":true}}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/user/knowledgebases/{id}":{"delete":{"tags":["Knowledge Bases"],"summary":"Delete Knowledge Base","operationId":"deleteKnowledgeBase","description":"Permanently delete a Famulor knowledge base and all its documents via API. AI voice assistants will lose access to the indexed content immediately.\n\n[Docs](https://docs.famulor.io/api-v1/knowledgebases/delete)","externalDocs":{"description":"Delete Knowledge Base","url":"https://docs.famulor.io/api-v1/knowledgebases/delete"},"parameters":[{"name":"id","in":"path","required":true,"description":"The unique identifier of the knowledge base to delete","schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"message":"Knowledgebase deleted successfully."},"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message"}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not Found","content":{"application/json":{"example":{"error":"Knowledgebase not found."}}}},"422":{"$ref":"#/components/responses/ValidationError"}}},"get":{"tags":["Knowledge Bases"],"summary":"Get Knowledge Base","operationId":"getKnowledgeBase","description":"Retrieves details of a specific knowledge base by ID\n\n[Docs](https://docs.famulor.io/api-v1/knowledgebases/get)","externalDocs":{"description":"Get Knowledge Base","url":"https://docs.famulor.io/api-v1/knowledgebases/get"},"parameters":[{"name":"id","in":"path","required":true,"description":"The unique identifier of the knowledge base","schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":{"id":1,"name":"Product Documentation","description":"Technical documentation for our products","status":"active","status_label":"Active","documents_count":5,"assistants_count":2,"created_at":"2025-01-05T10:30:00.000000Z","updated_at":"2025-01-08T14:20:00.000000Z"}},"schema":{"type":"object","properties":{"data":{"type":"object","description":"The knowledge base object","properties":{"id":{"type":"integer","description":"The unique identifier of the knowledge base"},"name":{"type":"string","description":"The name of the knowledge base"},"description":{"type":"string","description":"Optional description of the knowledge base"},"status":{"type":"string","description":"Current status: `empty`, `processing`, `active` or `failed`"},"status_label":{"type":"string","description":"Human-readable status label"},"documents_count":{"type":"integer","description":"Number of documents in this knowledge base"},"assistants_count":{"type":"integer","description":"Number of assistants using this knowledge base"},"created_at":{"type":"string","description":"ISO 8601 timestamp of creation"},"updated_at":{"type":"string","description":"ISO 8601 timestamp of last update"}},"additionalProperties":true}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not Found","content":{"application/json":{"example":{"error":"Knowledgebase not found."}}}},"422":{"$ref":"#/components/responses/ValidationError"}}},"put":{"tags":["Knowledge Bases"],"summary":"Update Knowledge Base","operationId":"updateKnowledgeBase","description":"Update an existing Famulor knowledge base via API. Rename, change settings or modify metadata for the source data feeding your AI voice assistants.\n\n[Docs](https://docs.famulor.io/api-v1/knowledgebases/update)","externalDocs":{"description":"Update Knowledge Base","url":"https://docs.famulor.io/api-v1/knowledgebases/update"},"parameters":[{"name":"id","in":"path","required":true,"description":"The unique identifier of the knowledge base to update","schema":{"type":"integer"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The new name for the knowledge base (max. 255 characters)"},"description":{"type":"string","description":"The new description for the knowledge base (max. 255 characters)"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"message":"Knowledgebase updated successfully.","data":{"id":1,"name":"Updated Product Documentation","description":"Updated description for our technical documents","status":"active","status_label":"Active","updated_at":"2025-01-08T15:45:00.000000Z"}},"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message"},"data":{"type":"object","description":"The updated knowledge base object","properties":{"id":{"type":"integer","description":"The unique identifier of the knowledge base"},"name":{"type":"string","description":"The name of the knowledge base"},"description":{"type":"string","description":"Description of the knowledge base"},"status":{"type":"string","description":"Current status"},"status_label":{"type":"string","description":"Human-readable status label"},"updated_at":{"type":"string","description":"ISO 8601 timestamp of last update"}},"additionalProperties":true}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not Found","content":{"application/json":{"example":{"error":"Knowledgebase not found."}}}},"422":{"description":"Validation Error","content":{"application/json":{"example":{"message":"The name may not be greater than 255 characters.","errors":{"name":["The name may not be greater than 255 characters."]}}}}}}}},"/user/knowledgebases/{knowledgebaseId}/documents":{"post":{"tags":["Knowledge Bases"],"summary":"Create Document","operationId":"createDocument","description":"Upload a new document to a Famulor knowledge base via API. Add PDFs, text, FAQs or product data that AI voice assistants can reference during calls.\n\n[Docs](https://docs.famulor.io/api-v1/knowledgebases/create-document)","externalDocs":{"description":"Create Document","url":"https://docs.famulor.io/api-v1/knowledgebases/create-document"},"parameters":[{"name":"knowledgebaseId","in":"path","required":true,"description":"The unique identifier of the knowledge base","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The name of the document (max. 255 characters)"},"description":{"type":"string","description":"Optional description of the document (max. 255 characters)"},"type":{"type":"string","description":"Document type: `website`, `pdf`, `txt` or `docx`"},"url":{"type":"string","description":"The main URL to scrape. Required if `links` is not provided."},"links":{"type":"array","description":"Array of specific URLs to scrape. Required if `url` is not provided.","items":{"type":"object","properties":{"link":{"type":"string","description":"A valid URL to include in the document"}},"required":["link"]}},"relative_links_limit":{"type":"integer","description":"Maximum number of relative links to follow when scraping (1-50)","default":10},"file":{"type":"string","format":"binary","description":"The file to upload (max. 20MB). Use `multipart/form-data` encoding."}},"required":["name","type","file"]}},"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The name of the document (max. 255 characters)"},"description":{"type":"string","description":"Optional description of the document (max. 255 characters)"},"type":{"type":"string","description":"Document type: `website`, `pdf`, `txt` or `docx`"},"url":{"type":"string","description":"The main URL to scrape. Required if `links` is not provided."},"links":{"type":"array","description":"Array of specific URLs to scrape. Required if `url` is not provided.","items":{"type":"object","properties":{"link":{"type":"string","description":"A valid URL to include in the document"}},"required":["link"]}},"relative_links_limit":{"type":"integer","description":"Maximum number of relative links to follow when scraping (1-50)","default":10},"file":{"type":"string","format":"binary","description":"The file to upload (max. 20MB). Use `multipart/form-data` encoding."}},"required":["name","type","file"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"examples":{"website-document-created":{"summary":"Website Document Created","value":{"message":"Document created successfully. Processing will begin shortly.","data":{"id":1,"name":"Company Website","description":"Main website content","type":"website","type_label":"Website","status":"processing","status_label":"Processing","created_at":"2025-01-08T10:30:00.000000Z"}}},"pdf-document-created":{"summary":"PDF Document Created","value":{"message":"Document created successfully. Processing will begin shortly.","data":{"id":2,"name":"Product Handbook","description":"User manual for our product","type":"pdf","type_label":"PDF","status":"processing","status_label":"Processing","created_at":"2025-01-08T10:35:00.000000Z"}}}},"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message"},"data":{"type":"object","description":"The created document object","properties":{"id":{"type":"integer","description":"The unique identifier of the document"},"name":{"type":"string","description":"The name of the document"},"description":{"type":"string","description":"Description of the document"},"type":{"type":"string","description":"Document type"},"type_label":{"type":"string","description":"Human-readable type label"},"status":{"type":"string","description":"Processing status (will initially be `processing`)"},"status_label":{"type":"string","description":"Human-readable status label"},"created_at":{"type":"string","description":"ISO 8601 timestamp of creation"}},"additionalProperties":true}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Knowledgebase Not Found","content":{"application/json":{"example":{"error":"Knowledgebase not found."}}}},"422":{"description":"Validation Error","content":{"application/json":{"example":{"message":"A file is required for this document type.","errors":{"file":["A file is required for this document type."]}}}}},"500":{"description":"Processing Error","content":{"application/json":{"example":{"error":"Failed to create document. Please try again."}}}}}},"get":{"tags":["Knowledge Bases"],"summary":"List Documents","operationId":"listDocuments","description":"List all documents stored in a specific Famulor knowledge base via API. Inspect filenames, sizes and indexing status used by AI voice assistants.\n\n[Docs](https://docs.famulor.io/api-v1/knowledgebases/list-documents)","externalDocs":{"description":"List Documents","url":"https://docs.famulor.io/api-v1/knowledgebases/list-documents"},"parameters":[{"name":"knowledgebaseId","in":"path","required":true,"description":"The unique identifier of the knowledge base","schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":1,"name":"Product Handbook","description":"Complete user manual for the product","type":"pdf","type_label":"PDF","status":"active","status_label":"Active","created_at":"2025-01-05T10:30:00.000000Z","updated_at":"2025-01-05T10:35:00.000000Z"},{"id":2,"name":"Company Website","description":"Main website content","type":"website","type_label":"Website","status":"processing","status_label":"Processing","created_at":"2025-01-08T09:00:00.000000Z","updated_at":"2025-01-08T09:00:00.000000Z"}]},"schema":{"type":"object","properties":{"data":{"type":"array","description":"Array of document objects","items":{"type":"object","properties":{"id":{"type":"integer","description":"The unique identifier of the document"},"name":{"type":"string","description":"The name of the document"},"description":{"type":"string","description":"Optional description of the document"},"type":{"type":"string","description":"Document type: `website`, `pdf`, `txt` or `docx`"},"type_label":{"type":"string","description":"Human-readable type label"},"status":{"type":"string","description":"Processing status: `processing`, `active` or `failed`"},"status_label":{"type":"string","description":"Human-readable status label"},"created_at":{"type":"string","description":"ISO 8601 timestamp of creation"},"updated_at":{"type":"string","description":"ISO 8601 timestamp of last update"}},"additionalProperties":true}}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Knowledgebase Not Found","content":{"application/json":{"example":{"error":"Knowledgebase not found."}}}},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/user/knowledgebases/{knowledgebaseId}/documents/{documentId}":{"delete":{"tags":["Knowledge Bases"],"summary":"Delete Document","operationId":"deleteDocument","description":"Delete a specific document from a Famulor knowledge base via API. Permanently removes its content from the RAG index used by your AI voice assistant.\n\n[Docs](https://docs.famulor.io/api-v1/knowledgebases/delete-document)","externalDocs":{"description":"Delete Document","url":"https://docs.famulor.io/api-v1/knowledgebases/delete-document"},"parameters":[{"name":"knowledgebaseId","in":"path","required":true,"description":"The unique identifier of the knowledge base","schema":{"type":"integer"}},{"name":"documentId","in":"path","required":true,"description":"The unique identifier of the document to delete","schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"message":"Document deleted successfully."},"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message"}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not Found","content":{"application/json":{"examples":{"knowledgebase-not-found":{"summary":"Knowledgebase Not Found","value":{"error":"Knowledgebase not found."}},"document-not-found":{"summary":"Document Not Found","value":{"error":"Document not found."}}}}}},"422":{"$ref":"#/components/responses/ValidationError"},"500":{"description":"Error","content":{"application/json":{"example":{"error":"Failed to delete document. Please try again."}}}}}},"get":{"tags":["Knowledge Bases"],"summary":"Get Document","operationId":"getDocument","description":"Retrieve details of a specific document inside a Famulor knowledge base by ID via API. Get content, metadata and processing status for AI voice agents.\n\n[Docs](https://docs.famulor.io/api-v1/knowledgebases/get-document)","externalDocs":{"description":"Get Document","url":"https://docs.famulor.io/api-v1/knowledgebases/get-document"},"parameters":[{"name":"knowledgebaseId","in":"path","required":true,"description":"The unique identifier of the knowledge base","schema":{"type":"integer"}},{"name":"documentId","in":"path","required":true,"description":"The unique identifier of the document","schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":{"id":1,"name":"Product Handbook","description":"Complete user manual for the product","type":"pdf","type_label":"PDF","status":"active","status_label":"Active","created_at":"2025-01-05T10:30:00.000000Z","updated_at":"2025-01-05T10:35:00.000000Z"}},"schema":{"type":"object","properties":{"data":{"type":"object","description":"The document object","properties":{"id":{"type":"integer","description":"The unique identifier of the document"},"name":{"type":"string","description":"The name of the document"},"description":{"type":"string","description":"Optional description of the document"},"type":{"type":"string","description":"Document type: `website`, `pdf`, `txt` or `docx`"},"type_label":{"type":"string","description":"Human-readable type label"},"status":{"type":"string","description":"Processing status: `processing`, `active` or `failed`"},"status_label":{"type":"string","description":"Human-readable status label"},"created_at":{"type":"string","description":"ISO 8601 timestamp of creation"},"updated_at":{"type":"string","description":"ISO 8601 timestamp of last update"}},"additionalProperties":true}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not Found","content":{"application/json":{"examples":{"knowledgebase-not-found":{"summary":"Knowledgebase Not Found","value":{"error":"Knowledgebase not found."}},"document-not-found":{"summary":"Document Not Found","value":{"error":"Document not found."}}}}}},"422":{"$ref":"#/components/responses/ValidationError"}}},"put":{"tags":["Knowledge Bases"],"summary":"Update Document","operationId":"updateDocument","description":"Update the name or description of a document in a Famulor knowledge base via API. Keep your AI voice agent's source materials organized and labelled.\n\n[Docs](https://docs.famulor.io/api-v1/knowledgebases/update-document)","externalDocs":{"description":"Update Document","url":"https://docs.famulor.io/api-v1/knowledgebases/update-document"},"parameters":[{"name":"knowledgebaseId","in":"path","required":true,"description":"The unique identifier of the knowledge base","schema":{"type":"integer"}},{"name":"documentId","in":"path","required":true,"description":"The unique identifier of the document to update","schema":{"type":"integer"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The new name for the document (max. 255 characters)"},"description":{"type":"string","description":"The new description for the document (max. 255 characters)"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"message":"Document updated successfully.","data":{"id":1,"name":"Updated Product Handbook","description":"Revised user manual with new features","type":"pdf","type_label":"PDF","status":"active","status_label":"Active","updated_at":"2025-01-08T15:45:00.000000Z"}},"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message"},"data":{"type":"object","description":"The updated document object","properties":{"id":{"type":"integer","description":"The unique identifier of the document"},"name":{"type":"string","description":"The name of the document"},"description":{"type":"string","description":"Description of the document"},"type":{"type":"string","description":"Document type"},"type_label":{"type":"string","description":"Human-readable type label"},"status":{"type":"string","description":"Processing status"},"status_label":{"type":"string","description":"Human-readable status label"},"updated_at":{"type":"string","description":"ISO 8601 timestamp of last update"}},"additionalProperties":true}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not Found","content":{"application/json":{"examples":{"knowledgebase-not-found":{"summary":"Knowledgebase Not Found","value":{"error":"Knowledgebase not found."}},"document-not-found":{"summary":"Document Not Found","value":{"error":"Document not found."}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"example":{"message":"The name may not be greater than 255 characters.","errors":{"name":["The name may not be greater than 255 characters."]}}}}}}}},"/user/label":{"post":{"tags":["Labels"],"summary":"Create Label","operationId":"createLabel","description":"Create a label to tag your assistants\n\n[Docs](https://docs.famulor.io/api-v1/labels/create)","externalDocs":{"description":"Create Label","url":"https://docs.famulor.io/api-v1/labels/create"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The label name (max 255 characters). Must be unique within your account."},"color":{"type":"string","description":"A color for the label badge. One of: `gray`, `slate`, `red`, `orange`, `amber`, `green`, `teal`, `blue`, `purple`, `pink`.","enum":["gray","slate","red","orange","amber","green","teal","blue","purple","pink"]}},"required":["name"]}}}},"responses":{"201":{"description":"Success Response","content":{"application/json":{"example":{"message":"Label created successfully","data":{"id":3,"name":"Inbound","color":"green","assistants_count":0}},"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message"},"data":{"type":"object","properties":{"id":{"type":"integer","description":"The unique identifier of the created label"},"name":{"type":"string","description":"The label name"},"color":{"type":"string","description":"The label color (or `null`)"},"assistants_count":{"type":"integer","description":"Number of assistants this label is applied to (always `0` for a new label)"}},"additionalProperties":true}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"description":"Validation Error","content":{"application/json":{"example":{"message":"The name has already been taken.","errors":{"name":["The name has already been taken."]}}}}}}}},"/user/label/{id}":{"delete":{"tags":["Labels"],"summary":"Delete Label","operationId":"deleteLabel","description":"Delete a label\n\n[Docs](https://docs.famulor.io/api-v1/labels/delete)","externalDocs":{"description":"Delete Label","url":"https://docs.famulor.io/api-v1/labels/delete"},"parameters":[{"name":"id","in":"path","required":true,"description":"The label ID. Must belong to your account.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Success Response","content":{"application/json":{"example":{"message":"Label deleted successfully"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not Found","content":{"application/json":{"example":{"message":"Label not found"}}}},"422":{"$ref":"#/components/responses/ValidationError"}}},"put":{"tags":["Labels"],"summary":"Update Label","operationId":"updateLabel","description":"Rename a label or change its color\n\n[Docs](https://docs.famulor.io/api-v1/labels/update)","externalDocs":{"description":"Update Label","url":"https://docs.famulor.io/api-v1/labels/update"},"parameters":[{"name":"id","in":"path","required":true,"description":"The label ID. Must belong to your account.","schema":{"type":"integer"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"New name (max 255 characters). Must be unique within your account."},"color":{"type":"string","description":"New color. One of: `gray`, `slate`, `red`, `orange`, `amber`, `green`, `teal`, `blue`, `purple`, `pink`. Send `null` to clear it.","enum":["gray","slate","red","orange","amber","green","teal","blue","purple","pink"]}}}}}},"responses":{"200":{"description":"Success Response","content":{"application/json":{"example":{"message":"Label updated successfully","data":{"id":3,"name":"Inbound calls","color":"teal","assistants_count":7}},"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message"},"data":{"type":"object","properties":{"id":{"type":"integer","description":"The label ID"},"name":{"type":"string","description":"The label name"},"color":{"type":"string","description":"The label color (or `null`)"},"assistants_count":{"type":"integer","description":"Number of assistants this label is applied to"}},"additionalProperties":true}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not Found","content":{"application/json":{"example":{"message":"Label not found"}}}},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/user/labels":{"get":{"tags":["Labels"],"summary":"List Labels","operationId":"listLabels","description":"List the labels in your account\n\n[Docs](https://docs.famulor.io/api-v1/labels/list)","externalDocs":{"description":"List Labels","url":"https://docs.famulor.io/api-v1/labels/list"},"parameters":[{"name":"per_page","in":"query","required":false,"description":"Number of labels per page (1-100, default: 15)","schema":{"type":"integer"}},{"name":"page","in":"query","required":false,"description":"Page number (default: 1)","schema":{"type":"integer"}}],"responses":{"200":{"description":"Success Response","content":{"application/json":{"example":{"data":[{"id":3,"name":"Inbound","color":"green","assistants_count":7},{"id":5,"name":"Outbound","color":"blue","assistants_count":2}],"current_page":1,"per_page":15,"total":2},"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"The unique identifier of the label"},"name":{"type":"string","description":"The label name"},"color":{"type":"string","description":"The label color (or `null`)"},"assistants_count":{"type":"integer","description":"Number of assistants this label is applied to"}},"additionalProperties":true}}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/user/lead":{"post":{"tags":["Leads"],"summary":"Create lead","operationId":"createLead","description":"Add a new lead to your Famulor outbound calling campaign via API. Submit contact information, custom variables and trigger AI voice agent calls.\n\n[Docs](https://docs.famulor.io/api-v1/leads/create)","externalDocs":{"description":"Create lead","url":"https://docs.famulor.io/api-v1/leads/create"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phone_number":{"type":"string","description":"Contact phone number in E.164 format (example: +1234567890)"},"campaign_id":{"type":"integer","description":"The campaign ID where this lead should be added"},"variables":{"type":"object","description":"Custom data fields to associate with this lead","properties":{"customer_name":{"type":"string","description":"Customer's full name"},"email":{"type":"string","description":"Customer's email address"}}},"allow_dupplicate":{"type":"boolean","description":"Permit creating duplicate leads within the same campaign (default: false)"},"secondary_contacts":{"type":"array","description":"Additional contact persons linked to this lead","items":{"type":"object","properties":{"phone_number":{"type":"string","description":"Secondary contact's phone number in E.164 format"},"variables":{"type":"object","description":"Custom variables for the secondary contact","properties":{"customer_name":{"type":"string","description":"Secondary contact's name"},"email":{"type":"string","description":"Secondary contact's email"}}}},"required":["phone_number"]}}},"required":["phone_number","campaign_id"]}}}},"responses":{"200":{"description":"Response","content":{"application/json":{"example":{"message":"Lead created successfully","data":{"id":1,"campaign_id":1,"phone_number":"+1234567890","variables":{"customer_name":"John Doe","email":"john.doe@example.com"},"status":"created","created_at":"2025-06-30 11:53:20","updated_at":"2025-06-30 11:53:20","campaign":{"id":1,"name":"My new campaign"},"secondary_contacts":[{"id":2,"phone_number":"+1234567891","variables":{"customer_name":"Jane Doe Secondary","email":"jane.doe.secondary@example.com"},"status":"created","created_at":"2025-06-30 11:53:20","updated_at":"2025-06-30 11:53:20"},{"id":3,"phone_number":"+1234567892","variables":{"customer_name":"Bob Doe Office","email":"bob.doe.office@example.com"},"status":"created","created_at":"2025-06-30 11:53:20","updated_at":"2025-06-30 11:53:20"}]}},"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success confirmation message"},"data":{"type":"object","description":"The created lead object with all associated data","properties":{"id":{"type":"integer","description":"Unique identifier for the new lead"},"campaign_id":{"type":"integer","description":"Campaign identifier this lead is assigned to"},"phone_number":{"type":"string","description":"Lead's contact number in E.164 format"},"variables":{"type":"object","description":"Custom variables stored with the lead","properties":{"customer_name":{"type":"string","description":"Customer's name"},"email":{"type":"string","description":"Customer's email address"}},"additionalProperties":true},"status":{"type":"string","description":"Current lead status"},"created_at":{"type":"string","description":"Creation timestamp"},"updated_at":{"type":"string","description":"Last modification timestamp"},"campaign":{"type":"object","description":"Campaign details for this lead","properties":{"id":{"type":"integer","description":"Campaign identifier"},"name":{"type":"string","description":"Campaign name"}},"additionalProperties":true},"secondary_contacts":{"type":"array","description":"List of secondary contacts created with this lead","items":{"type":"object","properties":{"id":{"type":"integer","description":"Secondary contact identifier"},"phone_number":{"type":"string","description":"Secondary contact phone number in E.164 format"},"variables":{"type":"object","description":"Variables for the secondary contact","additionalProperties":true},"status":{"type":"string","description":"Secondary contact status"},"created_at":{"type":"string","description":"Secondary contact creation timestamp"},"updated_at":{"type":"string","description":"Secondary contact last update timestamp"}},"additionalProperties":true}}},"additionalProperties":true}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/user/leads":{"get":{"tags":["Leads"],"summary":"List Leads","operationId":"listLeads","description":"Retrieve a paginated list of all leads for the authenticated Famulor account via API. Filter, sort and access contact details for voice agent campaigns.\n\n[Docs](https://docs.famulor.io/api-v1/leads/list)","externalDocs":{"description":"List Leads","url":"https://docs.famulor.io/api-v1/leads/list"},"parameters":[{"name":"status","in":"query","required":false,"description":"Filter leads by status. Possible values: `created`, `scheduled`, `processing`, `completed`, `rescheduled`, `reached-max-retries`, `blacklisted`","schema":{"type":"string","enum":["created","scheduled","processing","completed","rescheduled","reached-max-retries","blacklisted"]}},{"name":"campaign_id","in":"query","required":false,"description":"Filter leads by campaign ID","schema":{"type":"integer"}},{"name":"phone_number","in":"query","required":false,"description":"Filter leads by phone number (partial match supported)","schema":{"type":"string"}},{"name":"date_from","in":"query","required":false,"description":"Filter leads created from this date (`YYYY-MM-DD` format)","schema":{"type":"string"}},{"name":"date_to","in":"query","required":false,"description":"Filter leads created until this date (`YYYY-MM-DD` format)","schema":{"type":"string"}},{"name":"per_page","in":"query","required":false,"description":"Number of leads per page (`1-100`)","schema":{"type":"integer","default":15}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer","default":1}}],"responses":{"200":{"description":"Response","content":{"application/json":{"example":{"current_page":1,"data":[{"id":1,"campaign_id":1,"phone_number":"+1234567890","variables":{"customer_name":"John Doe","email":"john.doe@example.com"},"status":"created","created_at":"2025-06-30 11:18:04","updated_at":"2025-06-30 11:18:04","campaign":{"id":1,"name":"My new campaign"},"secondary_contacts":[{"id":2,"phone_number":"+1234567899","variables":{"customer_name":"Jane Doe Secondary","email":"jane.doe.secondary@example.com"},"status":"created","created_at":"2025-06-30 11:18:04","updated_at":"2025-06-30 11:18:04"}]}],"first_page_url":"https://app.famulor.de/api/user/leads?page=1","from":1,"last_page":10,"last_page_url":"https://app.famulor.de/api/user/leads?page=10","links":[{"url":null,"label":"&laquo; Previous","active":false},{"url":"https://app.famulor.de/api/user/leads?page=1","label":"1","active":true},{"url":"https://app.famulor.de/api/user/leads?page=2","label":"2","active":false}],"next_page_url":"https://app.famulor.de/api/user/leads?page=2","path":"https://app.famulor.de/api/user/leads","per_page":15,"prev_page_url":null,"to":15,"total":150},"schema":{"type":"object","properties":{"data":{"type":"array","description":"List of leads","items":{"type":"object","properties":{"id":{"type":"integer","description":"The ID of the lead"},"campaign_id":{"type":"integer","description":"The ID of the campaign this lead belongs to"},"phone_number":{"type":"string","description":"The lead's phone number in E.164 format"},"variables":{"type":"object","description":"The variables assigned to the lead","additionalProperties":true},"status":{"type":"string","description":"The status of the lead"},"created_at":{"type":"string","description":"The creation date of the lead"},"updated_at":{"type":"string","description":"The date of the last update of the lead"},"campaign":{"type":"object","description":"The campaign information","properties":{"id":{"type":"integer","description":"The ID of the campaign"},"name":{"type":"string","description":"The name of the campaign"}},"additionalProperties":true},"secondary_contacts":{"type":"array","description":"Array of secondary contact leads linked to this lead","items":{"type":"object","properties":{"id":{"type":"integer","description":"The ID of the secondary contact lead"},"phone_number":{"type":"string","description":"The phone number of the secondary contact in E.164 format"},"variables":{"type":"object","description":"The variables assigned to the secondary contact","additionalProperties":true},"status":{"type":"string","description":"The status of the secondary contact"},"created_at":{"type":"string","description":"The creation date of the secondary contact"},"updated_at":{"type":"string","description":"The date of the last update of the secondary contact"}},"additionalProperties":true}}},"additionalProperties":true}},"current_page":{"type":"integer","description":"The current page number"},"per_page":{"type":"integer","description":"Number of items per page"},"total":{"type":"integer","description":"Total number of leads matching the criteria"},"last_page":{"type":"integer","description":"The last page number"}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/user/leads/{id}":{"delete":{"tags":["Leads"],"summary":"Delete lead","operationId":"deleteLead","description":"Permanently remove a lead from your Famulor account via API. Deletes all associated call data, transcripts and notes for that contact record.\n\n[Docs](https://docs.famulor.io/api-v1/leads/delete)","externalDocs":{"description":"Delete lead","url":"https://docs.famulor.io/api-v1/leads/delete"},"parameters":[{"name":"id","in":"path","required":true,"description":"The unique identifier of the lead you want to remove","schema":{"type":"integer"}}],"responses":{"200":{"description":"Success Response","content":{"application/json":{"example":{"message":"Lead deleted successfully"},"schema":{"type":"object","properties":{"message":{"type":"string","description":"Confirmation message indicating successful deletion"}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not Found","content":{"application/json":{"example":{"message":"Lead not found"}}}},"422":{"$ref":"#/components/responses/ValidationError"}}},"put":{"tags":["Leads"],"summary":"Update Lead","operationId":"updateLead","description":"Update an existing Famulor lead via API. Modify contact information, custom variables, status and campaign assignment for AI voice outreach.\n\n[Docs](https://docs.famulor.io/api-v1/leads/update)","externalDocs":{"description":"Update Lead","url":"https://docs.famulor.io/api-v1/leads/update"},"parameters":[{"name":"id","in":"path","required":true,"description":"The ID of the lead to be updated","schema":{"type":"integer"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"campaign_id":{"type":"integer","description":"The ID of the campaign to which the lead should be assigned"},"phone_number":{"type":"string","description":"The lead's phone number (automatically formatted to E164)"},"status":{"type":"string","description":"The status of the lead. Must be one of the following values: created, completed, reached-max-retries"},"variables":{"type":"object","description":"Custom variables to be merged with the existing lead variables","additionalProperties":true}}}}}},"responses":{"200":{"description":"Response","content":{"application/json":{"example":{"message":"Lead successfully updated"},"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message indicating the lead was updated"}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/user/make_call":{"post":{"tags":["Calls"],"summary":"Make a Call","operationId":"makeCall","description":"Initiate an outbound phone call with a specific Famulor AI assistant via API. Pass lead data and trigger automated voice conversations programmatically.\n\n[Docs](https://docs.famulor.io/api-v1/calls/make)","externalDocs":{"description":"Make a Call","url":"https://docs.famulor.io/api-v1/calls/make"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phone_number":{"type":"string","description":"The customer's phone number in E.164 format (e.g. +1234567890)"},"assistant_id":{"type":"integer","description":"The ID of the assistant to make the call with"},"variables":{"type":"object","description":"The variables to be passed to the lead","properties":{"customer_name":{"type":"string","description":"The name of the customer"},"email":{"type":"string","description":"The customer's email address"}}}},"required":["phone_number","assistant_id"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"message":"Call initiated successfully","call_id":480337,"status":"initiated"},"schema":{"type":"object","properties":{"message":{"type":"string","description":"Confirmation message that the call was successfully initiated"},"call_id":{"type":"integer","description":"The unique ID of the created call"},"status":{"type":"string","description":"The initial status of the call (e.g. \"initiated\")"}},"additionalProperties":true}}}},"400":{"description":"Invalid Phone Number","content":{"application/json":{"example":{"message":"Invalid phone number format. Please use E.164 format (e.g. +1234567890)"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Assistant Not Found","content":{"application/json":{"example":{"message":"Assistant not found or does not belong to the authenticated user"}}}},"422":{"description":"Insufficient Balance","content":{"application/json":{"example":{"message":"Insufficient balance to make call. Please top up your account."}}}}}}},"/user/me":{"get":{"tags":["Account"],"summary":"Get User Information","operationId":"getUserInformation","description":"Retrieve the profile, settings and account details of the currently authenticated Famulor user via API. Useful for verifying tokens and account state.\n\n[Docs](https://docs.famulor.io/api-v1/user/me)","externalDocs":{"description":"Get User Information","url":"https://docs.famulor.io/api-v1/user/me"},"responses":{"200":{"description":"Response","content":{"application/json":{"example":{"name":"Your Name","email":"example@example.com","total_balance":100.67447094},"schema":{"type":"object","properties":{"name":{"type":"string","description":"The full name of the user"},"email":{"type":"string","description":"The email address of the user"},"total_balance":{"type":"number","description":"The current total balance of the user account"}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/user/phone-numbers/{id}":{"delete":{"tags":["Phone Numbers"],"summary":"Release Phone Number","operationId":"releasePhoneNumber","description":"Releases a phone number and cancels its subscription\n\n[Docs](https://docs.famulor.io/api-v1/phone-numbers/release)\n\nGilt auch für: **Delete SIP Trunk** ([Docs](https://docs.famulor.io/api-v1/sip-trunks/delete)).","externalDocs":{"description":"Release Phone Number","url":"https://docs.famulor.io/api-v1/phone-numbers/release"},"parameters":[{"name":"id","in":"path","required":true,"description":"The unique identifier of the phone number to release","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"examples":{"subscription-cancelled":{"summary":"Subscription Cancelled","value":{"message":"Phone number released successfully. It will be removed at the end of the billing period."}},"immediately-deleted":{"summary":"Immediately Deleted","value":{"message":"Phone number deleted successfully."}}},"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message indicating the release status"}},"additionalProperties":true}}}},"400":{"description":"Already Scheduled","content":{"application/json":{"example":{"error":"Phone number is already scheduled for release."}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not Found","content":{"application/json":{"example":{"error":"Phone number not found."}}}},"422":{"$ref":"#/components/responses/ValidationError"},"500":{"description":"Error","content":{"application/json":{"example":{"error":"Failed to release phone number. Please try again or contact support."}}}}}},"put":{"tags":["Phone Numbers"],"summary":"Update Phone Number","operationId":"updatePhoneNumber","description":"Update a phone number's nickname\n\n[Docs](https://docs.famulor.io/api-v1/phone-numbers/update)","externalDocs":{"description":"Update Phone Number","url":"https://docs.famulor.io/api-v1/phone-numbers/update"},"parameters":[{"name":"id","in":"path","required":true,"description":"The unique identifier of the phone number to update","schema":{"type":"integer"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"nickname":{"type":"string","description":"A short label for the phone number. Maximum 50 characters. Send `null` or an empty string to clear it."}}}}}},"responses":{"200":{"description":"Response","content":{"application/json":{"example":{"message":"Phone number updated successfully.","data":{"id":1,"phone_number":"+14155551234","nickname":"Sales line","country_code":"US","type":"normal"}},"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message"},"data":{"type":"object","description":"The updated phone number","properties":{"id":{"type":"integer","description":"The unique identifier of the phone number"},"phone_number":{"type":"string","description":"The phone number in E.164 format"},"nickname":{"type":"string","description":"The phone number's nickname (or `null` if not set)"},"country_code":{"type":"string","description":"The ISO 3166-1 alpha-2 country code"},"type":{"type":"string","description":"The type of phone number: `normal`, `sip`, or `caller_id`"}},"additionalProperties":true}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not Found","content":{"application/json":{"example":{"error":"Phone number not found."}}}},"422":{"description":"Validation Error","content":{"application/json":{"example":{"message":"The nickname must not exceed 50 characters.","errors":{"nickname":["The nickname must not exceed 50 characters."]}}}}}}}},"/user/phone-numbers/all":{"get":{"tags":["Phone Numbers"],"summary":"List Phone Numbers","operationId":"listPhoneNumbers","description":"Retrieves all phone numbers of the authenticated user\n\n[Docs](https://docs.famulor.io/api-v1/phone-numbers/list)","externalDocs":{"description":"List Phone Numbers","url":"https://docs.famulor.io/api-v1/phone-numbers/list"},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":1,"phone_number":"+49155551234","nickname":"Sales line","country_code":"DE","type":"normal","type_label":"Dedicated Number","sms_capable":true,"region":"us1","has_active_subscription":true,"created_at":"2025-01-07T10:30:00.000000Z"},{"id":2,"phone_number":"+442071234567","nickname":null,"country_code":"GB","type":"normal","type_label":"Dedicated Number","sms_capable":false,"region":"us1","has_active_subscription":true,"created_at":"2025-01-05T14:20:00.000000Z"}]},"schema":{"type":"object","properties":{"data":{"type":"array","description":"Array of phone number objects","items":{"type":"object","properties":{"id":{"type":"integer","description":"The unique identifier of the phone number"},"phone_number":{"type":"string","description":"The phone number in E.164 format (e.g. +49155551234)"},"nickname":{"type":["string","null"],"description":"A short, human-friendly label for the number (or `null` if not set)"},"country_code":{"type":"string","description":"The ISO 3166-1 alpha-2 country code (e.g. DE, GB, AU)"},"type":{"type":"string","description":"The type of phone number: `normal`, `sip` or `caller_id`"},"type_label":{"type":"string","description":"Human-readable label for the phone number type"},"sms_capable":{"type":"boolean","description":"Whether the phone number can send and receive SMS"},"region":{"type":"string","description":"The region where the phone number was provisioned"},"has_active_subscription":{"type":"boolean","description":"Whether the phone number has an active subscription"},"created_at":{"type":"string","description":"ISO 8601 timestamp of when the phone number was purchased"}},"additionalProperties":true}}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/user/phone-numbers/purchase":{"post":{"tags":["Phone Numbers"],"summary":"Purchase Phone Number","operationId":"purchasePhoneNumber","description":"Purchase a dedicated phone number in Famulor via API. Acquire local, mobile or toll-free numbers for inbound or outbound AI voice agent calls.\n\n[Docs](https://docs.famulor.io/api-v1/phone-numbers/purchase)","externalDocs":{"description":"Purchase Phone Number","url":"https://docs.famulor.io/api-v1/phone-numbers/purchase"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phone_number":{"type":"string","description":"The phone number to purchase in E.164 format (e.g. +14155551234). Must be a number returned by the Search endpoint."}},"required":["phone_number"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"example":{"message":"Phone number purchased successfully.","data":{"id":123,"phone_number":"+14155551234","country_code":"US","type":"normal","sms_capable":true}},"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message"},"data":{"type":"object","description":"The details of the purchased phone number","properties":{"id":{"type":"integer","description":"The unique identifier of the phone number"},"phone_number":{"type":"string","description":"The phone number in E.164 format"},"country_code":{"type":"string","description":"The ISO country code"},"type":{"type":"string","description":"The phone number type (always `normal` for purchased numbers)"},"sms_capable":{"type":"boolean","description":"Whether the number supports SMS"}},"additionalProperties":true}},"additionalProperties":true}}}},"400":{"description":"Bad Request","content":{"application/json":{"examples":{"already-in-use":{"summary":"Already In Use","value":{"error":"This phone number is already in use."}},"not-available":{"summary":"Not Available","value":{"error":"This phone number is not available for purchase. Please search for available numbers first."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"Payment Required","content":{"application/json":{"examples":{"no-payment-method":{"summary":"No Payment Method","value":{"error":"No payment method found. Please add a payment method to your account."}},"payment-failed":{"summary":"Payment Failed","value":{"error":"Payment failed. Please update your payment method."}}}}}},"422":{"description":"Invalid Format","content":{"application/json":{"example":{"error":"Unable to parse phone number. Please provide a valid E.164 format number."}}}},"500":{"description":"Provider Error","content":{"application/json":{"example":{"error":"Failed to purchase phone number from provider. Please contact support."}}}}}}},"/user/phone-numbers/search":{"get":{"tags":["Phone Numbers"],"summary":"Search Available Phone Numbers","operationId":"searchAvailablePhoneNumbers","description":"Searches for available phone numbers that can be purchased\n\n[Docs](https://docs.famulor.io/api-v1/phone-numbers/search)","externalDocs":{"description":"Search Available Phone Numbers","url":"https://docs.famulor.io/api-v1/phone-numbers/search"},"parameters":[{"name":"country_code","in":"query","required":false,"description":"The ISO 3166-1 alpha-2 country code to search in (e.g. DE, GB, AU, CA)","schema":{"type":"string","default":"DE"}},{"name":"contains","in":"query","required":false,"description":"Filters phone numbers containing specific digits (numeric characters only, maximum 10 digits)","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"examples":{"success":{"summary":"Success","value":{"data":[{"phone_number":"+14155551234","phone_number_formatted":"+1 415-555-1234","country_code":"US","price":3.99,"stripe_price_id":"price_1PkA4dBXoZOzqQuAsvGvVJTZ","address_requirements":"none","sms_capable":true},{"phone_number":"+14155555678","phone_number_formatted":"+1 415-555-5678","country_code":"US","price":3.99,"stripe_price_id":"price_1PkA4dBXoZOzqQuAsvGvVJTZ","address_requirements":"none","sms_capable":false}]}},"empty-response":{"summary":"Empty Response","value":{"data":[]}}},"schema":{"type":"object","properties":{"data":{"type":"array","description":"Array of available phone numbers","items":{"type":"object","properties":{"phone_number":{"type":"string","description":"The phone number in E.164 format"},"phone_number_formatted":{"type":"string","description":"The phone number formatted for display"},"country_code":{"type":"string","description":"The ISO country code"},"price":{"type":"number","description":"Monthly rental price in USD"},"stripe_price_id":{"type":"string","description":"The Stripe price ID for billing"},"address_requirements":{"type":"string","description":"Address requirements for this number: `none`, `local`, `foreign` or `inventory`"},"sms_capable":{"type":"boolean","description":"Whether the number supports SMS"}},"additionalProperties":true}}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/user/phone-numbers/sip-trunks":{"post":{"tags":["SIP Trunks"],"summary":"Create SIP Trunk","operationId":"createSIPTrunk","description":"Create a new SIP trunk with credentials, address, and proxy settings\n\n[Docs](https://docs.famulor.io/api-v1/sip-trunks/create)","externalDocs":{"description":"Create SIP Trunk","url":"https://docs.famulor.io/api-v1/sip-trunks/create"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sip_trunk_type":{"type":"string","description":"The type of SIP trunk: `extension` for a SIP extension, or `number` for a phone number (DID). This determines the expected format of the `phone_number` field."},"phone_number":{"type":"string","description":"The SIP extension (1-15 characters, e.g. `1000`) when `sip_trunk_type` is `extension`, or a phone number in E.164 format (e.g. `+14155551234`) when `sip_trunk_type` is `number`."},"nickname":{"type":"string","description":"A short, human-friendly label for the trunk (e.g. \"Provider X — Main\"). Maximum 50 characters."},"sip_username":{"type":"string","description":"Username for SIP authentication (3-128 characters)"},"sip_password":{"type":"string","description":"Password for SIP authentication (minimum 3 characters)"},"sip_address":{"type":"string","description":"The SIP server address without port (e.g. `sip.provider.com`)"},"sip_calling_format":{"type":"string","description":"The outbound calling number format:\n\n* `+e164` - International with `+` prefix (e.g. `+12025550123`)\n* `e164` - International without `+` prefix (e.g. `12025550123`)\n* `national` - National format without country code (e.g. `0741926265`)"},"inbound_authorization_type":{"type":"string","description":"How inbound calls are authenticated:\n\n* `auth` - Uses the same SIP username and password configured for outbound\n* `ip` - Whitelists specific IP addresses (requires `allowed_inbound_ips`)"},"allowed_inbound_ips":{"type":"array","description":"Array of IP addresses allowed to send inbound calls. **Required** when `inbound_authorization_type` is `ip`. Must contain at least one valid IP address.","items":{}},"country_code":{"type":"string","description":"ISO 3166-2 country code where the SIP trunk is located (e.g. `US`, `GB`, `DE`). When `sip_trunk_type` is `number`, the country is auto-detected from the phone number if possible."},"outbound_proxy":{"type":"boolean","description":"Route outbound calls through a fixed IP address. Default: `false`. Only enable this if your SIP provider requires IP-based authentication for outbound traffic."}},"required":["sip_trunk_type","phone_number","sip_username","sip_password","sip_address","sip_calling_format","inbound_authorization_type","country_code"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"examples":{"extension-with-password-auth":{"summary":"Extension with password auth","value":{"message":"SIP trunk created successfully.","data":{"id":42,"phone_number":"1000","nickname":"Provider X — Main","sip_username":"myuser","sip_address":"sip.provider.com","sip_calling_format":"+e164","inbound_authorization_type":"auth","allowed_inbound_ips":null,"outbound_proxy":false,"country_code":"US","inbound_trunk_id":"ST_xxxxxxxxxxxx","outbound_trunk_id":"ST_yyyyyyyyyyyy","created_at":"2026-03-31T10:00:00.000000Z","updated_at":"2026-03-31T10:00:00.000000Z"}}},"phone-number-did-with-ip-auth":{"summary":"Phone number (DID) with IP auth","value":{"message":"SIP trunk created successfully.","data":{"id":43,"phone_number":"+14155551234","nickname":null,"sip_username":"trunk_user","sip_address":"sip.provider.com","sip_calling_format":"e164","inbound_authorization_type":"ip","allowed_inbound_ips":["203.0.113.10","198.51.100.20"],"outbound_proxy":true,"country_code":"US","inbound_trunk_id":"ST_xxxxxxxxxxxx","outbound_trunk_id":"ST_yyyyyyyyyyyy","created_at":"2026-03-31T10:00:00.000000Z","updated_at":"2026-03-31T10:00:00.000000Z"}}}},"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message"},"data":{"type":"object","description":"The created SIP trunk object (same fields as [Get SIP trunk](/en/api-reference/sip-trunks/get))","additionalProperties":true}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"description":"Duplicate","content":{"application/json":{"example":{"error":"A SIP trunk with the same phone number, username, and address already exists."}}}},"422":{"description":"Validation Error","content":{"application/json":{"example":{"message":"The given data was invalid.","errors":{"sip_address":["SIP server address is required."],"sip_calling_format":["SIP calling format must be one of: +e164, e164, national."]}}}}},"500":{"description":"Provisioning Error","content":{"application/json":{"example":{"error":"Failed to create SIP trunk. Please try again or contact support."}}}}}},"get":{"tags":["SIP Trunks"],"summary":"List SIP Trunks","operationId":"listSIPTrunks","description":"Get all SIP trunks owned by the authenticated user\n\n[Docs](https://docs.famulor.io/api-v1/sip-trunks/list)","externalDocs":{"description":"List SIP Trunks","url":"https://docs.famulor.io/api-v1/sip-trunks/list"},"responses":{"200":{"description":"Response","content":{"application/json":{"example":{"data":[{"id":42,"phone_number":"1000","nickname":"Provider X — Main","sip_username":"myuser","sip_address":"sip.provider.com","sip_calling_format":"+e164","inbound_authorization_type":"auth","allowed_inbound_ips":null,"outbound_proxy":false,"country_code":"US","created_at":"2026-03-31T10:00:00.000000Z","updated_at":"2026-03-31T10:00:00.000000Z"},{"id":43,"phone_number":"+14155551234","nickname":null,"sip_username":"trunk_user","sip_address":"sip.provider.com","sip_calling_format":"e164","inbound_authorization_type":"ip","allowed_inbound_ips":["203.0.113.10","198.51.100.20"],"outbound_proxy":true,"country_code":"US","created_at":"2026-03-31T11:00:00.000000Z","updated_at":"2026-03-31T11:00:00.000000Z"}]},"schema":{"type":"object","properties":{"data":{"type":"array","description":"Array of SIP trunk objects","items":{"type":"object","properties":{"id":{"type":"integer","description":"The unique identifier of the SIP trunk"},"phone_number":{"type":"string","description":"The SIP extension or phone number (DID) in E.164 format"},"nickname":{"type":["string","null"],"description":"A short, human-friendly label for the trunk (or `null` if not set)"},"sip_username":{"type":"string","description":"The username used for SIP authentication"},"sip_address":{"type":"string","description":"The SIP server address"},"sip_calling_format":{"type":"string","description":"The outbound calling number format: `+e164`, `e164`, or `national`"},"inbound_authorization_type":{"type":"string","description":"The inbound authorization method: `auth` (username/password) or `ip` (IP whitelist)"},"allowed_inbound_ips":{"type":["array","null"],"description":"Array of whitelisted IP addresses for inbound calls (only when `inbound_authorization_type` is `ip`)","items":{}},"outbound_proxy":{"type":"boolean","description":"Whether outbound calls use a fixed proxy IP address"},"country_code":{"type":"string","description":"The ISO 3166-2 country code where the SIP trunk is located"},"created_at":{"type":"string","description":"ISO 8601 timestamp of when the SIP trunk was created"},"updated_at":{"type":"string","description":"ISO 8601 timestamp of when the SIP trunk was last updated"}},"additionalProperties":true}}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/user/phone-numbers/sip-trunks/{id}":{"get":{"tags":["SIP Trunks"],"summary":"Get SIP Trunk","operationId":"getSIPTrunk","description":"Retrieve full configuration of a single SIP trunk in Famulor by ID via API. Inspect credentials, routing and assigned numbers for your AI voice telephony.\n\n[Docs](https://docs.famulor.io/api-v1/sip-trunks/get)","externalDocs":{"description":"Get SIP Trunk","url":"https://docs.famulor.io/api-v1/sip-trunks/get"},"parameters":[{"name":"id","in":"path","required":true,"description":"The unique identifier of the SIP trunk","schema":{"type":"integer"}}],"responses":{"200":{"description":"Response","content":{"application/json":{"example":{"data":{"id":42,"phone_number":"1000","nickname":"Provider X — Main","sip_username":"myuser","sip_address":"sip.provider.com","sip_calling_format":"+e164","inbound_authorization_type":"auth","allowed_inbound_ips":null,"outbound_proxy":false,"country_code":"US","inbound_trunk_id":"ST_xxxxxxxxxxxx","outbound_trunk_id":"ST_yyyyyyyyyyyy","created_at":"2026-03-31T10:00:00.000000Z","updated_at":"2026-03-31T10:00:00.000000Z"}},"schema":{"type":"object","properties":{"data":{"type":"object","description":"The SIP trunk object","properties":{"id":{"type":"integer","description":"The unique identifier of the SIP trunk"},"phone_number":{"type":"string","description":"The SIP extension or phone number (DID) in E.164 format"},"nickname":{"type":"string","description":"A short, human-friendly label for the trunk (or `null` if not set)"},"sip_username":{"type":"string","description":"The username used for SIP authentication"},"sip_address":{"type":"string","description":"The SIP server address"},"sip_calling_format":{"type":"string","description":"The outbound calling number format: `+e164`, `e164`, or `national`"},"inbound_authorization_type":{"type":"string","description":"The inbound authorization method: `auth` or `ip`"},"allowed_inbound_ips":{"type":["array","null"],"description":"Array of whitelisted IP addresses (only when `inbound_authorization_type` is `ip`)","items":{}},"outbound_proxy":{"type":"boolean","description":"Whether outbound calls use a fixed proxy IP address"},"country_code":{"type":"string","description":"The ISO 3166-2 country code"},"inbound_trunk_id":{"type":"string","description":"Internal identifier for the inbound voice trunk (useful for debugging)"},"outbound_trunk_id":{"type":"string","description":"Internal identifier for the outbound voice trunk (useful for debugging)"},"created_at":{"type":"string","description":"ISO 8601 timestamp"},"updated_at":{"type":"string","description":"ISO 8601 timestamp"}},"additionalProperties":true}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not Found","content":{"application/json":{"example":{"error":"SIP trunk not found."}}}},"422":{"$ref":"#/components/responses/ValidationError"}}},"put":{"tags":["SIP Trunks"],"summary":"Update SIP Trunk","operationId":"updateSIPTrunk","description":"Update an existing SIP trunk configuration in Famulor via API. Change credentials, routing rules and assigned phone numbers for your AI voice telephony.\n\n[Docs](https://docs.famulor.io/api-v1/sip-trunks/update)","externalDocs":{"description":"Update SIP Trunk","url":"https://docs.famulor.io/api-v1/sip-trunks/update"},"parameters":[{"name":"id","in":"path","required":true,"description":"The unique identifier of the SIP trunk to update","schema":{"type":"integer"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"phone_number":{"type":"string","description":"The SIP extension or phone number (1-15 characters)"},"nickname":{"type":"string","description":"A short, human-friendly label for the trunk. Maximum 50 characters. Send `null` to clear it."},"sip_username":{"type":"string","description":"Username for SIP authentication (3-128 characters)"},"sip_password":{"type":"string","description":"Password for SIP authentication (minimum 3 characters)"},"sip_address":{"type":"string","description":"The SIP server address without port"},"sip_calling_format":{"type":"string","description":"The outbound calling number format: `+e164`, `e164`, or `national`"},"inbound_authorization_type":{"type":"string","description":"How inbound calls are authenticated: `auth` or `ip`. When switching to `ip`, you must also provide `allowed_inbound_ips`. When switching to `auth`, any existing IP whitelist is cleared."},"allowed_inbound_ips":{"type":"array","description":"Array of IP addresses allowed for inbound calls. **Required** when `inbound_authorization_type` is set to `ip`.","items":{}},"country_code":{"type":"string","description":"ISO 3166-2 country code"},"outbound_proxy":{"type":"boolean","description":"Route outbound calls through a fixed IP address"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"examples":{"updated-credentials":{"summary":"Updated credentials","value":{"message":"SIP trunk updated successfully.","data":{"id":42,"phone_number":"1000","nickname":"Provider X — Main","sip_username":"new_username","sip_address":"sip.provider.com","sip_calling_format":"+e164","inbound_authorization_type":"auth","allowed_inbound_ips":null,"outbound_proxy":false,"country_code":"US","inbound_trunk_id":"ST_newtrunkid1","outbound_trunk_id":"ST_newtrunkid2","created_at":"2026-03-31T10:00:00.000000Z","updated_at":"2026-03-31T12:00:00.000000Z"}}},"switched-to-ip-auth":{"summary":"Switched to IP auth","value":{"message":"SIP trunk updated successfully.","data":{"id":42,"phone_number":"1000","nickname":"Provider X — Main","sip_username":"myuser","sip_address":"sip.provider.com","sip_calling_format":"+e164","inbound_authorization_type":"ip","allowed_inbound_ips":["203.0.113.10"],"outbound_proxy":false,"country_code":"US","inbound_trunk_id":"ST_newtrunkid1","outbound_trunk_id":"ST_yyyyyyyyyyyy","created_at":"2026-03-31T10:00:00.000000Z","updated_at":"2026-03-31T12:00:00.000000Z"}}}},"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message"},"data":{"type":"object","description":"The updated SIP trunk object (same fields as [Get SIP trunk](/en/api-reference/sip-trunks/get))","additionalProperties":true}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not Found","content":{"application/json":{"example":{"error":"SIP trunk not found."}}}},"422":{"description":"Validation Error","content":{"application/json":{"example":{"message":"The given data was invalid.","errors":{"allowed_inbound_ips":["At least one allowed IP address is required when authorization type is \"ip\"."]}}}}},"500":{"description":"Provisioning Error","content":{"application/json":{"example":{"error":"Failed to update SIP trunk. Please try again or contact support."}}}}}}},"/user/sms":{"post":{"tags":["SMS"],"summary":"Send SMS","operationId":"sendSMS","description":"Send an SMS message using your Famulor phone number via API. Trigger transactional or follow-up texts after AI voice calls, lead capture or campaigns.\n\n[Docs](https://docs.famulor.io/api-v1/sms/send)","externalDocs":{"description":"Send SMS","url":"https://docs.famulor.io/api-v1/sms/send"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"integer","description":"The ID of your phone number from which the SMS will be sent (must be SMS-capable)"},"to":{"type":"string","description":"The recipient's phone number in international format (e.g., \"+4915123456789\")"},"body":{"type":"string","description":"The SMS message content (max. 300 characters)"}},"required":["from","to","body"]}}}},"responses":{"200":{"description":"Sent Successfully","content":{"application/json":{"example":{"message":"SMS sent successfully","data":{"sms_id":"SMS_67890","from":"+4912345678","to":"+4915123456789","body":"Hello! This is a test SMS from Famulor.","segments":1,"cost":0.05,"currency":"EUR","status":"sent"}},"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message confirming that the SMS was sent"},"data":{"type":"object","description":"Additional data about the sent SMS","additionalProperties":true},"400 Bad Request":{"type":"object","properties":{"message":{"type":"string","description":"Error message describing the issue (invalid phone number, insufficient balance, etc.)"}},"additionalProperties":true},"500 Internal Server Error":{"type":"object","properties":{"message":{"type":"string","description":"Error message indicating a failure in sending the SMS"},"error":{"type":"string","description":"Detailed error information"}},"additionalProperties":true}},"additionalProperties":true}}}},"400":{"description":"Bad Request","content":{"application/json":{"examples":{"invalid-request":{"summary":"Invalid Request","value":{"message":"Invalid phone number format"}},"insufficient-balance":{"summary":"Insufficient Balance","value":{"message":"Insufficient balance to send SMS"}},"phone-number-not-sms-capable":{"summary":"Phone Number Not SMS-Capable","value":{"message":"Phone number is not SMS-capable"}},"phone-number-not-found":{"summary":"Phone Number Not Found","value":{"message":"From number not found"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"},"500":{"description":"Server Error","content":{"application/json":{"example":{"message":"Failed to send SMS","error":"Twilio service temporarily unavailable"}}}}}}},"/user/tools":{"post":{"tags":["Mid-Call Tools"],"summary":"Create Mid-call Action","operationId":"createMidCallAction","description":"Create a new Mid-call Action for AI assistant integration\n\n[Docs](https://docs.famulor.io/api-v1/mid-call-tools/create-tool)","externalDocs":{"description":"Create Mid-call Action","url":"https://docs.famulor.io/api-v1/mid-call-tools/create-tool"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Mid-call Action name — letters, numbers and underscores, starting with a letter or underscore (max 64 characters, e.g. `get_weather`, `book_appointment`)"},"description":{"type":"string","description":"Detailed explanation of when and how the AI should use this Mid-call Action (max 255 characters)"},"endpoint":{"type":"string","description":"Valid URL of the API endpoint to call (max 2048 characters)"},"method":{"type":"string","description":"HTTP method: `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`"},"body_format":{"type":"string","description":"How the request body is encoded for write methods (POST/PUT/PATCH): `json` (default) or `form` (`application/x-www-form-urlencoded`)"},"timeout":{"type":"integer","description":"Request timeout in seconds (1-30, default: 10)"},"headers":{"type":"array","description":"HTTP headers to send with the request","items":{"type":"object","properties":{"name":{"type":"string","description":"Header name"},"value":{"type":"string","description":"Header value (max 2048 chars; supports `{{variable}}` substitution)"}},"required":["name","value"]}},"static_fields":{"type":"array","description":"Fixed key/value pairs always sent with the request (the AI never changes them)","items":{"type":"object","properties":{"key":{"type":"string","description":"Field key (max 64 chars)"},"value":{"type":"string","description":"Field value (max 2048 chars; supports `{{variable}}` substitution)"}},"required":["key"]}},"schema":{"type":"array","description":"Parameters that the AI will extract from conversation and send to the endpoint","items":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name (1-64 chars, must start with a letter or underscore, can contain letters, numbers and underscores)"},"type":{"type":"string","description":"Parameter type: `string`, `number`, `float`, or `boolean`"},"description":{"type":"string","description":"Description to help AI understand how to extract this parameter (3-255 chars)"},"required":{"type":"boolean","description":"Whether the AI must collect this parameter. Optional parameters are only sent when a value was collected. Defaults to `false`."}},"required":["name","type","description"]}}},"required":["name","description","endpoint","method"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"example":{"message":"Tool created successfully","data":{"id":1,"name":"send_notification","description":"Use this tool to send a notification to the customer. Call this when customer requests updates.","type":"http","endpoint":"https://api.yourcompany.com/notifications/send","method":"POST","body_format":"json","timeout":15,"headers":[{"name":"Content-Type","value":"application/json"}],"static_fields":[{"key":"caller","value":"{{customer_phone}}"}],"schema":[{"name":"message","type":"string","description":"The notification message to send","required":true},{"name":"send_sms","type":"boolean","description":"Whether to also send SMS notification","required":false}],"created_at":"2025-10-10T12:00:00.000000Z","updated_at":"2025-10-10T12:00:00.000000Z"}},"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message"},"data":{"type":"object","description":"The created Mid-call Action object","properties":{"id":{"type":"integer","description":"The unique identifier of the Mid-call Action"},"name":{"type":"string","description":"The name of the Mid-call Action"},"description":{"type":"string","description":"Mid-call Action description"},"type":{"type":"string","description":"Mid-call Action type: `http` or `automation`"},"endpoint":{"type":"string","description":"API endpoint URL"},"method":{"type":"string","description":"HTTP method"},"body_format":{"type":"string","description":"Request body encoding: `json` or `form`"},"timeout":{"type":"integer","description":"Request timeout in seconds"},"headers":{"type":"array","description":"HTTP headers","items":{}},"static_fields":{"type":"array","description":"Fixed key/value pairs always sent with the request","items":{}},"schema":{"type":"array","description":"Parameter schema","items":{}},"created_at":{"type":"string","description":"ISO 8601 timestamp"},"updated_at":{"type":"string","description":"ISO 8601 timestamp"}},"additionalProperties":true}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"description":"Unprocessable Entity","content":{"application/json":{"examples":{"validation-error":{"summary":"Validation Error","value":{"message":"The name field format is invalid.","errors":{"name":["Tool name must contain only letters, numbers and underscores, and start with a letter or underscore."]}}},"plan-limit-reached":{"summary":"Plan Limit Reached","value":{"message":"You have reached your plan limit of 5 mid call tools. Please upgrade your plan to create more tools."}}}}}}}},"get":{"tags":["Mid-Call Tools"],"summary":"List Mid-call Actions","operationId":"listMidCallActions","description":"Retrieve all Mid-call Actions available in your Famulor account via API. Useful for inventory, debugging and attaching actions to AI voice assistants.\n\n[Docs](https://docs.famulor.io/api-v1/mid-call-tools/get-tools)","externalDocs":{"description":"List Mid-call Actions","url":"https://docs.famulor.io/api-v1/mid-call-tools/get-tools"},"responses":{"200":{"description":"Response","content":{"application/json":{"example":{"data":[{"id":1,"name":"get_weather","description":"Use this tool to get the current weather in a specific city. Call this when the customer asks about weather conditions.","type":"http","endpoint":"https://api.openweathermap.org/data/2.5/weather?city={city}","method":"GET","body_format":"json","timeout":10,"headers":[{"name":"Content-Type","value":"application/json"},{"name":"Authorization","value":"Bearer sk_..."}],"static_fields":[],"schema":[{"name":"city","type":"string","description":"The city name to get weather for","required":true},{"name":"days","type":"number","description":"Number of forecast days","required":false}],"created_at":"2025-10-10T12:00:00.000000Z","updated_at":"2025-10-10T12:00:00.000000Z"},{"id":2,"name":"send_notification","description":"Use this tool to send a notification to the customer. Call this when customer requests updates.","type":"http","endpoint":"https://api.yourcompany.com/notifications/send","method":"POST","body_format":"json","timeout":15,"headers":[{"name":"Content-Type","value":"application/json"}],"static_fields":[{"key":"caller","value":"{{customer_phone}}"}],"schema":[{"name":"message","type":"string","description":"The notification message to send","required":true},{"name":"send_sms","type":"boolean","description":"Whether to also send SMS notification","required":false}],"created_at":"2025-10-09T14:30:00.000000Z","updated_at":"2025-10-10T09:15:00.000000Z"}]},"schema":{"type":"object","properties":{"data":{"type":"array","description":"Array of Mid-call Actions","items":{"type":"object","properties":{"id":{"type":"integer","description":"The unique identifier of the Mid-call Action"},"name":{"type":"string","description":"The name of the Mid-call Action"},"description":{"type":"string","description":"Detailed explanation of when and how the AI should use this Mid-call Action"},"type":{"type":"string","description":"Mid-call Action type: `http` or `automation`"},"endpoint":{"type":"string","description":"The API endpoint URL that will be called"},"method":{"type":"string","description":"HTTP method (GET, POST, PUT, PATCH, DELETE)"},"body_format":{"type":"string","description":"Request body encoding: `json` or `form`"},"timeout":{"type":"integer","description":"Request timeout in seconds (1-30)"},"headers":{"type":"array","description":"HTTP headers to send with the request","items":{"type":"object","properties":{"name":{"type":"string","description":"Header name"},"value":{"type":"string","description":"Header value"}},"additionalProperties":true}},"static_fields":{"type":"array","description":"Fixed key/value pairs always sent with the request","items":{"type":"object","properties":{"key":{"type":"string","description":"Field key"},"value":{"type":"string","description":"Field value"}},"additionalProperties":true}},"schema":{"type":"array","description":"Parameters that the AI will extract and send to the endpoint","items":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name"},"type":{"type":"string","description":"Parameter type (string, number, float, boolean)"},"description":{"type":"string","description":"Description to help AI understand how to extract this parameter"},"required":{"type":"boolean","description":"Whether the AI must collect this parameter"}},"additionalProperties":true}},"created_at":{"type":"string","description":"ISO 8601 timestamp when the Mid-call Action was created"},"updated_at":{"type":"string","description":"ISO 8601 timestamp when the Mid-call Action was last updated"}},"additionalProperties":true}}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/user/tools/{id}":{"delete":{"tags":["Mid-Call Tools"],"summary":"Delete Mid-call Action","operationId":"deleteMidCallAction","description":"Permanently remove a Mid-call Action from your Famulor account via API. Detaches the action from any AI voice assistant currently configured to use it.\n\n[Docs](https://docs.famulor.io/api-v1/mid-call-tools/delete-tool)","externalDocs":{"description":"Delete Mid-call Action","url":"https://docs.famulor.io/api-v1/mid-call-tools/delete-tool"},"parameters":[{"name":"id","in":"path","required":true,"description":"The unique identifier of the Mid-call Action to delete","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"message":"Tool deleted successfully"},"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message confirming deletion"}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not Found","content":{"application/json":{"example":{"message":"Tool not found"}}}},"422":{"$ref":"#/components/responses/ValidationError"}}},"get":{"tags":["Mid-Call Tools"],"summary":"Get Mid-call Action","operationId":"getMidCallAction","description":"Retrieve detailed information about a specific Mid-call Action\n\n[Docs](https://docs.famulor.io/api-v1/mid-call-tools/get-tool)","externalDocs":{"description":"Get Mid-call Action","url":"https://docs.famulor.io/api-v1/mid-call-tools/get-tool"},"parameters":[{"name":"id","in":"path","required":true,"description":"The unique identifier of the Mid-call Action","schema":{"type":"integer"}}],"responses":{"200":{"description":"Response","content":{"application/json":{"example":{"id":1,"name":"get_weather","description":"Use this tool to get the current weather in a specific city. Call this when the customer asks about weather conditions.","type":"http","endpoint":"https://api.openweathermap.org/data/2.5/weather?city={city}","method":"GET","body_format":"json","timeout":10,"headers":[{"name":"Content-Type","value":"application/json"},{"name":"Authorization","value":"Bearer sk_..."}],"static_fields":[],"schema":[{"name":"city","type":"string","description":"The city name to get weather for","required":true},{"name":"days","type":"number","description":"Number of forecast days","required":false}],"created_at":"2025-10-10T12:00:00.000000Z","updated_at":"2025-10-10T12:00:00.000000Z"},"schema":{"type":"object","properties":{"id":{"type":"integer","description":"The unique identifier of the Mid-call Action"},"name":{"type":"string","description":"The name of the Mid-call Action"},"description":{"type":"string","description":"Detailed explanation of when and how the AI should use this Mid-call Action"},"type":{"type":"string","description":"Mid-call Action type: `http` or `automation`"},"endpoint":{"type":"string","description":"The API endpoint URL that will be called"},"method":{"type":"string","description":"HTTP method (GET, POST, PUT, PATCH, DELETE)"},"body_format":{"type":"string","description":"Request body encoding: `json` or `form`"},"timeout":{"type":"integer","description":"Request timeout in seconds (1-30)"},"headers":{"type":"array","description":"HTTP headers to send with the request","items":{"type":"object","properties":{"name":{"type":"string","description":"Header name"},"value":{"type":"string","description":"Header value"}},"additionalProperties":true}},"static_fields":{"type":"array","description":"Fixed key/value pairs always sent with the request","items":{"type":"object","properties":{"key":{"type":"string","description":"Field key"},"value":{"type":"string","description":"Field value"}},"additionalProperties":true}},"schema":{"type":"array","description":"Parameters that the AI will extract and send to the endpoint","items":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name"},"type":{"type":"string","description":"Parameter type (string, number, float, boolean)"},"description":{"type":"string","description":"Description to help AI understand how to extract this parameter"},"required":{"type":"boolean","description":"Whether the AI must collect this parameter"}},"additionalProperties":true}},"created_at":{"type":"string","description":"ISO 8601 timestamp when the Mid-call Action was created"},"updated_at":{"type":"string","description":"ISO 8601 timestamp when the Mid-call Action was last updated"}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not Found","content":{"application/json":{"example":{"message":"Tool not found"}}}},"422":{"$ref":"#/components/responses/ValidationError"}}},"put":{"tags":["Mid-Call Tools"],"summary":"Update Mid-call Action","operationId":"updateMidCallAction","description":"Modify an existing Mid-call Action in Famulor via API. Update name, endpoint, parameters or description so AI voice agents call the right action.\n\n[Docs](https://docs.famulor.io/api-v1/mid-call-tools/update-tool)","externalDocs":{"description":"Update Mid-call Action","url":"https://docs.famulor.io/api-v1/mid-call-tools/update-tool"},"parameters":[{"name":"id","in":"path","required":true,"description":"The unique identifier of the Mid-call Action to update","schema":{"type":"integer"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Mid-call Action name — letters, numbers and underscores, starting with a letter or underscore (max 64 characters)"},"description":{"type":"string","description":"Detailed explanation of when and how the AI should use this Mid-call Action (max 255 characters)"},"endpoint":{"type":"string","description":"Valid URL of the API endpoint to call (max 2048 characters)"},"method":{"type":"string","description":"HTTP method: `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`"},"body_format":{"type":"string","description":"Request body encoding for write methods: `json` (default) or `form`"},"timeout":{"type":"integer","description":"Request timeout in seconds (1-30)"},"headers":{"type":"array","description":"HTTP headers to send with the request (replaces existing headers)","items":{"type":"object","properties":{"name":{"type":"string","description":"Header name"},"value":{"type":"string","description":"Header value (supports `{{variable}}` substitution)"}},"required":["name","value"]}},"static_fields":{"type":"array","description":"Fixed key/value pairs always sent with the request (replaces existing static fields)","items":{"type":"object","properties":{"key":{"type":"string","description":"Field key (max 64 chars)"},"value":{"type":"string","description":"Field value (max 2048 chars; supports `{{variable}}` substitution)"}},"required":["key"]}},"schema":{"type":"array","description":"Parameters schema (replaces existing schema)","items":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name (1-64 chars, starts with a letter or underscore)"},"type":{"type":"string","description":"Parameter type: `string`, `number`, `float`, or `boolean`"},"description":{"type":"string","description":"Parameter description (3-255 chars)"},"required":{"type":"boolean","description":"Whether the AI must collect this parameter (default `false`)"}},"required":["name","type","description"]}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"message":"Tool updated successfully","data":{"id":1,"name":"send_notification","description":"Use this tool to send a notification to the customer. Call this when customer requests updates.","type":"http","endpoint":"https://api.yourcompany.com/notifications/send","method":"POST","body_format":"json","timeout":15,"headers":[{"name":"Content-Type","value":"application/json"}],"static_fields":[{"key":"caller","value":"{{customer_phone}}"}],"schema":[{"name":"message","type":"string","description":"The notification message to send","required":true},{"name":"send_sms","type":"boolean","description":"Whether to also send SMS notification","required":false}],"created_at":"2025-10-10T12:00:00.000000Z","updated_at":"2025-10-10T14:30:00.000000Z"}},"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message"},"data":{"type":"object","description":"The updated Mid-call Action object with all current values","additionalProperties":true}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not Found","content":{"application/json":{"example":{"message":"Tool not found"}}}},"422":{"description":"Validation Error","content":{"application/json":{"example":{"message":"Validation failed","errors":{"name":["Tool name must contain only letters, numbers and underscores, and start with a letter or underscore."]}}}}}}}},"/user/whatsapp/send":{"post":{"tags":["WhatsApp"],"summary":"Send WhatsApp Template Message","operationId":"sendWhatsAppTemplateMessage","description":"Send a WhatsApp message using an approved template via Famulor\n\n[Docs](https://docs.famulor.io/api-v1/whatsapp/send-template)","externalDocs":{"description":"Send WhatsApp Template Message","url":"https://docs.famulor.io/api-v1/whatsapp/send-template"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sender_id":{"type":"integer","description":"The ID of the WhatsApp sender to send from (obtained from the [Get Senders](/en/api-reference/whatsapp/get-senders) endpoint)"},"template_id":{"type":"integer","description":"The ID of the message template to use (obtained from the [Get Templates](/en/api-reference/whatsapp/get-templates) endpoint)"},"recipient_phone":{"type":"string","description":"The recipient's phone number in international format (e.g., `+1234567890`)"},"recipient_name":{"type":"string","description":"The recipient's name, max 255 characters (used for conversation tracking and CRM purposes)"},"variables":{"type":"object","description":"Key-value pairs for template variables. Keys should match the variable names from the template. If the template has variables `{{1}}`, `{{2}}`, etc., provide them as `{\"1\": \"value1\", \"2\": \"value2\"}` or using the named keys from the template's `variables` array.","properties":{"1":{"type":"string","description":"Value for the first template variable"},"2":{"type":"string","description":"Value for the second template variable"}}}},"required":["sender_id","template_id","recipient_phone"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"success":true,"conversation_id":1234,"message_id":567,"whatsapp_message_id":890,"message_sid":"SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx","status":"queued"},"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the message was sent successfully"},"conversation_id":{"type":"integer","description":"The ID of the conversation (new or existing) associated with this message"},"message_id":{"type":"integer","description":"The ID of the conversation message record"},"whatsapp_message_id":{"type":"integer","description":"The ID of the WhatsApp message record"},"message_sid":{"type":"string","description":"The Twilio message SID for tracking delivery"},"status":{"type":"string","description":"The initial message delivery status (e.g., `queued`, `sent`)"},"402 Insufficient Balance":{"type":"string"},"404 Not Found":{"type":"string"},"422 Unprocessable Entity":{"type":"string"}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"Insufficient Balance","content":{"application/json":{"example":{"success":false,"error":"Insufficient balance. Please top up your account.","error_code":"INSUFFICIENT_BALANCE"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"sender-not-found":{"summary":"Sender Not Found","value":{"success":false,"error":"Sender not found or does not belong to you","error_code":"SENDER_NOT_FOUND"}},"template-not-found":{"summary":"Template Not Found","value":{"success":false,"error":"Template not found or does not belong to this sender","error_code":"TEMPLATE_NOT_FOUND"}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"examples":{"template-not-approved":{"summary":"Template Not Approved","value":{"success":false,"error":"Template is not approved. Current status: pending","error_code":"TEMPLATE_NOT_APPROVED"}},"invalid-phone":{"summary":"Invalid Phone","value":{"success":false,"error":"Invalid phone number format. Use E.164 format (e.g., +14155551234).","error_code":"INVALID_PHONE"}},"sender-offline":{"summary":"Sender Offline","value":{"success":false,"error":"Sender is not online. Current status: Offline","error_code":"SENDER_OFFLINE"}}}}}}}}},"/user/whatsapp/send-freeform":{"post":{"tags":["WhatsApp"],"summary":"Send WhatsApp Freeform Message","operationId":"sendWhatsAppFreeformMessage","description":"Send a free-text WhatsApp message within an active 24-hour session via Famulor\n\n[Docs](https://docs.famulor.io/api-v1/whatsapp/send-freeform)","externalDocs":{"description":"Send WhatsApp Freeform Message","url":"https://docs.famulor.io/api-v1/whatsapp/send-freeform"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sender_id":{"type":"integer","description":"The ID of the WhatsApp sender to send from (obtained from the [Get Senders](/en/api-reference/whatsapp/get-senders) endpoint)"},"recipient_phone":{"type":"string","description":"The recipient's phone number in international format (e.g., `+1234567890`)"},"message":{"type":"string","description":"The message content to send (max 4096 characters)"}},"required":["sender_id","recipient_phone","message"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"success":true,"conversation_id":1234,"message_id":567,"whatsapp_message_id":890,"message_sid":"SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx","session_status":{"is_open":true,"can_send_freeform":true,"requires_template":false,"message":"Session open (23 hr 45 min remaining). Unlimited free-form messages allowed.","minutes_remaining":1425,"expires_at":"2026-02-25T10:30:00+00:00"}},"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the message was sent successfully"},"conversation_id":{"type":"integer","description":"The ID of the conversation associated with this message"},"message_id":{"type":"integer","description":"The ID of the conversation message record"},"whatsapp_message_id":{"type":"integer","description":"The ID of the WhatsApp message record"},"message_sid":{"type":"string","description":"The Twilio message SID for tracking delivery"},"session_status":{"type":"object","description":"Updated session status after sending the message","properties":{"is_open":{"type":"boolean","description":"Whether the 24-hour messaging window is currently open"},"can_send_freeform":{"type":"boolean","description":"Whether freeform messages can be sent right now"},"requires_template":{"type":"boolean","description":"Whether a template message is required"},"message":{"type":"string","description":"Human-readable description of the session state"},"minutes_remaining":{"type":"integer","description":"Minutes remaining in the 24-hour window"},"expires_at":{"type":"string","description":"ISO 8601 timestamp when the session expires"}},"additionalProperties":true},"402 Insufficient Balance":{"type":"string"},"403 Session Expired":{"type":"string"},"404 Not Found":{"type":"string"},"503 Sender Offline":{"type":"string"}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"Insufficient Balance","content":{"application/json":{"example":{"success":false,"error":"Insufficient balance. Please top up your account.","error_code":"INSUFFICIENT_BALANCE"}}}},"403":{"description":"Session Expired","content":{"application/json":{"example":{"success":false,"error":"The 24-hour messaging window is closed. Customer must reply first, or use a template message.","error_code":"SESSION_EXPIRED","session_status":{"is_open":false,"can_send_freeform":false,"requires_template":true,"message":"Session expired. Send a template or wait for customer to reply.","expired_at":"2026-02-23T10:30:00+00:00"}}}}},"404":{"description":"Sender Not Found","content":{"application/json":{"example":{"success":false,"error":"Sender not found or does not belong to you","error_code":"SENDER_NOT_FOUND"}}}},"422":{"description":"Invalid Phone","content":{"application/json":{"example":{"success":false,"error":"Invalid phone number format. Use E.164 format (e.g., +14155551234).","error_code":"INVALID_PHONE"}}}},"503":{"description":"Sender Offline","content":{"application/json":{"example":{"success":false,"error":"Sender is not online. Current status: Offline","error_code":"SENDER_OFFLINE"}}}}}}},"/user/whatsapp/senders":{"get":{"tags":["WhatsApp"],"summary":"Get WhatsApp Senders","operationId":"getWhatsAppSenders","description":"List WhatsApp Business senders configured in your Famulor account\n\n[Docs](https://docs.famulor.io/api-v1/whatsapp/get-senders)","externalDocs":{"description":"Get WhatsApp Senders","url":"https://docs.famulor.io/api-v1/whatsapp/get-senders"},"parameters":[{"name":"status","in":"query","required":false,"description":"Filter senders by status. Default: `online`. Use `all` to return all senders regardless of status.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"examples":{"response":{"summary":"Response","value":{"data":[{"id":12,"phone_number":"+14155551234","display_name":"Acme Corp Support","status":"online","quality_rating":"GREEN","messaging_limit":10000,"messaging_limit_formatted":"10,000 / 24hr"},{"id":15,"phone_number":"+442071234567","display_name":"Acme Corp Sales","status":"online","quality_rating":"GREEN","messaging_limit":null,"messaging_limit_formatted":"Unlimited"}]}},"empty-response":{"summary":"Empty Response","value":{"data":[]}}},"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"The unique identifier of the WhatsApp sender. Use this ID when sending messages."},"phone_number":{"type":"string","description":"The sender's phone number in E.164 format (e.g., `+14155551234`)"},"display_name":{"type":"string","description":"The WhatsApp Business display name (business name shown to recipients)"},"status":{"type":"string","description":"The sender's current status: `online` or `offline`"},"quality_rating":{"type":"string","description":"Meta's quality rating for this sender: `GREEN`, `YELLOW`, or `RED`"},"messaging_limit":{"type":["integer","null"],"description":"The current messaging limit (number of unique recipients per 24 hours). `null` means unlimited."},"messaging_limit_formatted":{"type":"string","description":"Human-readable messaging limit (e.g., `1,000 / 24hr`, `10,000 / 24hr`, or `Unlimited`)"}},"additionalProperties":true}}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/user/whatsapp/senders/{senderId}/templates":{"get":{"tags":["WhatsApp"],"summary":"Get WhatsApp Templates","operationId":"getWhatsAppTemplates","description":"List WhatsApp message templates for a specific Famulor sender\n\n[Docs](https://docs.famulor.io/api-v1/whatsapp/get-templates)","externalDocs":{"description":"Get WhatsApp Templates","url":"https://docs.famulor.io/api-v1/whatsapp/get-templates"},"parameters":[{"name":"senderId","in":"path","required":true,"description":"The ID of the WhatsApp sender (obtained from the [Get Senders](/en/api-reference/whatsapp/get-senders) endpoint)","schema":{"type":"integer"}},{"name":"status","in":"query","required":false,"description":"Filter templates by approval status. Default: `approved`. Use `all` to return all templates regardless of status.","schema":{"type":"string"}}],"responses":{"200":{"description":"Response","content":{"application/json":{"example":{"data":[{"id":45,"name":"appointment_reminder","language":"en","category":"utility","status":"approved","body_text":"Hi {{1}}, this is a reminder for your appointment on {{2}} at {{3}}. Reply YES to confirm or NO to reschedule.","variables":["customer_name","date","time"],"has_variables":true},{"id":46,"name":"welcome_message","language":"en","category":"marketing","status":"approved","body_text":"Welcome to Acme Corp! We're excited to have you. How can we help you today?","variables":[],"has_variables":false}]},"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"The unique identifier of the template. Use this when sending template messages."},"name":{"type":"string","description":"The template name as registered with Meta (e.g., `order_confirmation`, `appointment_reminder`)"},"language":{"type":"string","description":"The template language code (e.g., `en`, `es`, `pt_BR`)"},"category":{"type":"string","description":"The template category: `marketing`, `utility`, or `authentication`"},"status":{"type":"string","description":"The approval status: `approved`, `pending`, or `rejected`"},"body_text":{"type":"string","description":"The template body text, with variable placeholders shown as `{{1}}`, `{{2}}`, etc."},"variables":{"type":"array","description":"List of variable names defined for the template. Empty array if the template has no variables.","items":{}},"has_variables":{"type":"boolean","description":"Whether this template requires variables to be provided when sending"}},"additionalProperties":true}},"404 Not Found":{"type":"string"}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Sender Not Found","content":{"application/json":{"example":{"success":false,"error":"Sender not found","error_code":"SENDER_NOT_FOUND"}}}},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/user/whatsapp/session-status":{"get":{"tags":["WhatsApp"],"summary":"Get WhatsApp Session Status","operationId":"getWhatsAppSessionStatus","description":"Check the 24-hour WhatsApp messaging window status for a Famulor conversation\n\n[Docs](https://docs.famulor.io/api-v1/whatsapp/session-status)","externalDocs":{"description":"Get WhatsApp Session Status","url":"https://docs.famulor.io/api-v1/whatsapp/session-status"},"parameters":[{"name":"sender_id","in":"query","required":true,"description":"The ID of the WhatsApp sender (obtained from the [Get Senders](/en/api-reference/whatsapp/get-senders) endpoint)","schema":{"type":"integer"}},{"name":"recipient_phone","in":"query","required":true,"description":"The recipient's phone number in international format (e.g., `+1234567890`)","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"examples":{"active-session":{"summary":"Active Session","value":{"success":true,"has_conversation":true,"conversation_id":1234,"customer_name":"John Doe","last_customer_message_at":"2026-02-24T10:30:00+00:00","session_status":{"is_open":true,"can_send_freeform":true,"requires_template":false,"message":"Session open (23 hr 45 min remaining). Unlimited free-form messages allowed.","minutes_remaining":1425,"expires_at":"2026-02-25T10:30:00+00:00"}}},"expired-session":{"summary":"Expired Session","value":{"success":true,"has_conversation":true,"conversation_id":1234,"customer_name":"John Doe","last_customer_message_at":"2026-02-22T14:00:00+00:00","session_status":{"is_open":false,"can_send_freeform":false,"requires_template":true,"message":"Session expired. Send a template or wait for customer to reply.","expired_at":"2026-02-23T14:00:00+00:00"}}},"no-conversation":{"summary":"No Conversation","value":{"success":true,"has_conversation":false,"session_status":{"is_open":false,"can_send_freeform":false,"requires_template":true,"message":"No conversation exists with this recipient. Send a template message first."}}}},"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request was successful"},"has_conversation":{"type":"boolean","description":"Whether a conversation exists with this recipient"},"conversation_id":{"type":"integer","description":"The conversation ID (only present when `has_conversation` is `true`)"},"customer_name":{"type":"string","description":"The customer's name if available (only present when `has_conversation` is `true`)"},"last_customer_message_at":{"type":"string","description":"ISO 8601 timestamp of the customer's last message (only present when `has_conversation` is `true`)"},"session_status":{"type":"object","properties":{"is_open":{"type":"boolean","description":"Whether the 24-hour messaging window is currently open"},"can_send_freeform":{"type":"boolean","description":"Whether freeform (non-template) messages can be sent right now"},"requires_template":{"type":"boolean","description":"Whether a template message is required to message this recipient"},"message":{"type":"string","description":"Human-readable description of the current session state"},"minutes_remaining":{"type":"integer","description":"Minutes remaining in the 24-hour window (only present when session is open)"},"expires_at":{"type":"string","description":"ISO 8601 timestamp when the session expires (present when session is open or no customer message exists)"},"expired_at":{"type":"string","description":"ISO 8601 timestamp when the session expired (only present when session has expired)"}},"additionalProperties":true},"404 Not Found":{"type":"string"}},"additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Sender Not Found","content":{"application/json":{"example":{"success":false,"error":"Sender not found","error_code":"SENDER_NOT_FOUND"}}}},"422":{"$ref":"#/components/responses/ValidationError"}}}}},"webhooks":{"conversation-ended":{"post":{"tags":["Webhooks"],"summary":"Conversation Ended Webhook","operationId":"webhookConversationEnded","description":"Webhook sent after a chat conversation ends containing transcript, extracted variables, and customer data\n\n[Docs](https://docs.famulor.io/api-v1/webhooks/conversation-ended)","externalDocs":{"description":"Conversation Ended Webhook","url":"https://docs.famulor.io/api-v1/webhooks/conversation-ended"},"security":[],"requestBody":{"required":true,"description":"Payload, den Famulor an deine Webhook-URL sendet.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Numeric identifier of the conversation (the same `id` shown in the dashboard conversation URL). Use `conversation_id` (UUID) when calling the API."},"conversation_id":{"type":"string","description":"Unique identifier (UUID) of the conversation"},"assistant_id":{"type":"string","description":"Unique identifier (UUID) of the assistant that handled the conversation"},"type":{"type":"string","description":"The type of conversation. Possible values: `widget`, `whatsapp`","enum":["widget","whatsapp"]},"message_count":{"type":"integer","description":"Total number of messages exchanged in the conversation"},"status":{"type":"string","description":"Status of the conversation. Value: `ended`"},"extracted_variables":{"type":"object","description":"Variables extracted by AI based on your assistant's post-call schema configuration","properties":{"status":{"type":"boolean","description":"Whether the conversation objective was achieved"},"summary":{"type":"string","description":"Conversation summary"},"custom_variable":{"type":["string","number","boolean"],"description":"Any custom variables you defined in the assistant configuration"}},"additionalProperties":true},"input_variables":{"type":"object","description":"Variables that were passed to the assistant at the start of the conversation (e.g., from pre-chat form fields or automation flows)","additionalProperties":true},"transcript":{"type":"array","description":"Array of message objects representing the full conversation, ordered oldest to newest","items":{"type":"object","properties":{"role":{"type":"string","description":"The sender role: `user`, `assistant`, or `system` (`system` messages mark events such as a human agent taking over the chat)"},"content":{"type":"string","description":"The message text. For media messages this is the caption or a short placeholder (e.g. `[Image]`); audio notes contain the transcribed text"},"timestamp":{"type":"string","description":"ISO 8601 timestamp of the individual message, in the user's configured timezone. Lets you order messages and see how long a conversation spanned (useful for chats that run over several days)"},"timestamp_unix":{"type":"integer","description":"Unix timestamp (seconds since epoch) of the individual message. Convenient for arithmetic — e.g. computing the gap between two messages without parsing the ISO string"}},"additionalProperties":true}},"formatted_transcript":{"type":"string","description":"Human-readable formatted transcript with `AI:` and `Customer:` prefixes"},"attachments":{"type":"array","description":"Media files (images, videos, documents) shared during the conversation. Each entry includes a direct URL you can pass to external services (for example, image or video analysis). This is an empty array when no media was shared — media is typically present on WhatsApp conversations.","items":{"type":"object","properties":{"type":{"type":"string","description":"The media category. Possible values: `image`, `video`, `audio`, `document`","enum":["image","video","audio","document"]},"url":{"type":"string","description":"Direct URL to download the media file"},"filename":{"type":"string","description":"Original file name of the media"}},"additionalProperties":true}},"customer_phone":{"type":["string","null"],"description":"Customer phone number (available for WhatsApp conversations, `null` for widget conversations)"},"customer_name":{"type":"string","description":"Customer name if provided (e.g., from pre-chat form), or `null`"},"sender":{"type":["object","null"],"description":"WhatsApp sender information (only present for WhatsApp conversations, `null` for widget)","properties":{"phone_number":{"type":"string","description":"The WhatsApp sender phone number"},"display_name":{"type":"string","description":"The WhatsApp sender display name"}},"additionalProperties":true},"created_at":{"type":"string","description":"ISO 8601 timestamp when the conversation started (in the user's configured timezone)"},"ended_at":{"type":"string","description":"ISO 8601 timestamp when the conversation ended (in the user's configured timezone)"}},"additionalProperties":true},"example":{"id":1042,"conversation_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","assistant_id":"f9e8d7c6-b5a4-3210-fedc-ba9876543210","type":"widget","message_count":8,"status":"ended","extracted_variables":{"status":true,"summary":"Customer asked about pricing plans and was interested in the Pro plan"},"input_variables":{"name":"John Doe","email":"john@example.com"},"transcript":[{"role":"assistant","content":"Hi! How can I help you today?","timestamp":"2026-02-23T09:30:00+01:00","timestamp_unix":1740299400},{"role":"user","content":"I have a question about your service.","timestamp":"2026-02-23T09:31:12+01:00","timestamp_unix":1740299472},{"role":"assistant","content":"Of course! I'd be happy to help. What would you like to know?","timestamp":"2026-02-23T09:31:18+01:00","timestamp_unix":1740299478},{"role":"user","content":"What are your pricing plans?","timestamp":"2026-02-23T09:32:05+01:00","timestamp_unix":1740299525}],"formatted_transcript":"AI: Hi! How can I help you today?\nCustomer: I have a question about your service.\nAI: Of course! I'd be happy to help. What would you like to know?\nCustomer: What are your pricing plans?","attachments":[],"customer_phone":null,"customer_name":"John Doe","sender":null,"created_at":"2026-02-23T09:30:00+01:00","ended_at":"2026-02-23T10:00:00+01:00"}}}},"responses":{"200":{"description":"Bestätige den Empfang mit 2xx. Antwortet dein Endpunkt nicht mit 2xx, wiederholt Famulor die Zustellung."}}}},"post-call":{"post":{"tags":["Webhooks"],"summary":"Post-Call Webhook","operationId":"webhookPostCall","description":"Webhook sent after a call ends containing extracted variables and call data\n\n[Docs](https://docs.famulor.io/api-v1/webhooks/post-call)","externalDocs":{"description":"Post-Call Webhook","url":"https://docs.famulor.io/api-v1/webhooks/post-call"},"security":[],"requestBody":{"required":true,"description":"Payload, den Famulor an deine Webhook-URL sendet.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier of the call"},"customer_phone":{"type":"string","description":"Customer’s phone number in E.164 format (e.g. \"+1234567890\") or null if not available"},"assistant_phone":{"type":"string","description":"Phone number used by the assistant in E.164 format or null if not available"},"duration":{"type":"integer","description":"Call duration in seconds"},"status":{"type":"string","description":"Final status of the call (e.g. \"completed\", \"busy\", \"failed\")"},"extracted_variables":{"type":"object","description":"Variables extracted by the AI based on your post-call schema configuration","additionalProperties":true},"input_variables":{"type":"object","description":"Variables passed to the assistant before the call started","additionalProperties":true},"transcript":{"type":"string","description":"Full transcript of the conversation"},"recording_url":{"type":"string","description":"URL to download the call recording (only included if \"Include recording in webhook\" is enabled in assistant settings)"},"created_at":{"type":"string","description":"ISO 8601 timestamp of when the call was initiated"},"finished_at":{"type":"string","description":"ISO 8601 timestamp of when the call was completed (taken from the call record’s updated_at)"},"lead":{"type":"object","description":"Lead information (only included for campaign calls)","properties":{"id":{"type":"integer","description":"Unique identifier of the lead"},"phone_number":{"type":"string","description":"Lead's phone number"},"variables":{"type":"object","description":"Variables associated with the lead","additionalProperties":true},"status":{"type":"string","description":"Current status of the lead"},"created_at":{"type":"string","description":"When the lead was created"},"updated_at":{"type":"string","description":"When the lead was last updated"}},"additionalProperties":true},"campaign":{"type":"object","description":"Campaign information (if available)","properties":{"id":{"type":"integer","description":"Campaign ID"},"name":{"type":"string","description":"Campaign name"},"status":{"type":"string","description":"Campaign status"},"allowed_hours_start_time":{"type":"string","description":"Campaign allowed start time"},"allowed_hours_end_time":{"type":"string","description":"Campaign allowed end time"},"allowed_days":{"type":"array","description":"Allowed campaign days","items":{}},"max_calls_in_parallel":{"type":"integer","description":"Maximum concurrent calls for the campaign"},"max_retries":{"type":"integer","description":"Maximum retry attempts for leads"},"retry_interval":{"type":"integer","description":"Retry interval in minutes"},"created_at":{"type":"string","description":"When the campaign was created"},"updated_at":{"type":"string","description":"When the campaign was last updated"}},"additionalProperties":true}},"additionalProperties":true},"example":{"id":480336,"customer_phone":"+4915123456789","assistant_phone":"+4912345678","duration":180,"status":"completed","extracted_variables":{"customer_interested":true,"appointment_scheduled":false,"contact_reason":"product_inquiry","follow_up_needed":true,"customer_budget":"10000-50000","decision_maker":true,"next_contact_date":"2024-02-15"},"input_variables":{"customer_name":"Max Mustermann","company":"Beispiel GmbH"},"transcript":"Assistant: Hello Mr. Mustermann! I am calling from Famulor...\nCustomer: Hello, yes I’m listening...","recording_url":"https://recordings.famulor.de/call-480336.mp3","created_at":"2024-01-15T10:30:00Z","finished_at":"2024-01-15T10:33:00Z","lead":{"id":12345,"phone_number":"+4915123456789","variables":{"customer_name":"Max Mustermann","company":"Beispiel GmbH","source":"website"},"status":"contacted","created_at":"2024-01-14T09:00:00Z","updated_at":"2024-01-15T10:33:00Z"},"campaign":{"id":2324,"name":"New Customer Acquisition Q1 2024","status":"in-progress","allowed_hours_start_time":"09:00:00","allowed_hours_end_time":"18:00:00","allowed_days":["monday","tuesday","wednesday","thursday","friday"],"max_calls_in_parallel":5,"max_retries":3,"retry_interval":60,"created_at":"2024-01-01T08:00:00Z","updated_at":"2024-01-15T10:00:00Z"}}}}},"responses":{"200":{"description":"Bestätige den Empfang mit 2xx. Antwortet dein Endpunkt nicht mit 2xx, wiederholt Famulor die Zustellung."}}}},"read-receipts":{"post":{"tags":["Webhooks"],"summary":"Read Receipts Webhook","operationId":"webhookReadReceipts","description":"Signed webhook sent on every delivery-status change (sent, delivered, read, failed) of a WhatsApp message you send\n\n[Docs](https://docs.famulor.io/api-v1/webhooks/read-receipts)","externalDocs":{"description":"Read Receipts Webhook","url":"https://docs.famulor.io/api-v1/webhooks/read-receipts"},"security":[],"requestBody":{"required":true,"description":"Payload, den Famulor an deine Webhook-URL sendet.","content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string","description":"The event type. Value: `message_status`"},"whatsapp_message_id":{"type":"integer","description":"Numeric identifier of the message — the same `whatsapp_message_id` returned when you sent the message. Use this to correlate the status update with the original send."},"message_sid":{"type":"string","description":"Provider message identifier for messages sent over Twilio, or `null`"},"meta_message_id":{"type":["string","null"],"description":"Provider message identifier (WhatsApp `wamid`) for messages sent over the Meta Cloud API, or `null`"},"conversation_id":{"type":"string","description":"Unique identifier (UUID) of the conversation the message belongs to, or `null`"},"assistant_id":{"type":"string","description":"Unique identifier (UUID) of the assistant connected to the sender, or `null`"},"sender":{"type":"object","description":"The WhatsApp sender the message was sent from","properties":{"id":{"type":"integer","description":"Numeric identifier of the sender"},"phone_number":{"type":"string","description":"The sender's WhatsApp phone number"},"display_name":{"type":"string","description":"The sender's display name"}},"additionalProperties":true},"to":{"type":"string","description":"The recipient phone number"},"from":{"type":"string","description":"The sender phone number"},"direction":{"type":"string","description":"Message direction. Value: `outbound`"},"status":{"type":"string","description":"The new delivery status. Possible values: `sent`, `delivered`, `read`, `failed`, `undelivered`","enum":["sent","delivered","read","failed","undelivered"]},"error_code":{"type":["integer","null"],"description":"Provider error code when `status` is `failed` or `undelivered`, otherwise `null`"},"error_message":{"type":["string","null"],"description":"Raw provider error message when the message failed, otherwise `null`"},"error_description":{"type":["string","null"],"description":"Human-readable description of the error, otherwise `null`"},"timestamp":{"type":"string","description":"ISO 8601 timestamp of when the platform recorded the status change, in the WhatsApp number owner's configured timezone"},"provider_timestamp":{"type":"string","description":"ISO 8601 timestamp of the carrier's own event time, in the owner's configured timezone. Present for messages sent over the Meta Cloud API; `null` over Twilio (Twilio's status callback does not include an event time). Prefer this when present — it is the carrier's authoritative time."}},"additionalProperties":true},"example":{"event":"message_status","whatsapp_message_id":890,"message_sid":"SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx","meta_message_id":null,"conversation_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","assistant_id":"f9e8d7c6-b5a4-3210-fedc-ba9876543210","sender":{"id":42,"phone_number":"+19876543210","display_name":"My Business"},"to":"+1234567890","from":"+19876543210","direction":"outbound","status":"delivered","error_code":null,"error_message":null,"error_description":null,"timestamp":"2026-06-08T09:30:02+00:00","provider_timestamp":"2026-06-08T09:30:00+00:00"}}}},"responses":{"200":{"description":"Bestätige den Empfang mit 2xx. Antwortet dein Endpunkt nicht mit 2xx, wiederholt Famulor die Zustellung."}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API-Key als Bearer-Token: `Authorization: Bearer YOUR_API_KEY`. Key erstellen unter https://app.famulor.de."}},"responses":{"Unauthorized":{"description":"Fehlender oder ungültiger API-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"message":"Unauthenticated."}}}},"ValidationError":{"description":"Die Anfrage ist inhaltlich ungültig.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"example":{"message":"The given data was invalid.","errors":{"phone_number":["The phone number field is required."]}}}}}},"schemas":{"Error":{"type":"object","properties":{"message":{"type":"string","description":"Menschenlesbare Fehlermeldung."},"error":{"type":"string","description":"Fehlerkennung, sofern gesetzt."}}},"ValidationError":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"object","description":"Feldname → Liste der Fehlermeldungen.","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}