curl -X GET "https://app.famulor.de/api/user/conversations?type=whatsapp&per_page=10" \
-H "Authorization: Bearer YOUR_API_KEY"
curl -X GET "https://app.famulor.de/api/user/conversations?customer_phone=+49123456789" \
-H "Authorization: Bearer YOUR_API_KEY"
curl -X GET "https://app.famulor.de/api/user/conversations?whatsapp_sender_phone=+49987654321" \
-H "Authorization: Bearer YOUR_API_KEY"
const response = await fetch(
'https://app.famulor.de/api/user/conversations?type=whatsapp&per_page=10',
{
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
}
);
const data = await response.json();
// Fetch next page using cursor
if (data.next_cursor) {
const nextPage = await fetch(
`https://app.famulor.de/api/user/conversations?cursor=${data.next_cursor}`,
{ headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);
}
import requests
response = requests.get(
'https://app.famulor.de/api/user/conversations',
headers={'Authorization': 'Bearer YOUR_API_KEY'},
params={
'type': 'whatsapp',
'per_page': 10
}
)
data = response.json()
# Fetch next page using cursor
if data.get('next_cursor'):
next_response = requests.get(
'https://app.famulor.de/api/user/conversations',
headers={'Authorization': 'Bearer YOUR_API_KEY'},
params={'cursor': data['next_cursor']}
)
{
"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
}
List Conversations
List all conversations of the authenticated user with filtering and cursor pagination
GET
/
api
/
user
/
conversations
curl -X GET "https://app.famulor.de/api/user/conversations?type=whatsapp&per_page=10" \
-H "Authorization: Bearer YOUR_API_KEY"
curl -X GET "https://app.famulor.de/api/user/conversations?customer_phone=+49123456789" \
-H "Authorization: Bearer YOUR_API_KEY"
curl -X GET "https://app.famulor.de/api/user/conversations?whatsapp_sender_phone=+49987654321" \
-H "Authorization: Bearer YOUR_API_KEY"
const response = await fetch(
'https://app.famulor.de/api/user/conversations?type=whatsapp&per_page=10',
{
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
}
);
const data = await response.json();
// Fetch next page using cursor
if (data.next_cursor) {
const nextPage = await fetch(
`https://app.famulor.de/api/user/conversations?cursor=${data.next_cursor}`,
{ headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);
}
import requests
response = requests.get(
'https://app.famulor.de/api/user/conversations',
headers={'Authorization': 'Bearer YOUR_API_KEY'},
params={
'type': 'whatsapp',
'per_page': 10
}
)
data = response.json()
# Fetch next page using cursor
if data.get('next_cursor'):
next_response = requests.get(
'https://app.famulor.de/api/user/conversations',
headers={'Authorization': 'Bearer YOUR_API_KEY'},
params={'cursor': data['next_cursor']}
)
{
"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
}
This endpoint returns a cursor-paginated list of conversations belonging to the authenticated user’s assistants. Use it to view conversation history, filter by type, or integrate with your CRM.
This endpoint uses cursor-based pagination for better performance with large datasets. Use
next_cursor and prev_cursor to navigate between pages.Query Parameters
string
Filters conversations by type. Possible values:
test, widget, whatsapp, apiinteger
Filters conversations by assistant ID (must belong to the authenticated user)
string
Filters conversations by the customer’s phone number (exact match). Useful for finding all conversations with a specific customer.
string
Filters conversations by WhatsApp sender phone number (exact match). Useful for finding all conversations from a specific WhatsApp Business number.
string
Filters conversations by an external identifier. Useful for finding conversations linked to records in your external system.
integer
Number of conversations per page (1-100, default: 15)
string
Cursor for pagination. Use
next_cursor or prev_cursor from a previous response.Response Fields
array
Show Properties
Show Properties
string
The unique UUID of the conversation
string
The UUID of the assistant handling this conversation
string
The name of the assistant handling this conversation
string
The conversation type:
test, widget, whatsapp, or apiobject
Custom variables associated with the conversation (key-value pairs)
string
The identifier from your external system for this conversation. Only present for conversations of type
api if an external identifier was set.integer
Total number of messages in the conversation
number
The total cost of the conversation in USD
boolean
Indicates if AI responses are enabled for this conversation
string
Date and time when the conversation was created
string
Date and time when the conversation was last updated
object
string
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.string
Cursor to fetch the previous page of results.
null if this is the first page.integer
Number of items per page
curl -X GET "https://app.famulor.de/api/user/conversations?type=whatsapp&per_page=10" \
-H "Authorization: Bearer YOUR_API_KEY"
curl -X GET "https://app.famulor.de/api/user/conversations?customer_phone=+49123456789" \
-H "Authorization: Bearer YOUR_API_KEY"
curl -X GET "https://app.famulor.de/api/user/conversations?whatsapp_sender_phone=+49987654321" \
-H "Authorization: Bearer YOUR_API_KEY"
const response = await fetch(
'https://app.famulor.de/api/user/conversations?type=whatsapp&per_page=10',
{
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
}
);
const data = await response.json();
// Fetch next page using cursor
if (data.next_cursor) {
const nextPage = await fetch(
`https://app.famulor.de/api/user/conversations?cursor=${data.next_cursor}`,
{ headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);
}
import requests
response = requests.get(
'https://app.famulor.de/api/user/conversations',
headers={'Authorization': 'Bearer YOUR_API_KEY'},
params={
'type': 'whatsapp',
'per_page': 10
}
)
data = response.json()
# Fetch next page using cursor
if data.get('next_cursor'):
next_response = requests.get(
'https://app.famulor.de/api/user/conversations',
headers={'Authorization': 'Bearer YOUR_API_KEY'},
params={'cursor': data['next_cursor']}
)
{
"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
}
Conversation Types
| Type | Description |
|---|---|
test | Internal test conversations from the assistant test interface |
widget | Conversations from the web chat widget |
whatsapp | WhatsApp Business conversations |
api | Conversations created via the API |
Filter Parameters
All filter parameters use indexed columns for efficient querying:| Parameter | Description | Use Case |
|---|---|---|
type | Filter by conversation type | Retrieve only WhatsApp or Widget conversations |
assistant_id | Filter by specific assistant | Display conversations for a single assistant |
customer_phone | Filter by customer phone number | Find all conversations with a specific customer |
whatsapp_sender_phone | Filter by WhatsApp sender phone | Find all conversations from a business number |
external_identifier | Filter by your external ID | Link conversations with your CRM records |
WhatsApp Conversation Details
For WhatsApp conversations, the response includes additional fields:- whatsapp_sender: The WhatsApp Business number that conducted the conversation (name and phone number of your WhatsApp sender)
- customer: The customer who initiated or received the conversation (their name and phone number)
whatsapp and help identify the parties involved when integrating with your CRM or support systems.
API Conversation Details
For conversations created via the API, you can set anexternal_identifier when creating the conversation. This identifier is returned in the response and can be used for:
- Linking conversations with your CRM leads or contacts
- Tracking conversations across your internal systems
- Filtering conversations by your external reference
Use Cases
- Analytics Dashboard: Display conversation metrics and trends
- CRM Integration: Sync conversation data with your customer database using
external_identifier - Customer Lookup: Find all conversations with a particular customer via
customer_phone - Quality Monitoring: Review conversation volume by type and assistant
- Billing Audit: Track conversation costs within your organization
Related pages: Introduction and Authentication Guide, and API Integration Examples.
⌘I