Export conversation sessions API
Returns one row per (agent session × matched ticket) for a date window — the same shape as Filum's scheduled Google Sheets export, exposed as a paginated JSON endpoint. A single conversation may produce several rows when it is handed between multiple agents and/or produces multiple tickets.
Prerequisites
To use the API, you need a token. Tokens can be generated by an admin in the settings section of the Filum CX platform. The token's permission set must include the $export_conversation_session resource with the list action.
API
Access the API via the endpoint: https://contact-center-scheduler.filum.ai/
GET /external/conversation-sessions
Summary
List per-agent conversation sessions joined with their tickets, filtered by conversation updatedAt window.
Query parameters
| Name | Description | Required | Schema |
|---|---|---|---|
startDate | Inclusive lower bound on the conversation updatedAt. Either a plain date (2026-04-06, snapped to 00:00:00 in timezone) or a full ISO 8601 timestamp (2026-04-06T10:00:00Z, used exactly as given) for sub-day incremental pulls. Conversations created before this bound are still returned if they had activity (new message, status change, etc.) inside the window. | Yes | string (date or date-time) |
endDate | Inclusive upper bound on the conversation updatedAt. Same format rules as startDate: a plain date snaps to 23:59:59.999 in timezone, a full timestamp is used as given. The window from startDate to endDate can be at most 31 days. | Yes | string (date or date-time) |
timezone | IANA timezone for interpreting plain-date startDate / endDate boundaries and for computing business-hours metrics. Defaults to your workspace timezone. | No | string |
organizationId | Optional. When provided, must equal the organization you are authenticated against (403 otherwise). The request is always scoped to your authenticated organization regardless. | No | string |
sessionAgentEmails | Comma-separated list of session agent emails to filter by. | No | string |
assigneeAccountIds | Comma-separated list of agent account ids (matches either the session-derived agent or the ticket's assignee_account_id). | No | string |
sessionEndReasons | Comma-separated list of session end reasons. Options: handoff_to_ai, terminal, replaced_by_other_handoff, service_account_takeover, open_at_end. | No | string |
cursor | Opaque cursor from the previous response's nextCursor. Omit on the first call. | No | string |
perPage | Conversations per page. Each conversation can expand to several rows (one per agent session × matched ticket), so a page usually holds 1–3× this many rows. | No | integer (1..100, default: 25) |
Header parameters
| Name | Description | Required | Schema |
|---|---|---|---|
authorization | The authorization token. Format: Bearer <your_api_token> | Yes | string |
organization-id | The unique identifier of your organization | Yes | string |
auth-type | The type of authorization. Options: token (for API tokens), account (for user sessions). | Yes | string |
Responses
| Code | Description | Content type |
|---|---|---|
| 200 | Successful response | application/json |
| 400 | Invalid parameters (bad date, window over 31 days, perPage out of range) | application/json |
| 401 | Unauthorized | application/json |
| 403 | organizationId does not match the authenticated organization | application/json |
| 429 | Rate limit exceeded | application/json |
200 Successful response
Top-level envelope (cursor-paginated):
| Field | Type | Description |
|---|---|---|
items | array of ConversationSession | The conversation-session rows of this page |
nextCursor | string | null | Pass as cursor to get the next page. null on the last page. |
hasMore | boolean | true when there is another page |
Pages are ordered by conversation (updatedAt, _id) ascending.
ConversationSession item:
| Field | Type | Description |
|---|---|---|
| Session | One row per agent engagement window within a conversation. | |
sessionIndex | integer | null | Zero-based index of this session within its conversation. null for rows that represent a ticket with no matched session. |
sessionAgentEmail | string | Agent who handled this session. Blank when the session activity carried no agent identity (e.g. an unattended route_back_to_human). |
sessionAgentName | string | Agent display name. |
sessionAgentAccountId | integer | null | Agent account id from the activity stream. |
sessionStartAt | string (date-time) | null | When the agent's session window opened (assign / route_back_to_human / human_take_over). |
sessionTookOverAt | string (date-time) | null | When the agent explicitly took over, if distinct from the start. |
sessionEndAt | string (date-time) | null | When the session closed (terminal action or handoff). |
sessionStartAction | string | The activity action that opened the session. |
sessionEndAction | string | The activity action that closed it (end_conversation, route_to_ai, route_to_rating, timed_out, …). |
sessionEndReason | string | Higher-level reason: handoff_to_ai, terminal, replaced_by_other_handoff, service_account_takeover, open_at_end. |
| Conversation | Conversation-level fields (same value across every session row of the same conversation). | |
conversationId | string | The Mongo _id of the conversation. |
conversationCreatedAt | string (date-time) | null | |
conversationUpdatedAt | string (date-time) | The conversation's updatedAt, bumped by any write (new message, status change, assignment, …). This is the field startDate / endDate filter on; use it to anchor your next incremental pull. |
conversationRoutedToAiAt | string (date-time) | null | First route_to_ai / route_back_to_ai event on the conversation. |
conversationRoutedToAgentAt | string (date-time) | null | First route_to_human / route_back_to_human event. |
conversationAssignedAt | string (date-time) | null | First assign event. |
conversationAgentTookOverAt | string (date-time) | null | First human_take_over event. |
sentToRatingAt | string (date-time) | null | The route_to_rating event that closed this session (per-session, not conv-level). |
conversationClosedAt | string (date-time) | null | The conversation's close timestamp from Mongo. |
conversationResolvedAt | string (date-time) | null | The conversation-level "resolved" anchor used by Resolution Time (= conversationClosedAt). |
| Customer | Snapshot of the user object on the conversation. | |
customerFilumId | string | |
customerName | string | |
customerPhone | string | |
customerEmail | string | |
| Ticket | The ticket matched to this session by (assignee_account_id, time window). Fields are blank when the row is a session with no matched ticket. | |
ticketId | integer | null | |
ticketCreatedAt | string (date-time) | null | |
ticketUpdatedAt | string (date-time) | null | |
ticketSubject | string | |
ticketDescription | string | |
ticketStatus | string | |
ticketPriority | string | |
ticketDueDate | string (date-time) | null | |
ticketAssignedAt | string (date-time) | null | |
ticketResolvedAt | string (date-time) | null | |
installedSourceId | integer | null | |
installedSourceName | string | |
channelType | string | E.g. chat. |
ticketAssigneeName | string | null | The ticket's current assignee. |
ticketAssigneeEmail | string | null | |
| Metric endpoints | The anchor timestamps used to compute durations. | |
botHandoffAt | string (date-time) | null | Latest route_to_human / route_back_to_human at or before the session start (bounded to "after the previous session ended" and within 24h of the session start). Falls back to sessionStartAt if no qualifying handoff exists. |
firstAgentAssignedAt | string (date-time) | null | sessionTookOverAt ?? sessionStartAt. |
firstAgentMessageAt | string (date-time) | null | First senderType=agent message strictly after firstAgentAssignedAt, inside the session window. |
lastAgentMessageAt | string (date-time) | null | Last senderType=agent message inside the session window. |
conversationFirstAssignedAt | string (date-time) | null | The conversation's first agent assignment (earliest agent session start). Same value on every row of the conversation. |
| Metrics (calendar hours) | Plain elapsed time, in seconds. null when an endpoint is missing. | |
timeToAssignSeconds | integer | null | Last bot message (or conversation creation when there is no bot) → first agent assignment. Conversation-level; null when never assigned. |
waitTimeSeconds | integer | null | firstAgentMessageAt − botHandoffAt. |
firstResponseTimeSeconds | integer | null | firstAgentMessageAt − firstAgentAssignedAt. |
averageResponseTimeSeconds | integer | null | Mean time the customer waited for an agent reply in this session. Turn 1 is the First Response Time; each later turn is a customer message → the agent's next reply, where a run of consecutive customer messages counts once (from the first unanswered one). null when the agent never replied, same as Wait Time and First Response Time. |
resolutionTimeSeconds | integer | null | conversationResolvedAt − botHandoffAt. |
botResolutionTimeSeconds | integer | null | Conversation routed to AI → resolved, independent of any ticket or session. |
wasDeflected | boolean | true when the bot resolved the conversation without a human agent ever being involved. |
| Metrics (business hours) | Same spans intersected with the org's working-hours schedule in timezone. These are the "(BHrs)" columns of the Google Sheets export. | |
timeToAssignBusinessHoursSeconds | integer | null | |
waitTimeBusinessHoursSeconds | integer | null | |
firstResponseTimeBusinessHoursSeconds | integer | null | |
averageResponseTimeBusinessHoursSeconds | integer | null | Average Response Time (BHrs): each turn of averageResponseTimeSeconds counted only within working hours. |
resolutionTimeBusinessHoursSeconds | integer | null | |
totalResolutionTimeBusinessHoursSeconds | integer | null | Bot handoff → ticket resolution (includes a 30-minute wind-down grace). Falls back to conversationResolvedAt when there is no ticket. |
agentResolutionTimeBusinessHoursSeconds | integer | null | First agent assignment → ticket resolution (includes a 30-minute wind-down grace). Falls back to conversationResolvedAt when there is no ticket. |
| Chat session category | Classifies bot handoff → resolution against the working-hours schedule. All four fields are null when the org has no schedule, or the handoff/resolution day has no working window. | |
chatType | string | null | One of within-bhrs, spillover, backlog, out-of-bhrs, aged. |
isBau | boolean | null | true for within-bhrs, backlog, out-of-bhrs. |
includeInNormalizedMetrics | boolean | null | true unless chatType is aged. |
includeInLaBenchmark | boolean | null | true only when chatType is within-bhrs. |
| CSAT | ||
rating | integer | null | Survey star rating, if the customer responded. |
resolutionYesNo | string | Yes if the survey carried an explicit resolution=1 metric or the rating was ≥ 4; No if resolution=0 or rating ≤ 3; empty when no survey. |
feedback | string | Free-text feedback, if any. |
submittedAt | string (date-time) | null | When the survey was submitted. |
| Custom fields | ||
customFields | object ({ [name: string]: string }) | Per-ticket custom fields, keyed by the field's display name. |
Response sample
{
"items": [
{
"sessionIndex": 0,
"sessionAgentEmail": "alice@yourorg.com",
"sessionAgentName": "Alice Tan",
"sessionAgentAccountId": 1799,
"sessionStartAt": "2026-05-08T15:02:33.000Z",
"sessionTookOverAt": "2026-05-08T15:08:55.000Z",
"sessionEndAt": "2026-05-08T15:09:56.000Z",
"sessionStartAction": "assign",
"sessionEndAction": "route_to_rating",
"sessionEndReason": "terminal",
"conversationId": "69fdf7f9e1e9bcb8cf2bc4b9",
"conversationCreatedAt": "2026-05-08T14:49:00.000Z",
"conversationUpdatedAt": "2026-05-08T23:45:00.000Z",
"conversationRoutedToAiAt": "2026-05-08T14:49:00.000Z",
"conversationRoutedToAgentAt": "2026-05-08T14:52:00.000Z",
"conversationAssignedAt": "2026-05-08T15:02:00.000Z",
"conversationAgentTookOverAt": "2026-05-08T15:08:00.000Z",
"sentToRatingAt": "2026-05-08T15:09:38.000Z",
"conversationClosedAt": "2026-05-08T23:45:00.000Z",
"conversationResolvedAt": "2026-05-08T23:45:00.000Z",
"customerFilumId": "fil_123",
"customerName": "FaFa",
"customerPhone": "+60129666852",
"customerEmail": null,
"ticketId": 705854,
"ticketCreatedAt": "2026-05-08T15:09:54.741Z",
"ticketUpdatedAt": "2026-05-08T15:14:45.354Z",
"ticketSubject": "Request from WhatsApp - FaFa",
"ticketDescription": "",
"ticketStatus": "closed",
"ticketPriority": "low",
"ticketDueDate": null,
"ticketAssignedAt": "2026-05-08T15:02:00.000Z",
"ticketResolvedAt": "2026-05-08T15:09:54.741Z",
"installedSourceId": 6537,
"installedSourceName": "WhatsApp MY",
"channelType": "chat",
"ticketAssigneeName": "Alice Tan",
"ticketAssigneeEmail": "alice@yourorg.com",
"botHandoffAt": "2026-05-08T14:52:21.000Z",
"firstAgentAssignedAt": "2026-05-08T15:08:55.000Z",
"firstAgentMessageAt": "2026-05-08T15:09:03.000Z",
"lastAgentMessageAt": "2026-05-08T15:09:32.000Z",
"conversationFirstAssignedAt": "2026-05-08T15:02:33.000Z",
"timeToAssignSeconds": 612,
"waitTimeSeconds": 1002,
"firstResponseTimeSeconds": 8,
"averageResponseTimeSeconds": 14,
"resolutionTimeSeconds": 31959,
"botResolutionTimeSeconds": null,
"wasDeflected": false,
"timeToAssignBusinessHoursSeconds": 612,
"waitTimeBusinessHoursSeconds": 1002,
"firstResponseTimeBusinessHoursSeconds": 8,
"averageResponseTimeBusinessHoursSeconds": 14,
"resolutionTimeBusinessHoursSeconds": 28800,
"totalResolutionTimeBusinessHoursSeconds": 28800,
"agentResolutionTimeBusinessHoursSeconds": 27900,
"chatType": "spillover",
"isBau": false,
"includeInNormalizedMetrics": true,
"includeInLaBenchmark": false,
"rating": 5,
"resolutionYesNo": "Yes",
"feedback": "",
"submittedAt": "2026-05-08T15:10:30.000Z",
"customFields": {
"Outlet Name": "ZUS KLCC",
"Ticket Category 1": "Order",
"Ticket Category 2": "Refund"
}
}
],
"nextCursor": "eyJ1cGRhdGVkQXQiOiIyMDI2LTA1LTA4VDIzOjQ1OjAwLjAwMFoiLCJpZCI6IjY5ZmRmN2Y5ZTFlOWJjYjhjZjJiYzRiOSJ9",
"hasMore": true
}
GET /external/conversation-sessions/{conversationId}
Summary
Get the per-agent session rows for a single conversation, looked up by its conversation id — no date window needed. Returns the same row shape as the list endpoint. Useful when you already know which conversation you care about (e.g. from a webhook payload or the conversationId field of a previously exported row) and want its latest session/ticket/metric breakdown.
Path parameters
| Name | Description | Required | Schema |
|---|---|---|---|
conversationId | The conversation id (the same value returned as conversationId in export rows). | Yes | string |
Query parameters
| Name | Description | Required | Schema |
|---|---|---|---|
timezone | IANA timezone for computing business-hours metrics. Defaults to Asia/Singapore. | No | string |
organizationId | Optional. When provided, must equal the organization you are authenticated against (403 otherwise). The request is always scoped to your authenticated organization regardless. | No | string |
Header parameters
Same as the list endpoint (authorization, organization-id, auth-type).
Responses
| Code | Description | Content type |
|---|---|---|
| 200 | Successful response | application/json |
| 401 | Unauthorized | application/json |
| 404 | Conversation not found in the organization | application/json |
| 429 | Rate limit exceeded | application/json |
200 Successful response
| Field | Type | Description |
|---|---|---|
items | array of ConversationSession | Every session row of the conversation — one per (agent session × matched ticket), same item schema as the list endpoint. |
No pagination fields — a single conversation only expands to a handful of rows (typically 1–5).
Usage examples
Pull all conversation sessions for last week
curl -X GET "https://contact-center-scheduler.filum.ai/external/conversation-sessions?startDate=2026-06-02&endDate=2026-06-08&timezone=Asia/Kuala_Lumpur&perPage=100" \
-H "authorization: Bearer your_api_token_here" \
-H "organization-id: your_organization_id_here" \
-H "auth-type: token"
Filter to a single agent's sessions
curl -X GET "https://contact-center-scheduler.filum.ai/external/conversation-sessions?startDate=2026-06-01&endDate=2026-06-08&sessionAgentEmails=alice@yourorg.com&perPage=100" \
-H "authorization: Bearer your_api_token_here" \
-H "organization-id: your_organization_id_here" \
-H "auth-type: token"
Only completed (rated) sessions, by account id
curl -X GET "https://contact-center-scheduler.filum.ai/external/conversation-sessions?startDate=2026-06-01&endDate=2026-06-08&assigneeAccountIds=1799,1798&sessionEndReasons=terminal" \
-H "authorization: Bearer your_api_token_here" \
-H "organization-id: your_organization_id_here" \
-H "auth-type: token"
Look up a single conversation by id
curl -X GET "https://contact-center-scheduler.filum.ai/external/conversation-sessions/69fdf7f9e1e9bcb8cf2bc4b9?timezone=Asia/Kuala_Lumpur" \
-H "authorization: Bearer your_api_token_here" \
-H "organization-id: your_organization_id_here" \
-H "auth-type: token"
Paginate through a large window
CURSOR=""
while : ; do
RESP=$(curl -sG "https://contact-center-scheduler.filum.ai/external/conversation-sessions" \
--data-urlencode "startDate=2026-04-01" \
--data-urlencode "endDate=2026-04-30" \
--data-urlencode "perPage=100" \
${CURSOR:+--data-urlencode "cursor=$CURSOR"} \
-H "authorization: Bearer your_api_token_here" \
-H "organization-id: your_organization_id_here" \
-H "auth-type: token")
echo "$RESP"
CURSOR=$(echo "$RESP" | jq -r '.nextCursor // empty')
[ -z "$CURSOR" ] && break
done
Incremental pulls
To pull only what changed since your last run, keep the largest conversationUpdatedAt you received and pass it as startDate (a full timestamp is used exactly as given):
curl -sG "https://contact-center-scheduler.filum.ai/external/conversation-sessions" \
--data-urlencode "startDate=2026-06-08T09:30:00Z" \
--data-urlencode "endDate=2026-06-08T10:30:00Z" \
-H "authorization: Bearer your_api_token_here" \
-H "organization-id: your_organization_id_here" \
-H "auth-type: token"
Notes
Date filter semantics
startDate and endDate filter on the conversation's updatedAt, not createdAt. A long-running conversation that was created last month but had activity (new messages, status changes, etc.) inside your window is still returned. This matches what an analyst pulling "what happened this week" typically wants.
Multi-row conversations
A single conversation can appear in multiple rows when:
- It is handed off between multiple agents — each handler gets one session row.
- It produces multiple tickets — each ticket is paired with its session by
(assignee_account_id, time window). - An agent's session ends before the ticket is finally resolved —
conversationResolvedAtis shared across every session row of that conversation, so resolution-time calculations are anchored on the chat close (customer POV), not the per-session end.
Sessions that never carry an agent identity (e.g. an unattended route_back_to_human) are still emitted with blank session-agent fields and no matched ticket. Filter them out with WHERE session_agent_email != '' if you only want rows representing a real human handler.
Window guidance
One request covers at most 31 days (400 otherwise). Each page only touches perPage conversations, so page latency does not grow with the window. For longer historical pulls, walk consecutive 31-day windows, or contact your Filum representative for a one-off export.
Rate limiting
The endpoint is rate-limited:
- Per second: 5 requests
- Per minute: 50 requests
Exceeding these limits returns 429 Too Many Requests. Implement retry with exponential backoff.
Error responses
401 Unauthorized
{ "detail": { "message": "Unauthorized" } }
Either the token is invalid, the organization-id header is missing, or the token's permission set does not include $export_conversation_session:list.
400 Bad request
{ "detail": { "message": "Date range cannot exceed 31 days" } }
Returned for a missing or malformed startDate / endDate, a startDate after endDate, a window longer than 31 days, or a perPage outside 1–100. Split longer periods into windows of 31 days or less.
403 Forbidden
{ "detail": { "message": "organizationId does not match the authenticated organization" } }
The organizationId query parameter, if provided, must equal the organization your token is authenticated against.
404 Not found (by-id endpoint only)
{ "detail": { "message": "Conversation 69fdf7f9e1e9bcb8cf2bc4b9 not found" } }
The conversation id does not exist, or it belongs to a different organization than the one you are authenticated against.
429 Too many requests
{ "detail": "Rate limit exceeded" }