Need clarification on date parameter boundaries (inclusive/exclusive), "one month" range calculation, pagination stability, and SMS session/message filtering behavior for cloud recordings, call logs, and SMS sessions APIs

API and Webhooks
1

API Endpoints

  1. GET /users/{userId}/recordings - List cloud recordings
  2. GET /phone/users/{userId}/call_logs - Get user’s call logs
  3. GET /phone/sms/sessions - List SMS sessions
  4. GET /phone/sms/sessions/{sessionId} - Get SMS session details

Description

We’re implementing a data sync system that needs to fetch historical data across large date ranges. Based on form post "estrictions-on-retrieving-data-from-cloud-recordings-api, we understand recordings are limited to “one month range” within a 6-month look-back window, but several critical details remain unclear:

1. Date Parameter Boundaries (All Endpoints):

  • Are from and to parameters inclusive or exclusive on either end?
  • Example: Does from=2025-01-01&to=2025-01-31 include both Jan 1 and Jan 31, or is one boundary exclusive?
  • Why this matters: When splitting large ranges into one-month chunks to comply with API limits, we need to know whether to use:
    • from=2025-01-01&to=2025-01-31 then from=2025-01-31&to=2025-02-28 (1-day overlap if both inclusive)
    • from=2025-01-01&to=2025-01-31 then from=2025-02-01&to=2025-02-28 (no overlap if both inclusive)

2. “One Month” Range Calculation:

  • The recordings documentation and SMS sessions documentation both state “one month” limits
  • Does “one month” mean:
    • A fixed 30 or 31 days maximum?
    • “Same date, previous month” (e.g., April 7 to May 7, which varies: 28-31 days)?
    • Exactly one calendar month (e.g., Jan 1 to Jan 31)?
  • Questions about boundary cases:
    • from=2025-01-31&to=2025-02-28 = 28 days spanning 2 months (valid?)
    • from=2025-01-31&to=2025-03-03 = 31 days but spans 3 calendar months (valid?)
    • from=2024-01-31&to=2024-02-29 = 29 days in leap year (valid?)
    • from=2024-02-29&to=2024-03-29 = 29 days starting from leap day (valid?)
  • Should we use fixed 28-day chunks to be safe, or calculate based on actual month lengths?

3. “One Month” Limit for Call Logs:

  • Recordings and SMS sessions have clear one-month limits
  • Does the call logs endpoint (/phone/users/{userId}/call_logs) have the same one-month chunking requirement?
  • Or can we use the full 6-month range in a single request?

4. Pagination Stability (All Endpoints):

  • What is the default sort order for results?
  • If new data is added during pagination (new recordings/calls/SMS between page requests), can items shift between pages?
  • Does next_page_token guarantee stable/consistent results, or should we implement client-side deduplication?
  • Why this matters: Without stable ordering, the same item could appear twice or be missed entirely when paginating through large result sets

5. SMS Two-Level Filtering Behavior:

  • We notice that BOTH /phone/sms/sessions and /phone/sms/sessions/{sessionId} accept from/to parameters
  • This suggests a two-level filtering approach:
    1. Filter sessions by activity using filter_type parameter (which specifies: sent_message_time, received_message_time, last_message_time, or sent_received_message_time)
    2. Filter messages within each session using from/to on the session details endpoint
  • Critical Questions:
    • For session details endpoint: The from/to parameters don’t have an accompanying filter_type parameter - which message timestamp field do they filter on?
      • Is it sent_time, received_time, date_time, created_at, or something else?
      • Does it filter on sent messages only, received messages only, or both?
    • Why are two levels of date filtering needed? Does this mean sessions span longer than one month?
    • Scenario 1: Session with continuous activity Jan 1 through Mar 1
      • Query: from=2025-02-01&to=2025-02-28&filter_type=sent_received_message_time
      • Will this session be included?
    • Scenario 2: Session with messages in Jan (1st-31st) and late Mar (16th-30th), but NO messages in Feb or early Mar (1st-15th)
      • Query: from=2025-02-01&to=2025-03-15&filter_type=sent_received_message_time
      • Will this session be included? (The date range spans a gap in activity)
      • If included, what happens when we query session details with the same date range - do we get an empty message list?
    • When we query session details with from=2025-02-01&to=2025-02-28, do we get only messages from that range, or all messages in the session?
    • For incremental sync: Should we query sessions with a wide date range (e.g., last 6 months) and rely on message-level filtering in step 2?
    • Or should we use the same date range for both session filtering and message filtering?

6. SMS Session Definition and Lifecycle:

  • What exactly is an “SMS session”?
  • Does a session represent:
    • A conversation thread (potentially long-lived, spanning months)?
    • A time-based window (e.g., all messages in a 24-hour period)?
    • Something else?
  • Can new messages be added to an existing session over time?
  • What determines when a session ends and a new one begins?
  • If sessions have a creation_time field, what does it represent? The time of the first message, or when Zoom created the session record?
  • For incremental sync: If sessions are long-lived conversation threads, we need to:
    1. Find all sessions that had activity since last sync (using filter_type=sent_received_message_time)
    2. For each session, fetch only messages since last sync (using from/to on session details)
    • Is this the intended workflow?

7. SMS Sessions from Parameter Bug Status:
Forum post “broken-from-date-filter-for-phone-sms-sessions-endpoint” reported that the from parameter was being ignored on /phone/sms/sessions

  • Has this been resolved?
  • Does it affect both the session list endpoint and the session details endpoint?

How To Reproduce

# Example 1: Date boundary ambiguity
# If both parameters are inclusive and we split a 60-day range:
GET https://api.zoom.us/v2/users/me/recordings?from=2025-01-01&to=2025-01-31
GET https://api.zoom.us/v2/users/me/recordings?from=2025-01-31&to=2025-03-02
# Result: Jan 31 recordings appear in BOTH responses (duplicate)

# If one is exclusive:
GET https://api.zoom.us/v2/users/me/recordings?from=2025-01-01&to=2025-01-31
GET https://api.zoom.us/v2/users/me/recordings?from=2025-02-01&to=2025-03-02
# Result: Jan 31 recordings might be missed entirely (gap)

# Example 2: "One month" boundary cases
GET https://api.zoom.us/v2/users/me/recordings?from=2025-01-31&to=2025-02-28
# 28 days, spans 2 calendar months - valid?

GET https://api.zoom.us/v2/users/me/recordings?from=2025-01-31&to=2025-03-03
# 31 days, spans 3 calendar months - valid?

GET https://api.zoom.us/v2/users/me/recordings?from=2024-02-29&to=2024-03-29
# 29 days starting from leap day - valid?

# Example 3: SMS session filtering with activity gaps
# Scenario: Session spanning Jan 1 - Mar 30 with messages:
#   - Jan 5, Jan 10, Jan 20 (active in January)
#   - [NO activity Feb 1 - Mar 15]
#   - Mar 16, Mar 20, Mar 25 (active in late March)

# Question 1: Query covering the gap period
GET https://api.zoom.us/v2/phone/sms/sessions?from=2025-02-01&to=2025-03-15&filter_type=sent_received_message_time
# Does this return the session? (Date range has NO message activity, but session exists)

# Question 2: If session IS returned, what do we get for messages?
GET https://api.zoom.us/v2/phone/sms/sessions/{sessionId}?from=2025-02-01&to=2025-03-15
# Empty list? Or does it ignore the from/to and return all messages (Jan + Mar)?

# Example 4: SMS two-level filtering - which timestamp field is used?
# Scenario: Session with messages:
#   - Message A: sent Jan 5, received Jan 5
#   - Message B: sent Feb 10, received Feb 10
#   - Message C: sent Mar 15, received Mar 15

# Step 1: Get sessions with Feb activity
GET https://api.zoom.us/v2/phone/sms/sessions?from=2025-02-01&to=2025-02-28&filter_type=sent_received_message_time
# Question: Does this return the session (it has a Feb 10 message)?

# Step 2: Get messages from that session
GET https://api.zoom.us/v2/phone/sms/sessions/{sessionId}?from=2025-02-01&to=2025-02-28
# Questions:
# - Which timestamp field is being filtered (sent_time, received_time, date_time, created_at)?
# - Does this return only Message B (Feb 10)?
# - Or all messages (A, B, C) because there's no filter_type to specify sent vs received?
# - Or does it default to filtering on both sent AND received timestamps (like sent_received_message_time)?

# Example 5: Incremental sync workflow
# Last sync was Jan 15, now it's Feb 20

# Option A: Use narrow date range for both levels
GET https://api.zoom.us/v2/phone/sms/sessions?from=2025-01-15&to=2025-02-20&filter_type=sent_received_message_time
# Then for each session:
GET https://api.zoom.us/v2/phone/sms/sessions/{sessionId}?from=2025-01-15&to=2025-02-20

# Option B: Use wide range for sessions, narrow for messages
GET https://api.zoom.us/v2/phone/sms/sessions?from=2024-08-01&to=2025-02-20&filter_type=sent_received_message_time
# Then for each session:
GET https://api.zoom.us/v2/phone/sms/sessions/{sessionId}?from=2025-01-15&to=2025-02-20

# Which approach is correct/more efficient?

Authentication: Server-to-Server OAuth

Any clarification on these points would help us implement reliable data synchronization without gaps or duplicates.

Thank you!