Messages (v6)

Get messages by IDs

Returns a list of messages (MessageV6) by IDs, in request order. With conversation_id the user must have access to that conversation and only its messages are returned. Without it the ids may span conversations and voice memos; each message is checked on its own and any the user cannot access, or that do not exist, are silently left out. MessageV6 differs from v5 in three ways: thread_id (the parent id, or the message id itself when it is not a reply) replaces parent_message_id; the audio rendition and its transcript, AI summary, language flags and time codes are nested under content, with the waveform as a compact base-36 string; and the requesting user's own state (heard_ms, label_ids, notify, notes, last_heard_update) is included where the read path carries it.

post/v6/messages/by-ids

Request

  • Base URL: https://api.carbonvoice.app
  • URL: https://api.carbonvoice.app/v6/messages/by-ids
  • Auth: one of:
    • API key in header pxtoken
    • OAuth 2 (implicit, authorization URL https://api.carbonvoice.app/oauth/authorize)

Request body

conversation_idstring

Conversation (channel) ID. When set, the user must have access to this conversation and only its messages are returned. When omitted, messages may come from any conversation (or be voice memos) and each is checked on its own; messages the user cannot access, or that do not exist, are left out.

message_idsstring[] required

List of message IDs to fetch. Results keep this order; ids that are not returned are simply absent.

languagestring

Language for message content (e.g. transcript, audio). Original language used if not provided.

presigned_urlboolean

Include presigned URLs for audio files (default: false)

freshboolean

Bypass cache and fetch fresh data (default: false)

Example request

{
  "conversation_id": "507f1f77bcf86cd799439011",
  "message_ids": [
    "507f1f77bcf86cd799439012",
    "507f1f77bcf86cd799439013"
  ]
}

Response

idstring required

Message ID

type'channel' | 'prerecorded' | 'voicememo' | 'stored' | 'welcome' required

Message type

kind'audio' | 'text' | 'attachment' | 'action-item' | 'ai-prompt' | 'ai-response' | 'channel-reminder' required
namestring

User-assigned name (title) of the message. Omitted when the message has none.

created_atstring date-time required

Creation timestamp

updated_atstring date-time required

Last update timestamp

deleted_atstring date-time

Deletion timestamp

conversation_idstring

Conversation ID

workspace_idstring required

Workspace ID

creator_idstring required

Creator ID

status'offline' | 'paused' | 'processing' | 'scheduled' | 'active' | 'deleted' | 'account-deleted' | 'initializing' | 'inprogress' | 'canceled' | 'failed' required
audio_delivery'recording' | 'streaming' required
thread_idstring required

ID of the thread this message belongs to: the parent message id for a reply, or the message's own id when it is not a reply. A message is a reply exactly when thread_id !== id.

idempotency_keystring

Optional canonical idempotency key surfaced when the underlying message data carries one. Not guaranteed to be present on every message.

available_languagesstring[]

List of available languages for the message

original_languagestring

The language the message was recorded in

share_link_idstring

Share Link ID to a message

linkstring required

Link to Message

folder_idstring

Folder ID where the message is stored

conversation_sequencenumber

Sequence number of the message in the conversation

source_message_idstring

Source message ID if this is a forwarded message

users_caught_up'all' | 'some' | 'none'

Users caught up status for the message

source'email_ingestion' | 'reminder_user_id'

Where the message came from, when it was not recorded in the app

source_valuestring

Source-specific value (e.g. the ingested email address)

tagged_user_idsstring[] required

IDs of users tagged in the message

heard_msnumber

How far the requesting user has listened, in milliseconds. Only present when the message was read on behalf of a user.

label_idsstring[]

Label IDs the requesting user applied to the message. Only present when the message was read on behalf of a user.

notifyboolean

Whether the message is still in the requesting user's notifications (unheard). Only present when the message was read on behalf of a user.

notesstring

Private notes the requesting user attached to the message. Only present when the message was read on behalf of a user.

last_heard_updatestring date-time

Last time the requesting user's listen state or notes for this message changed. Only present when the message was read on behalf of a user.

Changes

No recorded changes to this operation across all 1 revision of this API.