Famulor Conversations API
Konversationen auflisten und die KI pro Konversation steuern.
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-conversations-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 Conversations 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: Conversations
description: Konversationen auflisten und die KI pro Konversation steuern.
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
Docs'
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:
* `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
Docs'
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:
* `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'
/user/conversations:
get:
tags:
- Conversations
summary: List Conversations
operationId: listConversations
description: 'List all conversations of the authenticated user with filtering and cursor pagination
Docs'
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'
components:
responses:
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.
Unauthorized:
description: Fehlender oder ungültiger API-Key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Unauthenticated.
schemas:
ValidationError:
type: object
properties:
message:
type: string
errors:
type: object
description: Feldname → Liste der Fehlermeldungen.
additionalProperties:
type: array
items:
type: string
Error:
type: object
properties:
message:
type: string
description: Menschenlesbare Fehlermeldung.
error:
type: string
description: Fehlerkennung, sofern gesetzt.
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