Overview
Conversation History lets you retrieve the full record of a single session so you can review past messages, power support workflows, or run analytics. You request history by providing the routerSessionId. This identifier is included with Router traffic, for example when routing messages or events. The API can return just messages, messages with session events, or only events - depending on your query parameters. You can also request a summary in the response metadata and, if needed, delete a session’s history. A separate, paged endpoint is also available to fetch a conversation's transcript on demand, optionally transformed through a configured pipeline (for example to translate it into a language of your choice).
When calling our APIs we require an authentication token to be present. Please refer to our authentication page for details.
Endpoints
Get session history
This API also supports retrieving session events - you can include events with messages by adding the includeEvents=true query parameter.
You can also only fetch events without messages by adding the includeMessages=false query parameter.
This endpoint also allows you to fetch conversation history including a summary by setting includeSummary=true. You can also specify the language in which the summary should be and the maximum length.
Endpoint: GET https://api.cm.com/router/conversation-history/v1/accounts/{accountId}/session-history?routerSessionId={sessionId}&includeEvents={true/false}&includeMessages={true/false}&includeSummary={true/false}&summaryLanguage={lan}&maxSummaryLength={length}
Header: X-CM-PRODUCTTOKEN: 00000000-0000-0000-0000-000000000000
Permission: ConversationalRouter.SessionHistory_Read
| Field | Type | Description |
|---|---|---|
| accountId | Guid | The ID of logical account |
| routerSessionId | Guid | Identifier of the session |
| includeEvents | boolean | When true, session events are included in the response alongside messages. Default value is false |
| includeMessages | boolean | When false, messages are omitted and only events are returned. Default value is true |
| includeSummary | boolean | When true, a summary of the conversation is included in the response metadata. Default value is false |
| summaryLanguage | string | The language the summary should be generated in. Requires includeSummary=true |
| maxSummaryLength | int | The maximum length of the summary. Default value is 20 |
📘 Setting parameters
includeEventsandincludeMessagescannot both befalse— at least one must be requested, otherwise the endpoint returns400 Bad Request. SettingsummaryLanguagewithoutincludeSummary=truealso returns400. When the session has no stored history, the endpoint returns204 No Content.
Response body
| Field | Type | Description |
|---|---|---|
| accountId | Guid | The ID of the logical account |
| sessionId | Guid | Identifier of the session. Also returned as conversationId (the same value) |
| chatId | Guid | The hashed ID of the chat the session belongs to |
| conversationHistory | array | The messages and/or events for that session, in the TwoWay conversationMessages / conversationEvents format |
| metadata | object | Metadata about the session history (see below) |
Metadata properties:
| Field | Type | Description |
|---|---|---|
| summary | string | A summary of the conversation’s text messages. Only present when includeSummary=true; if the conversation is too short to summarize, a short explanatory message is returned instead |
Get session IDs for a chat
Returns the IDs of all sessions recorded for a given chat, so you can discover which sessions exist before fetching each session’s history.
Endpoint: GET https://api.cm.com/router/conversation-history/v1/accounts/{accountId}/chats/{chatHashedId}/session-ids
Header: X-CM-PRODUCTTOKEN: 00000000-0000-0000-0000-000000000000
Permission: ConversationalRouter.SessionHistory_Read
| Field | Type | Description |
|---|---|---|
| accountId | Guid | The ID of logical account |
| chatHashedId | Guid | The hashed ID of the chat |
Response body
| Field | Type | Description |
|---|---|---|
| accountId | Guid | The ID of the logical account |
| chatId | Guid | The hashed ID of the chat |
| sessionIds | array of Guid | The session IDs recorded for this chat. Also returned as conversationIds (the same values) |
When the chat has no recorded sessions, the endpoint returns 204 No Content.
Get conversation transcription
This endpoint returns a conversation's full transcript as a chronological, paged list of messages, intended for handing a conversation over to a human agent or another system - for example when escalating a bot conversation, or archiving it. You provide the conversationId, which is the same identifier the session history endpoint returns as sessionId (also returned there as conversationId).
Optionally, each message can be run through a configured pipeline before it is returned by setting transformWithPipelineId - for example a translation pipeline, so you can fetch an on-demand transcript in a language of your choice by also setting hostLanguage. Per-message pipeline enrichment (detected language, extracted entities, sentiment, translation, redactions) is omitted by default; set includeEnrichment=true to include it.
Endpoint: GET https://api.cm.com/router/conversation-history/v2/accounts/{accountId}/conversations/{conversationId}/transcription?transformWithPipelineId={pipelineId}&hostLanguage={lan}&includeEnrichment={true/false}&cursor={cursor}
Header: X-CM-PRODUCTTOKEN: 00000000-0000-0000-0000-000000000000
Permission: ConversationalRouter.SessionHistory_Read
| Field | Type | Description |
|---|---|---|
| accountId | Guid | The ID of logical account |
| conversationId | Guid | Identifier of the conversation. The same value the session history endpoint returns as sessionId / conversationId |
| transformWithPipelineId | Guid | Optional. ID of a configured pipeline to run over each message before it is returned, for example a translation pipeline. Omit to get the plain transcript |
| hostLanguage | string | Optional. Overrides the pipeline's translation target language for this call (e.g. nl, en). Only meaningful together with transformWithPipelineId; ignored when the pipeline has no translation step |
| includeEnrichment | boolean | Optional. When true, includes per-message pipeline enrichment (detected language, extracted entities, sentiment, translation, redactions) on each message. Default value is false |
| cursor | string | Optional. Page cursor, as returned in nextCursor by a previous call. Omit to start from the beginning of the conversation |
📘 Setting parameters
The response is paged: a page's size is based on how much text it contains rather than a fixed number of messages, so page sizes vary. Repeat the request with the returned
nextCursor- keeping the same query parameters - untilnextCursorisnullto walk the whole conversation. An invalidcursorreturns400 Bad Request.If the pipeline transformation fails, the transcript is returned untransformed rather than the request failing - the response carries no error marker for this, so a failed transform cannot be detected from the response alone. Only text messages are transformed; other message types (media, carousels, etc.) pass through unchanged.
includeEnrichmentdefaults tofalsebecause enrichment can contain the original values a redaction step removed from the message text - only enable it when your integration needs that detail.
Response body
| Field | Type | Description |
|---|---|---|
| accountId | Guid | The ID of the logical account |
| conversationId | Guid | Identifier of the conversation |
| entries | array | The conversation's messages, in chronological order (see below) |
| nextCursor | string | Cursor for the next page, or null when this is the last page |
Each entry:
| Field | Type | Description |
|---|---|---|
| entryId | Guid | Identifier of the entry |
| occurredAt | datetime | When the message occurred |
| entryType | string | Always message on this endpoint |
| subType | string | Message discriminator, e.g. text |
| direction | string | clientOriginated or clientTerminated |
| flowId | Guid | The flow the message was routed through, if any |
| stateId | Guid | The state the message was routed through, if any |
| sourceApplicationId | Guid | The application the message originated from, if any |
| targetApplicationIds | array of Guid | The applications the message was routed to |
| routingDurationMs | long | How long routing the message took, in milliseconds, if applicable |
| pipelineDurationMs | long | How long the pipeline transform took, in milliseconds. Only present when transformWithPipelineId was set |
| message | object | The message content in the TwoWay rich message format. When a pipeline was applied, the transformed text is on message.text; enrichment, when includeEnrichment=true was set, is on message.pipelineEnrichment |
This endpoint returns messages only - it does not include deliveries, event, or routerAction entries.
Delete session history
If your use case requires it, you can delete a session’s stored history.
Endpoint: DELETE https://api.cm.com/router/conversation-history/v1/accounts/{accountId}/session-history/{sessionId}
Header: X-CM-PRODUCTTOKEN: 00000000-0000-0000-0000-000000000000
Permission: ConversationalRouter.SessionHistory_Delete
| Field | Type | Description |
|---|---|---|
| accountId | Guid | The ID of logical account |
| sessionId | Guid | Identifier of the session |