GetCallSegments

Overview

Step 3 of the pipeline (call path). Queries call segments matching the phone numbers gathered in step 2. Enforces per-user call access and handler filter permissions by default.

Source scoping always applies, in one of two forms:

Default — the RestrictSources strategy is consulted and its result used as the source filter
Explicit override — fromSources()/fromSource() replaces the strategy result with a caller-supplied set

bypassRunningUserPermissions() skips only the running user's call access check and the handler filter. It does not affect source scoping — whichever form applies (strategy or explicit) still runs.

Results are paged. Use moreAvailable and forNextPage() to iterate. Use toGetTranscriptsRequest() to convert the response into a GetTranscripts request for step 4.

Request

Obtain the Request via GatherPhoneNumbersInScope.Response.toGetCallSegmentsRequest().

GetCallSegments.IHandler handler =
    GetCallSegments.construct(SharingRule.WithoutSharing);
GetCallSegments.Response callResult =
    handler.execute(
        phoneResult.toGetCallSegmentsRequest()
            .occurredAfter(cutoff)
            .take(50)
    );

Method	Description
`bypassRunningUserPermissions()`	Skips the running user's call access check and handler filter (per-user gates only). Does not affect source scoping — `RestrictSources` or `fromSources()`/`fromSource()` still applies.
`fromSources(Set<Id> sourceIds)`	Replace the `RestrictSources` strategy result with an explicit set of CallCore source record IDs.
`fromSource(Id sourceId)`	Replace the `RestrictSources` strategy result with a single CallCore source record ID.
`occurredAfter(Datetime cutoff)`	Filter to segments starting after this timestamp.
`occurredBefore(Datetime cutoff)`	Filter to segments starting before this timestamp.
`take(Integer n)`	Page size. Maximum 50, default 20.
`forNextPage(GetCallSegments.Response prev)`	Continue from the previous response's cursor.

Response

Member	Type	Description
`segments`	`List<PhoneCallSegment>`	The call segments returned for this page.
`moreAvailable`	`Boolean`	`true` if earlier pages exist (records older than the current page). Pass this response to `forNextPage()` on the next request.
`laterAvailable`	`Boolean`	`true` if later pages exist (records newer than the current page).
`toSegmentIdsWithTranscripts()`	`Set<Id>`	Segment IDs that have an associated `Available` transcript.
`toGetTranscriptsRequest()`	`GetTranscripts.Request`	Converts to a request for step 4 — fetches transcripts for all segments with `Available` status.

Each PhoneCallSegment includes the segment ID, handler info, timing, direction, and whether a recording is available. Transcripts are not included inline — use toGetTranscriptsRequest() and a separate GetTranscripts call to fetch them.

Testing

MockGetCallSegments is a package-provided test double. Call use() to install it for the current test transaction, then returning() with the segments it should return. Use withMoreAvailable(true) when testing paging behaviour.

@isTest
static void myTest() {
    PhoneCallSegment seg = new PhoneCallSegment();
    seg.segmentId           = someSegmentId;   // from test setup
    seg.inbound             = true;
    seg.startedAt           = Datetime.now().addMinutes(-10);
    seg.answered            = true;
    seg.transcriptionStatus = TranscriptionStatus.Available;

    MockGetCallSegments.use()
        .returning(new List<PhoneCallSegment>{ seg });

    MyService.run(someRecordId);
}

To simulate a paged result:

MockGetCallSegments.use()
    .returning(firstPageSegments)
    .withMoreAvailable(true);

Method	Description
`use()`	Installs this instance as the handler for the current test transaction. Returns the instance for chaining.
`returning(List<PhoneCallSegment> segments)`	Configures the segments returned by `execute()`.
`withMoreAvailable(Boolean value)`	Sets the `moreAvailable` flag on the response. Defaults to `false`.