Skip to main content
GET
/
user
/
conversations
curl -X GET "https://app.autocalls.ai/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.autocalls.ai/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 this to display 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
Filter conversations by type. Possible values: test, widget, whatsapp, api
​
assistant_id
integer
Filter conversations by assistant ID (must belong to the authenticated user)
​
customer_phone
string
Filter conversations by customer phone number (exact match). Useful for finding all conversations with a specific customer.
​
whatsapp_sender_phone
string
Filter conversations by WhatsApp sender phone number (exact match). Useful for finding all conversations from a specific WhatsApp business number.
​
external_identifier
string
Filter conversations by external identifier. Useful for finding conversations linked to your external system records.
​
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 more 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.autocalls.ai/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.autocalls.ai/api/user/conversations",
  "per_page": 15,
  "next_cursor": "eyJpZCI6MTAwLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9",
  "prev_cursor": null
}

​
Conversation Types

TypeDescription
testInternal test conversations from the assistant testing 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 typeGet only WhatsApp or widget conversations
assistant_idFilter by specific assistantView 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 specific business number
external_identifierFilter by your external IDLink conversations to your CRM records

​
WhatsApp Conversation Details

For WhatsApp conversations, the response includes additional fields:
  • whatsapp_sender: The business WhatsApp number that handled the conversation (your WhatsApp sender’s name and phone)
  • customer: The customer who initiated or received the conversation (their name and phone number)
These fields are only present for whatsapp type conversations and help you identify the parties involved when integrating with your CRM or support systems.

​
API Conversation Details

For API-created conversations, you can set an external_identifier when creating the conversation. This identifier is returned in the response and can be used to:
  • Link conversations to your CRM leads or contacts
  • Track conversations across your internal systems
  • Filter 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 specific customer using customer_phone
  • Quality Monitoring: Review conversation volumes by type and assistant
  • Billing Review: Track conversation costs across your organization