Skip to main content

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​

NameDescriptionRequiredSchema
startDateInclusive 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.Yesstring (date or date-time)
endDateInclusive 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.Yesstring (date or date-time)
timezoneIANA timezone for interpreting plain-date startDate / endDate boundaries and for computing business-hours metrics. Defaults to your workspace timezone.Nostring
organizationIdOptional. When provided, must equal the organization you are authenticated against (403 otherwise). The request is always scoped to your authenticated organization regardless.Nostring
sessionAgentEmailsComma-separated list of session agent emails to filter by.Nostring
assigneeAccountIdsComma-separated list of agent account ids (matches either the session-derived agent or the ticket's assignee_account_id).Nostring
sessionEndReasonsComma-separated list of session end reasons. Options: handoff_to_ai, terminal, replaced_by_other_handoff, service_account_takeover, open_at_end.Nostring
cursorOpaque cursor from the previous response's nextCursor. Omit on the first call.Nostring
perPageConversations 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.Nointeger (1..100, default: 25)

Header parameters​

NameDescriptionRequiredSchema
authorizationThe authorization token. Format: Bearer <your_api_token>Yesstring
organization-idThe unique identifier of your organizationYesstring
auth-typeThe type of authorization. Options: token (for API tokens), account (for user sessions).Yesstring

Responses​

CodeDescriptionContent type
200Successful responseapplication/json
400Invalid parameters (bad date, window over 31 days, perPage out of range)application/json
401Unauthorizedapplication/json
403organizationId does not match the authenticated organizationapplication/json
429Rate limit exceededapplication/json

200 Successful response​

Top-level envelope (cursor-paginated):

FieldTypeDescription
itemsarray of ConversationSessionThe conversation-session rows of this page
nextCursorstring | nullPass as cursor to get the next page. null on the last page.
hasMorebooleantrue when there is another page

Pages are ordered by conversation (updatedAt, _id) ascending.

ConversationSession item:

FieldTypeDescription
SessionOne row per agent engagement window within a conversation.
sessionIndexinteger | nullZero-based index of this session within its conversation. null for rows that represent a ticket with no matched session.
sessionAgentEmailstringAgent who handled this session. Blank when the session activity carried no agent identity (e.g. an unattended route_back_to_human).
sessionAgentNamestringAgent display name.
sessionAgentAccountIdinteger | nullAgent account id from the activity stream.
sessionStartAtstring (date-time) | nullWhen the agent's session window opened (assign / route_back_to_human / human_take_over).
sessionTookOverAtstring (date-time) | nullWhen the agent explicitly took over, if distinct from the start.
sessionEndAtstring (date-time) | nullWhen the session closed (terminal action or handoff).
sessionStartActionstringThe activity action that opened the session.
sessionEndActionstringThe activity action that closed it (end_conversation, route_to_ai, route_to_rating, timed_out, …).
sessionEndReasonstringHigher-level reason: handoff_to_ai, terminal, replaced_by_other_handoff, service_account_takeover, open_at_end.
ConversationConversation-level fields (same value across every session row of the same conversation).
conversationIdstringThe Mongo _id of the conversation.
conversationCreatedAtstring (date-time) | null
conversationUpdatedAtstring (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.
conversationRoutedToAiAtstring (date-time) | nullFirst route_to_ai / route_back_to_ai event on the conversation.
conversationRoutedToAgentAtstring (date-time) | nullFirst route_to_human / route_back_to_human event.
conversationAssignedAtstring (date-time) | nullFirst assign event.
conversationAgentTookOverAtstring (date-time) | nullFirst human_take_over event.
sentToRatingAtstring (date-time) | nullThe route_to_rating event that closed this session (per-session, not conv-level).
conversationClosedAtstring (date-time) | nullThe conversation's close timestamp from Mongo.
conversationResolvedAtstring (date-time) | nullThe conversation-level "resolved" anchor used by Resolution Time (= conversationClosedAt).
CustomerSnapshot of the user object on the conversation.
customerFilumIdstring
customerNamestring
customerPhonestring
customerEmailstring
TicketThe ticket matched to this session by (assignee_account_id, time window). Fields are blank when the row is a session with no matched ticket.
ticketIdinteger | null
ticketCreatedAtstring (date-time) | null
ticketUpdatedAtstring (date-time) | null
ticketSubjectstring
ticketDescriptionstring
ticketStatusstring
ticketPrioritystring
ticketDueDatestring (date-time) | null
ticketAssignedAtstring (date-time) | null
ticketResolvedAtstring (date-time) | null
installedSourceIdinteger | null
installedSourceNamestring
channelTypestringE.g. chat.
ticketAssigneeNamestring | nullThe ticket's current assignee.
ticketAssigneeEmailstring | null
Metric endpointsThe anchor timestamps used to compute durations.
botHandoffAtstring (date-time) | nullLatest 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.
firstAgentAssignedAtstring (date-time) | nullsessionTookOverAt ?? sessionStartAt.
firstAgentMessageAtstring (date-time) | nullFirst senderType=agent message strictly after firstAgentAssignedAt, inside the session window.
lastAgentMessageAtstring (date-time) | nullLast senderType=agent message inside the session window.
conversationFirstAssignedAtstring (date-time) | nullThe 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.
timeToAssignSecondsinteger | nullLast bot message (or conversation creation when there is no bot) → first agent assignment. Conversation-level; null when never assigned.
waitTimeSecondsinteger | nullfirstAgentMessageAt − botHandoffAt.
firstResponseTimeSecondsinteger | nullfirstAgentMessageAt − firstAgentAssignedAt.
averageResponseTimeSecondsinteger | nullMean 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.
resolutionTimeSecondsinteger | nullconversationResolvedAt − botHandoffAt.
botResolutionTimeSecondsinteger | nullConversation routed to AI → resolved, independent of any ticket or session.
wasDeflectedbooleantrue 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.
timeToAssignBusinessHoursSecondsinteger | null
waitTimeBusinessHoursSecondsinteger | null
firstResponseTimeBusinessHoursSecondsinteger | null
averageResponseTimeBusinessHoursSecondsinteger | nullAverage Response Time (BHrs): each turn of averageResponseTimeSeconds counted only within working hours.
resolutionTimeBusinessHoursSecondsinteger | null
totalResolutionTimeBusinessHoursSecondsinteger | nullBot handoff → ticket resolution (includes a 30-minute wind-down grace). Falls back to conversationResolvedAt when there is no ticket.
agentResolutionTimeBusinessHoursSecondsinteger | nullFirst agent assignment → ticket resolution (includes a 30-minute wind-down grace). Falls back to conversationResolvedAt when there is no ticket.
Chat session categoryClassifies 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.
chatTypestring | nullOne of within-bhrs, spillover, backlog, out-of-bhrs, aged.
isBauboolean | nulltrue for within-bhrs, backlog, out-of-bhrs.
includeInNormalizedMetricsboolean | nulltrue unless chatType is aged.
includeInLaBenchmarkboolean | nulltrue only when chatType is within-bhrs.
CSAT
ratinginteger | nullSurvey star rating, if the customer responded.
resolutionYesNostringYes 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.
feedbackstringFree-text feedback, if any.
submittedAtstring (date-time) | nullWhen the survey was submitted.
Custom fields
customFieldsobject ({ [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​

NameDescriptionRequiredSchema
conversationIdThe conversation id (the same value returned as conversationId in export rows).Yesstring

Query parameters​

NameDescriptionRequiredSchema
timezoneIANA timezone for computing business-hours metrics. Defaults to Asia/Singapore.Nostring
organizationIdOptional. When provided, must equal the organization you are authenticated against (403 otherwise). The request is always scoped to your authenticated organization regardless.Nostring

Header parameters​

Same as the list endpoint (authorization, organization-id, auth-type).

Responses​

CodeDescriptionContent type
200Successful responseapplication/json
401Unauthorizedapplication/json
404Conversation not found in the organizationapplication/json
429Rate limit exceededapplication/json

200 Successful response​

FieldTypeDescription
itemsarray of ConversationSessionEvery 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 — conversationResolvedAt is 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" }