Famulor Webhooks API
Ereignis-Callbacks, die Famulor an deine URL sendet.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/famulor-io:famulor-io-webhooks-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Famulor Webhooks 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
AI-Assistenten, startest und liest Anrufe, verwaltest Leads und Kampagnen,
versendest SMS und WhatsApp-Nachrichten, pflegst Wissensdatenbanken und
automatisierst Prozesse.
## Authentifizierung
Alle Endpunkte erwarten einen API-Key als Bearer-Token:
```
Authorization: Bearer YOUR_API_KEY
```
Den Key erstellst du in deinem Account unter im
Bereich API-Keys. Der Key wird nur einmal angezeigt.
## Webhooks
Famulor sendet Ereignisse (Post-Call, Conversation Ended, Read Receipts) an
deine URL. Die Payloads stehen im Abschnitt `webhooks` dieser Spec.
Diese Datei wird aus der offiziellen Dokumentation generiert:'
version: 1.0.0
contact:
name: Famulor Support
email: sales@famulor.io
url: https://www.famulor.io/support
license:
name: Proprietary
url: https://www.famulor.io/terms
termsOfService: https://www.famulor.io/terms
servers:
- url: https://app.famulor.de/api
description: Production
security:
- BearerAuth: []
tags:
- name: Webhooks
description: Ereignis-Callbacks, die Famulor an deine URL sendet.
paths: {}
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
Docs'
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?
Customer: I have a question about your service.
AI: Of course! I''d be happy to help. What would you like to know?
Customer: 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
Docs'
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...
Customer: 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
Docs'
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.'
externalDocs:
description: Famulor API-Dokumentation
url: https://docs.famulor.io/api-v1/introduction