Skip to main content

Export conversations API

Prerequisites​

To use the APIs, you need to have a token. Tokens can be generated by an admin at the setting section in Filum CX platform. Ensure you have the necessary permissions to access the admin settings for token generation.

APIs​

Access the APIs via the endpoint: https://contact-center-scheduler.filum.ai/

https://contact-center.filum.ai/ still serves the same endpoints for existing integrations; new integrations should use the endpoint above.

All parameter and field names are camelCase and case-sensitive. A parameter the API does not know (for example start_date or per_page) is ignored: perPage then falls back to its default, and a missing startDate / endDate returns 400.

GET /external/conversations​

Summary​

Get Conversations

Returns conversations created between startDate and endDate, most recent activity first. The filter is on creation time, so a conversation created before the window does not come back when it is later updated or closed. To pick up changes in near real time, use the conversation sessions API, which filters on the last update.

Query Parameters​

NameDescriptionRequiredSchema
startDateThe start of the window, on conversation creation time (YYYY-MM-DD or an ISO 8601 timestamp)Yesstring (date)
endDateThe end of the window (YYYY-MM-DD or an ISO 8601 timestamp). At most 31 days after startDateYesstring (date)
pageThe page number of the conversation results you want to retrieveNointeger (>= 1, default: 1)
perPageThe number of conversation results you want to display per pageNointeger (1 .. 100, default: 10)
statusesFilter by conversation statuses (comma-separated). Options: closed, human_in_progress, ai_in_progress, pending, classifying, ratingNostring
installedSourceIdsFilter by installed source IDs (comma-separated)Nostring
assigneeAccountIdsFilter by assignee account IDs (comma-separated)Nostring
teamIdsFilter by team IDs (comma-separated)Nostring
hasTicketFilter by whether conversation has a ticket. Options: true, falseNoboolean
chatbotEnabledFilter by whether chatbot is enabled. Options: true, falseNoboolean
readFilter by read status. Options: true, falseNoboolean
searchSearch term to filter conversations by user name, phone, email, or ticket IDNostring
includeResponseTimestrue adds averageResponseTimeSeconds and averageResponseTimeBusinessHoursSeconds to each conversation. Off by default because it makes the request slower.Noboolean

Header Parameters​

NameDescriptionRequiredSchema
authorizationThe authorization token to validate the request. The value should be in the format Bearer <your_api_token>Yesstring
organization-idThe unique identifier of your organizationYesstring
auth-typetoken for API tokensYesstring

Responses​

CodeDescriptionContent type
200Successful Responseapplication/json
400Invalid parameters, a window longer than 31 days, or a query that took too longapplication/json
401Missing or invalid tokenapplication/json
403The token has no access to this organizationapplication/json
429Rate limit exceededapplication/json

200 Successful Response​

Each item is the conversation record. The fields below are the supported ones; other internal fields may also appear and can change without notice.

FieldType/FormatRequiredDescription
itemsarray of objectsYesA list of conversations
items._idstringYesThe unique identifier of the conversation
items.organizationIdstringYesThe unique identifier of the organization
items.installedSourceIdintegerNoThe ID of the installed source (channel)
items.sourceIdintegerNoThe ID of the source
items.channelobjectNoThe channel: type and name
items.userobjectYesInformation about the user in the conversation
items.user.idstringNoThe unique identifier of the user
items.user.namestringNoThe name of the user
items.user.emailstringNoThe email of the user
items.user.phonestringNoThe phone number of the user
items.user.anonymousIdstringNoThe anonymous identifier of the user
items.statusstringYesThe status of the conversation
items.assigneeobject | nullNoThe agent the conversation is assigned to
items.assignee.idintegerYesThe account ID of the assignee
items.assignee.namestringYesThe name of the assignee
items.assignee.emailstringYesThe email of the assignee
items.assignee.assignedAtstring (date-time)NoWhen the assignee was assigned
items.teamobject | nullNoThe team: id (integer) and name
items.ticketobject | nullNoThe latest ticket linked to the conversation
items.ticket.idintegerYesThe ID of the ticket
items.ticket.subjectstringNoThe subject of the ticket
items.ticket.statusstringNoThe status of the ticket
items.ticket.prioritystringNoThe priority of the ticket
items.ticket.assigneeobject | nullNoThe assignee of the ticket: id, name, email
items.ticket.teamobject | nullNoThe team of the ticket: id, name
items.lastMessageobjectNoInformation about the last message
items.lastMessage.textstringNoThe text content of the last message
items.lastMessage.createdAtstring (date-time)NoThe timestamp when the last message was created
items.lastMessage.senderTypestringNoThe sender type of the last message (user, assistant, agent)
items.readbooleanYesWhether the conversation has been read
items.chatbotEnabledbooleanNoWhether chatbot is enabled for the conversation
items.aiPackageEnabledbooleanNoWhether AI package is enabled for the conversation
items.createdAtstring (date-time)YesThe timestamp when the conversation was created
items.updatedAtstring (date-time)YesThe timestamp when the conversation was last updated
items.closedAtstring (date-time)NoWhen the conversation was closed. Not set while it is open; cleared if the customer writes again during the satisfaction survey
items.typestringNoThe type of conversation (chat, call, etc.)
items.namestringNoThe name of the conversation
items.averageResponseTimeSecondsinteger | nullNoOnly with includeResponseTimes=true. Mean time the customer waited for an agent reply, in seconds, over every reply turn of every agent session in the conversation. The first turn is assignment → first agent reply; later turns run from a customer message to the agent's next reply (consecutive customer messages count once). null when no agent replied. Same calculation as the conversation sessions API, averaged across sessions by turn count.
items.averageResponseTimeBusinessHoursSecondsinteger | nullNoOnly with includeResponseTimes=true. The same average with each turn counted only inside your workspace's working hours, in your workspace timezone. Matches "Average Response Time (BHrs)" in the Google Sheets export.
totalintegerYesTotal number of conversations matching the filter
pageintegerYesCurrent page number
perPageintegerYesNumber of items per page
pagesintegerYesTotal number of pages

Response samples

{
"items": [
{
"_id": "507f1f77bcf86cd799439011",
"organizationId": "org_12345",
"installedSourceId": 1,
"sourceId": 10,
"channel": {
"type": "webchat",
"name": "Website chat"
},
"user": {
"id": "user_123",
"name": "John Doe",
"email": "john.doe@example.com",
"phone": "+84901234567",
"anonymousId": null
},
"status": "closed",
"assignee": {
"id": 42,
"name": "Agent Smith",
"email": "agent.smith@company.com",
"assignedAt": "2024-01-15T10:02:00.000Z"
},
"team": {
"id": 5,
"name": "Support Team"
},
"ticket": {
"id": 1001,
"subject": "Order not delivered",
"status": "solved",
"priority": "normal",
"assignee": {
"id": 42,
"name": "Agent Smith",
"email": "agent.smith@company.com"
},
"team": {
"id": 5,
"name": "Support Team"
}
},
"lastMessage": {
"text": "Thank you for your help!",
"createdAt": "2024-01-15T10:30:00.000Z",
"senderType": "user"
},
"read": true,
"chatbotEnabled": false,
"aiPackageEnabled": true,
"createdAt": "2024-01-15T10:00:00.000Z",
"updatedAt": "2024-01-15T10:35:00.000Z",
"closedAt": "2024-01-15T10:35:00.000Z",
"type": "chat",
"name": "Support Inquiry"
}
],
"total": 150,
"page": 1,
"perPage": 10,
"pages": 15
}

GET /external/conversations/{conversationId}/messages​

Summary​

Get Messages for a Conversation

Returns the messages of one conversation, newest first.

Path Parameters​

NameDescriptionRequiredSchema
conversationIdThe unique identifier of the conversation (_id from the list above)Yesstring

Query Parameters​

NameDescriptionRequiredSchema
pageThe page number of the message results you want to retrieveNointeger (>= 1, default: 1)
perPageThe number of message results you want to display per page. Keep it at 100 or lessNointeger (>= 1, default: 20)
scopeFilter by message scope. Options: external, internal, socialNostring
senderTypeFilter by sender type. Options: user, assistant, agentNostring

Header Parameters​

NameDescriptionRequiredSchema
authorizationThe authorization token to validate the request. The value should be in the format Bearer <your_api_token>Yesstring
organization-idThe unique identifier of your organizationYesstring
auth-typetoken for API tokensYesstring

Responses​

CodeDescriptionContent type
200Successful Responseapplication/json
400Invalid parameters, or the conversation was not foundapplication/json
401Missing or invalid tokenapplication/json
403The token has no access to this organizationapplication/json
429Rate limit exceededapplication/json

200 Successful Response​

Each item is the message record. The fields below are the supported ones; other internal fields may also appear and can change without notice.

FieldType/FormatRequiredDescription
itemsarray of objectsYesA list of messages
items._idstringYesThe unique identifier of the message
items.conversationIdstringYesThe unique identifier of the conversation
items.organizationIdstringYesThe unique identifier of the organization
items.textstringNoThe text content of the message
items.senderTypestringYesThe type of sender (user, assistant, agent)
items.agentobjectNoThe agent who sent the message: id, name, email
items.scopestringYesThe scope of the message (external, internal, social)
items.statusstringNoThe status of the message (sent, sending, failed, etc.)
items.attachmentsarray of objectsNoList of attachments in the message
items.attachments.urlstringYesThe URL of the attachment
items.attachments.typestringYesThe type of attachment (image, file, etc.)
items.attachments.namestringNoThe name of the attachment
items.attachments.mimeTypestringNoThe MIME type of the attachment
items.attachments.sizeBytesintegerNoThe size of the attachment in bytes
items.createdAtstring (date-time)YesThe timestamp when the message was created
items.updatedAtstring (date-time)YesThe timestamp when the message was last updated
items.agentTypestringNoThe type of AI agent (qna, survey, greeting, etc.)
items.assistantIdstringNoThe ID of the assistant that sent the message
items.metadataobjectNoAdditional metadata about the message
totalintegerYesTotal number of messages in the conversation
pageintegerYesCurrent page number
perPageintegerYesNumber of items per page
pagesintegerYesTotal number of pages

Response samples

{
"items": [
{
"_id": "65a4f1c2e4b0a1b2c3d4e5f7",
"conversationId": "507f1f77bcf86cd799439011",
"organizationId": "org_12345",
"text": "Sure, I'd be happy to help you with your order. Could you please provide your order number?",
"senderType": "assistant",
"scope": "external",
"status": "sent",
"attachments": [],
"createdAt": "2024-01-15T10:00:30.000Z",
"updatedAt": "2024-01-15T10:00:30.000Z",
"agentType": "qna",
"assistantId": "assistant_abc123",
"metadata": {
"sources": [
{
"title": "Order Support Documentation",
"url": "https://docs.example.com/orders"
}
]
}
},
{
"_id": "65a4f1a4e4b0a1b2c3d4e5f6",
"conversationId": "507f1f77bcf86cd799439011",
"organizationId": "org_12345",
"text": "Hello, I need help with my order",
"senderType": "user",
"scope": "external",
"status": "sent",
"attachments": [
{
"url": "https://example.com/image.jpg",
"type": "image",
"name": "order-screenshot.jpg",
"mimeType": "image/jpeg",
"sizeBytes": 48213
}
],
"createdAt": "2024-01-15T10:00:00.000Z",
"updatedAt": "2024-01-15T10:00:00.000Z"
}
],
"total": 25,
"page": 1,
"perPage": 20,
"pages": 2
}

Usage Examples​

Example 1: Get all conversations created in January 2024​

curl -X GET "https://contact-center-scheduler.filum.ai/external/conversations?startDate=2024-01-01&endDate=2024-01-31&page=1&perPage=50" \
-H "authorization: Bearer your_api_token_here" \
-H "organization-id: your_organization_id_here" \
-H "auth-type: token"

Read pages from the first response and request page=2, page=3, … until you reach it. For a range longer than 31 days, send one request series per window of 31 days or less.

Example 2: Include Average Response Time​

curl -X GET "https://contact-center-scheduler.filum.ai/external/conversations?startDate=2024-01-01&endDate=2024-01-31&perPage=50&includeResponseTimes=true" \
-H "authorization: Bearer your_api_token_here" \
-H "organization-id: your_organization_id_here" \
-H "auth-type: token"

Each item then also carries:

{
"averageResponseTimeSeconds": 95,
"averageResponseTimeBusinessHoursSeconds": 80
}

Example 3: Get messages for a specific conversation​

curl -X GET "https://contact-center-scheduler.filum.ai/external/conversations/507f1f77bcf86cd799439011/messages?page=1&perPage=50" \
-H "authorization: Bearer your_api_token_here" \
-H "organization-id: your_organization_id_here" \
-H "auth-type: token"

Rate Limiting​

The API endpoints are rate-limited to ensure fair usage and system stability. The default rate limits are:

  • Per second: 5 requests
  • Per minute: 50 requests

If you exceed these limits, you will receive a 429 Too Many Requests response. Please implement appropriate retry logic with exponential backoff in your integration.

Error Responses​

Every error has the same shape: a detail.message that says what went wrong.

{
"detail": {
"message": "Date range cannot exceed 31 days"
}
}
CodeExample detail.messageWhat to do
400Date range cannot exceed 31 daysSplit the range into windows of 31 days or less
400startDate must not be after endDateSwap or fix the dates
400Query took too long to complete. Narrow the date range or filters, then try again.Use a shorter window or more filters
400Conversation not found (messages endpoint)Check the conversation ID
401Check the token and the auth-type: token header
403organizationId does not match the authenticated organizationUse the organization the token belongs to
429Wait and retry with exponential backoff