Skip to main content
GET
List conversation messages
Back to the Analytics APIs overview Returns the messages exchanged in a project’s conversations chronologically. Message content is filtered according to the project’s PII policy before it is returned, so sensitive values may be masked or removed. Messages are ordered by time, then by message ID to keep the order stable. Give either a date range (fromDate and toDate together), a list of sessionIds, or the call IDs of voice calls (externalCallIds or callSids). A date-range query with no other filter that would span more than 10,000 sessions is rejected with 400. Narrow the range or add sessionIds for busy projects. Always use a filter and paginate as needed. For pagination, prefer cursor: pass the nextCursor value from the previous response. offset also works, and skip is an older name for offset that is still accepted. Use only one of the three in a single request. Use limit (1 to 10,000, default 100) to set the page size. A page can hold fewer messages than limit so the response stays within 1 MiB. Check hasMore instead of assuming that a short page is the last one. Use direction to sort by time: asc (default) for oldest first, or desc for newest first. Authenticate with the x-api-key header. The key must be bound to the project you are querying and have analytics:read permission.

Filters

Different filters combine with AND. Multiple values in the same filter combine with OR.
  • fromDate and toDate: Inclusive start and exclusive end timestamps. Send them together unless you send sessionIds, externalCallIds, or callSids. When you send both, the date range still applies.
  • sessionIds: Filter by specific session IDs; up to 10,000.
  • externalCallIds: Filter voice calls by the upstream call ID that the contact center or carrier sent in the SIP INVITE, such as a Genesys conversation ID. Pass 1 to 100 values. Matching ignores case. Only calls made after this filter shipped carry the ID. Use callSids for older calls.
  • callSids: Filter voice calls by KoreVG call SID. Pass 1 to 100 values. Matching is exact. It also finds calls recorded before this filter shipped.
  • channelUId: Filter by the end-user identifier that the channel supplied, such as an email address, phone number, or provider ID. Pass up to 100 values. Values are normalized before matching, and phone numbers need a country code. Sessions created before this filter shipped can’t be found with it. Use the POST endpoint for identifier lookups so they stay out of URLs and logs.
  • callerNumber: Filter by caller number (ANI) or provider caller ID. Pass up to 100 values.
  • channel: Filter by the channel the conversation took place on. Pass up to 100 values.
  • environment: Filter by environment: dev, staging, production, or working-copy. Pass up to 100 values.
  • traceDimensions[key]: Filter by a custom session dimension, for example traceDimensions[tier]=gold. Repeat with different keys to require all of them.

Authorizations

x-api-key
string
header
required

Project-bound API key. Do not send an Authorization header.

Path Parameters

projectId
string
required
Minimum string length: 1

Query Parameters

fromDate
string<date-time>

Inclusive ISO 8601 timestamp. Required with toDate unless sessionIds, externalCallIds or callSids is supplied. When sent with call IDs, the range still applies (AND).

toDate
string<date-time>

Exclusive ISO 8601 timestamp. Required with fromDate unless sessionIds, externalCallIds or callSids is supplied.

sessionIds
string[]

Filter to specific sessions. Pass up to 10,000 session IDs, comma-separated or by repeating the parameter. Can be used instead of a date range.

Maximum array length: 10000
Minimum string length: 1
externalCallIds
string[]

Filter to the voice calls with these upstream call IDs — the ID the contact center or carrier put in the SIP INVITE (for example a Genesys conversation ID, a Five9 call ID or a Cisco GUID). The ID is taken from the first header present in this order: X-ExternalCallId, X-ConversationId, Cisco-Guid, X-Inin-Cnv, X-Five9SessionId, X-Twilio-CallSid, X-MasterContactId, X-InContact-ContactId, X-Avaya-UCID, P-Genesys-ConnId, X-Genesys-CallUUID, X-User-To-User, User-to-User (the part before the first ;), X-CID.

Pass 1 to 100 values, comma-separated or by repeating the parameter. Each value is 1 to 256 characters after trimming. Matching ignores case. Can be used instead of a date range, and is ANDed with every other filter, including callSids. An empty value, an empty entry, a value over 256 characters or more than 100 values returns 400 INVALID_EXTERNAL_CALL_IDS; the values are never returned. Works when the project's exposure config disables the identity field group. Only calls made after this filter shipped carry the external call ID; find older calls with callSids.

Required array length: 1 - 100 elements
Required string length: 1 - 256
callSids
string[]

Filter to the voice calls with these KoreVG call SIDs. Pass 1 to 100 values, comma-separated or by repeating the parameter. Each value is 1 to 256 characters after trimming and is matched exactly. Can be used instead of a date range, and is ANDed with every other filter. Invalid input returns 400 INVALID_CALL_SIDS; the values are never returned. Works when the project's exposure config disables the identity field group, and also finds calls recorded before this filter shipped.

Required array length: 1 - 100 elements
Required string length: 1 - 256
channelUId
string[]

Filter to the messages of specific end users by their channel user identifier (channelUId): the email address, phone number, SIP address or provider id the channel supplied for them, or the externalUserId an integrator passed when the session started. Values are normalized before matching, so Priya@Example.com and priya@example.com match, and +1 (415) 555-0100, 14155550100 and tel:+14155550100 match the same phone number. Phone numbers must include the country code; a national number without one matches only as a provider id. Matching is exact on the whole identifier (no partial or prefix match). A match is evidence, not proof of identity: numbers and emails get reassigned. Pass up to 100 values, comma-separated or by repeating the parameter. Prefer the POST operation for identifier lookups: GET query strings can be recorded by proxies and access logs.

Changed in this release: channelUId no longer matches the internal contact, customer or anonymous identifiers recorded on the session. Sessions created before this feature have no channelUId and cannot be found by it; use sessionIds or a date range for them. An empty or invalid value returns 400 INVALID_CHANNEL_UID. Returns every message of each matching session. The former channelUIds alias is no longer accepted (400 INVALID_QUERY_PARAMETER).

Maximum array length: 100
Minimum string length: 1
callerNumber
string[]

Filter to sessions from specific callers (ANI or provider caller id). Pass up to 100 values, comma-separated (spaces after commas are allowed) or by repeating the parameter; the filter is ANDed with every other filter. The 100-value limit counts entries before duplicates are merged; more returns 400 TOO_MANY_FILTER_VALUES. A value that itself contains a comma cannot be queried, because commas always separate values.

Paste the value in any format the provider, a transcript, a CDR or a spreadsheet shows. Each value is turned into the same match key the platform stored at call time: invisible characters, fullwidth digits and Unicode dashes are cleaned up, a national trunk (0) after the country code is removed (+44 (0)20 7946 0958 matches +442079460958), and phone-like values (including sip: and tel: URIs, spaces, dashes, dots, slashes and parentheses) become E.164. 7 to 15 bare digits are treated as an international number (919876543210 matches +919876543210). Digits written in a national format keep their digits (098765 43210 matches 09876543210). Other values, such as softphone usernames, SDK ids or Anonymous, are matched as cleaned text. Matching is exact and case-sensitive: anonymous does not match Anonymous, and +14155550100 ext 12 does not match +14155550100. Non-ASCII digits such as Arabic-Indic digits are not converted to ASCII. Keys longer than 128 characters are truncated, the same way they were when stored.

There is no country inference: a national number without its country code (9876543210) does not match a stored +919876543210, and 00 or 011 dial prefixes are not converted. Send the full international form where possible. Send + as %2B or use the POST twin; an unencoded + decodes to a space, which is also accepted and gives the same match. Anonymous matches every withheld-number call in the window.

An entry that is empty or has no letter or digit (for example callerNumber=, a trailing comma, or only +), or an entry longer than 512 characters, returns 400 INVALID_CALLER_NUMBER. The value is never returned in the response. When the project's reporting exposure config disables the identity field group, a request with this parameter returns 403 CALLER_NUMBER_LOOKUP_DISABLED.

Coverage: this endpoint compares the caller value the provider stored on the session record, as received, with the match key, the match key without +, and the cleaned value as you sent it. It covers sessions recorded before this filter shipped. Pasting the provider value exactly as stored matches, unless the stored value itself contains invisible characters, fullwidth digits, Unicode dashes or surrounding whitespace (those are cleaned from what you send, so only its E.164 or bare-digit form can match). A re-formatted copy matches here only when it shares the E.164 or bare-digit form of the stored value: for example +44 20 7946 0958 does not match a stored +44 (0)20 7946 0958, and 09876543210 does not match a stored 098765 43210, although /sessions matches both. Playground and Studio debug sessions are never matched.

Maximum array length: 100
Required string length: 1 - 512
channel
enum<string>[]

Filter by the channel the conversation took place on. Pass up to 100 values, comma-separated or by repeating the parameter.

Matched exactly as stored, with no alias handling. Unlike the sessions endpoint, web and web_chat are different values here, and shorthand such as sms or sdk_http matches nothing — use the exact channel name.

Not restricted to a fixed list, so an unrecognised value returns no results rather than an error.

Maximum array length: 100
Available options:
http_async,
slack,
line,
msteams,
whatsapp,
messenger,
instagram,
twilio_sms,
zendesk,
telegram,
genesys,
genesys_open_messaging,
ai4w,
kore_agent_assist,
email,
voice_vxml,
korevg,
audiocodes,
genesys_audio_connector,
voice_pipeline,
voice_realtime,
voice,
voice_twilio,
voice_livekit,
ag_ui,
a2a,
sdk_websocket,
web_debug,
web_chat,
api,
http
environment
enum<string>[]

Filter by environment. Pass up to 100 values, comma-separated or by repeating the parameter. Matched exactly as stored.

Not restricted to a fixed list, so an unrecognised value returns no results rather than an error, though in practice only the four values below are stored.

Maximum array length: 100
Available options:
dev,
staging,
production,
working-copy
traceDimensions[key]
string

Filter by a custom dimension recorded against the session. Replace key with the dimension name — for example traceDimensions[tier]=gold. Repeat with different keys to require all of them. Values match exactly.

cursor
string

Pass the nextCursor value from the previous response to get the next page. Do not use together with offset or skip.

Minimum string length: 1
offset
integer
default:0

Number of messages to skip before the first one returned. Do not use together with cursor or skip.

Required range: x >= 0
skip
integer

An older name for offset, kept for compatibility. Prefer offset. Do not use together with cursor or offset.

Required range: x >= 0
limit
integer
default:100

How many messages to return. A page may come back with fewer than requested so the response stays within the 1 MiB size limit — check hasMore rather than assuming a short page is the last one.

Required range: 1 <= x <= 10000
direction
enum<string>
default:asc

Sort order by time: asc for oldest first, desc for newest first.

Available options:
asc,
desc

Response

Message page returned successfully.

success
boolean
required

Always true on a successful response.

totalRecords
integer
required

Total number of messages matching your filters, across all pages.

Required range: x >= 0
hasMore
boolean
required

Whether more pages are available after this one.

offset
integer
required

The offset applied to this response.

Required range: x >= 0
limit
integer
required

The page size applied to this response.

Required range: 1 <= x <= 10000
messages
object[]
required

The messages on this page.

nextCursor
string | null
required

Opaque cursor for the next page.