Skip to main content
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"

{
  "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

​
type
string
Filters conversations by type. Possible values: test, widget, whatsapp, api
​
assistant_id
integer
Filters conversations by assistant ID (must belong to the authenticated user)
​
customer_phone
string
Filters conversations by the customer’s phone number (exact match). Useful for finding all conversations with a specific customer.
​
whatsapp_sender_phone
string
Filters conversations by WhatsApp sender phone number (exact match). Useful for finding all conversations from a specific WhatsApp Business number.
​
external_identifier
string
Filters conversations by an external identifier. Useful for finding conversations linked to records in your external system.
​
per_page
integer
Number of conversations per page (1-100, default: 15)
​
cursor
string
Cursor for pagination. Use next_cursor or prev_cursor from a previous response.

​
Response Fields

​
data
array
​
next_cursor
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.
​
prev_cursor
string
Cursor to fetch the previous page of results. null if this is the first page.
​
per_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"

{
  "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

TypeDescription
testInternal test conversations from the assistant test interface
widgetConversations from the web chat widget
whatsappWhatsApp Business conversations
apiConversations created via the API

​
Filter Parameters

All filter parameters use indexed columns for efficient querying:
ParameterDescriptionUse Case
typeFilter by conversation typeRetrieve only WhatsApp or Widget conversations
assistant_idFilter by specific assistantDisplay conversations for a single assistant
customer_phoneFilter by customer phone numberFind all conversations with a specific customer
whatsapp_sender_phoneFilter by WhatsApp sender phoneFind all conversations from a business number
external_identifierFilter by your external IDLink 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)
These fields are only present for conversations of type 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 an external_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.