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
| Name | Description | Required | Schema |
|---|---|---|---|
| startDate | The start of the window, on conversation creation time (YYYY-MM-DD or an ISO 8601 timestamp) | Yes | string (date) |
| endDate | The end of the window (YYYY-MM-DD or an ISO 8601 timestamp). At most 31 days after startDate | Yes | string (date) |
| page | The page number of the conversation results you want to retrieve | No | integer (>= 1, default: 1) |
| perPage | The number of conversation results you want to display per page | No | integer (1 .. 100, default: 10) |
| statuses | Filter by conversation statuses (comma-separated). Options: closed, human_in_progress, ai_in_progress, pending, classifying, rating | No | string |
| installedSourceIds | Filter by installed source IDs (comma-separated) | No | string |
| assigneeAccountIds | Filter by assignee account IDs (comma-separated) | No | string |
| teamIds | Filter by team IDs (comma-separated) | No | string |
| hasTicket | Filter by whether conversation has a ticket. Options: true, false | No | boolean |
| chatbotEnabled | Filter by whether chatbot is enabled. Options: true, false | No | boolean |
| read | Filter by read status. Options: true, false | No | boolean |
| search | Search term to filter conversations by user name, phone, email, or ticket ID | No | string |
| includeResponseTimes | true adds averageResponseTimeSeconds and averageResponseTimeBusinessHoursSeconds to each conversation. Off by default because it makes the request slower. | No | boolean |
Header Parameters
| Name | Description | Required | Schema |
|---|---|---|---|
| authorization | The authorization token to validate the request. The value should be in the format Bearer <your_api_token> | Yes | string |
| organization-id | The unique identifier of your organization | Yes | string |
| auth-type | token for API tokens | Yes | string |
Responses
| Code | Description | Content type |
|---|---|---|
| 200 | Successful Response | application/json |
| 400 | Invalid parameters, a window longer than 31 days, or a query that took too long | application/json |
| 401 | Missing or invalid token | application/json |
| 403 | The token has no access to this organization | application/json |
| 429 | Rate limit exceeded | application/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.
| Field | Type/Format | Required | Description |
|---|---|---|---|
| items | array of objects | Yes | A list of conversations |
| items._id | string | Yes | The unique identifier of the conversation |
| items.organizationId | string | Yes | The unique identifier of the organization |
| items.installedSourceId | integer | No | The ID of the installed source (channel) |
| items.sourceId | integer | No | The ID of the source |
| items.channel | object | No | The channel: type and name |
| items.user | object | Yes | Information about the user in the conversation |
| items.user.id | string | No | The unique identifier of the user |
| items.user.name | string | No | The name of the user |
| items.user.email | string | No | The email of the user |
| items.user.phone | string | No | The phone number of the user |
| items.user.anonymousId | string | No | The anonymous identifier of the user |
| items.status | string | Yes | The status of the conversation |
| items.assignee | object | null | No | The agent the conversation is assigned to |
| items.assignee.id | integer | Yes | The account ID of the assignee |
| items.assignee.name | string | Yes | The name of the assignee |
| items.assignee.email | string | Yes | The email of the assignee |
| items.assignee.assignedAt | string (date-time) | No | When the assignee was assigned |
| items.team | object | null | No | The team: id (integer) and name |
| items.ticket | object | null | No | The latest ticket linked to the conversation |
| items.ticket.id | integer | Yes | The ID of the ticket |
| items.ticket.subject | string | No | The subject of the ticket |
| items.ticket.status | string | No | The status of the ticket |
| items.ticket.priority | string | No | The priority of the ticket |
| items.ticket.assignee | object | null | No | The assignee of the ticket: id, name, email |
| items.ticket.team | object | null | No | The team of the ticket: id, name |
| items.lastMessage | object | No | Information about the last message |
| items.lastMessage.text | string | No | The text content of the last message |
| items.lastMessage.createdAt | string (date-time) | No | The timestamp when the last message was created |
| items.lastMessage.senderType | string | No | The sender type of the last message (user, assistant, agent) |
| items.read | boolean | Yes | Whether the conversation has been read |
| items.chatbotEnabled | boolean | No | Whether chatbot is enabled for the conversation |
| items.aiPackageEnabled | boolean | No | Whether AI package is enabled for the conversation |
| items.createdAt | string (date-time) | Yes | The timestamp when the conversation was created |
| items.updatedAt | string (date-time) | Yes | The timestamp when the conversation was last updated |
| items.closedAt | string (date-time) | No | When the conversation was closed. Not set while it is open; cleared if the customer writes again during the satisfaction survey |
| items.type | string | No | The type of conversation (chat, call, etc.) |
| items.name | string | No | The name of the conversation |
| items.averageResponseTimeSeconds | integer | null | No | Only 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.averageResponseTimeBusinessHoursSeconds | integer | null | No | Only 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. |
| total | integer | Yes | Total number of conversations matching the filter |
| page | integer | Yes | Current page number |
| perPage | integer | Yes | Number of items per page |
| pages | integer | Yes | Total 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
| Name | Description | Required | Schema |
|---|---|---|---|
| conversationId | The unique identifier of the conversation (_id from the list above) | Yes | string |
Query Parameters
| Name | Description | Required | Schema |
|---|---|---|---|
| page | The page number of the message results you want to retrieve | No | integer (>= 1, default: 1) |
| perPage | The number of message results you want to display per page. Keep it at 100 or less | No | integer (>= 1, default: 20) |
| scope | Filter by message scope. Options: external, internal, social | No | string |
| senderType | Filter by sender type. Options: user, assistant, agent | No | string |
Header Parameters
| Name | Description | Required | Schema |
|---|---|---|---|
| authorization | The authorization token to validate the request. The value should be in the format Bearer <your_api_token> | Yes | string |
| organization-id | The unique identifier of your organization | Yes | string |
| auth-type | token for API tokens | Yes | string |
Responses
| Code | Description | Content type |
|---|---|---|
| 200 | Successful Response | application/json |
| 400 | Invalid parameters, or the conversation was not found | application/json |
| 401 | Missing or invalid token | application/json |
| 403 | The token has no access to this organization | application/json |
| 429 | Rate limit exceeded | application/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.
| Field | Type/Format | Required | Description |
|---|---|---|---|
| items | array of objects | Yes | A list of messages |
| items._id | string | Yes | The unique identifier of the message |
| items.conversationId | string | Yes | The unique identifier of the conversation |
| items.organizationId | string | Yes | The unique identifier of the organization |
| items.text | string | No | The text content of the message |
| items.senderType | string | Yes | The type of sender (user, assistant, agent) |
| items.agent | object | No | The agent who sent the message: id, name, email |
| items.scope | string | Yes | The scope of the message (external, internal, social) |
| items.status | string | No | The status of the message (sent, sending, failed, etc.) |
| items.attachments | array of objects | No | List of attachments in the message |
| items.attachments.url | string | Yes | The URL of the attachment |
| items.attachments.type | string | Yes | The type of attachment (image, file, etc.) |
| items.attachments.name | string | No | The name of the attachment |
| items.attachments.mimeType | string | No | The MIME type of the attachment |
| items.attachments.sizeBytes | integer | No | The size of the attachment in bytes |
| items.createdAt | string (date-time) | Yes | The timestamp when the message was created |
| items.updatedAt | string (date-time) | Yes | The timestamp when the message was last updated |
| items.agentType | string | No | The type of AI agent (qna, survey, greeting, etc.) |
| items.assistantId | string | No | The ID of the assistant that sent the message |
| items.metadata | object | No | Additional metadata about the message |
| total | integer | Yes | Total number of messages in the conversation |
| page | integer | Yes | Current page number |
| perPage | integer | Yes | Number of items per page |
| pages | integer | Yes | Total 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"
}
}
| Code | Example detail.message | What to do |
|---|---|---|
| 400 | Date range cannot exceed 31 days | Split the range into windows of 31 days or less |
| 400 | startDate must not be after endDate | Swap or fix the dates |
| 400 | Query took too long to complete. Narrow the date range or filters, then try again. | Use a shorter window or more filters |
| 400 | Conversation not found (messages endpoint) | Check the conversation ID |
| 401 | Check the token and the auth-type: token header | |
| 403 | organizationId does not match the authenticated organization | Use the organization the token belongs to |
| 429 | Wait and retry with exponential backoff |