---
title: "Start channel message"
method: POST
path: "/v3/messages/start"
tags: ["MessageControllerV3", "Messages"]
deprecated: true
---

# Start channel message

`POST /v3/messages/start`

## Request

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

> **Deprecated.**

## Request body

- StartChannelMessage
  - `transcript` string, nullable: The transcript if the client generated one, if is_text_message is true then this text will be used to generate andio using text-to-speech
  - `is_text_message` boolean, required: If true the server will generate audio based on the transcript provided
  - `unique_client_id` string, required: A unique id the client can use to identify the message, server will prevent duplicates using it
  - `release_date` string, date-time, nullable: The date the message should be released (Not yet implemented)
  - `utm_data` UtmData
    - `utm_source` string
    - `utm_medium` string
    - `utm_campaign` string
    - `utm_term` string
    - `utm_content` string
  - `is_streaming` boolean, required: If the message is being streamed than notifications are sent to listeners at the begining of the message
  - `announce_user` boolean, nullable: Only used if is_text_message is true, prepends <first name said> to transcript before text-to-speech
  - `voice` string, nullable: the voice to use when doing text to speech
  - `kind` 'audio' | 'text' | 'attachment' | 'action-item' | 'ai-prompt' | 'ai-response' | 'channel-reminder'
  - `channel_id` string, required
  - `workspace_guid` string, nullable
  - `reply_to_message_id` string, nullable
  - `createForward` StartMessageWithForward
    - `forwarded_message_id` string, required: Message ID that will be forwarded
    - `end_access_at` string, date-time, nullable: Date when the access to forwarded message ends
  - `tagged_user_ids` string[]: IDs of users to tag on this message at creation time

## Response `200`

- MessageV2
  - `message_id` string, required
  - `creator_id` string, required
  - `created_at` string, date-time, required
  - `deleted_at` string, date-time, nullable
  - `last_updated_at` string, date-time, required
  - `workspace_ids` string[], required
  - `channel_ids` string[], required
  - `parent_message_id` string, nullable
  - `heard_ms` number, nullable: The number of ms of audio listened to by the user requesting the message
  - `utm_data` UtmData
    - `utm_source` string
    - `utm_medium` string
    - `utm_campaign` string
    - `utm_term` string
    - `utm_content` string
  - `attachments` Attachment[], required
    - `_id` string, required
    - `client_id` string, nullable
    - `creator_id` string, required
    - `created_at` string, date-time, required
    - `type` 'link' | 'file' | 'location' | 'ai-response-id' | 'ai-prompt-id' | 'action-item-id' | 'ask-id', required
    - `link` string, required
    - `active_begin` string, date-time, nullable
    - `active_end` string, date-time, nullable
    - `filename` string, nullable
    - `mime_type` string, nullable
    - `length_in_bytes` number, nullable
    - `location` LatLon
      - `latitude` number, double, required
      - `longitude` number, double, required
    - `status` 'Initializing' | 'Uploading' | 'Uploaded' | 'Failed'
    - `percent_complete` number, nullable
  - `notes` string, required
  - `notify` boolean, required: Has the logged in user cleared the notification for this message
  - `last_heard_update` string, date-time, required: Last time we listened/updated notify bit
  - `reaction_summary` ReactionSummary, required
    - `reaction_counts` object, required
    - `top_user_reactions` UserReaction[], required
      - `user_id` string, required
      - `reaction_id` string, required
    - `top_user_emojis` TopUserEmoji[]: Optional: summaries persisted before this field existed lack it — clients must tolerate absence.
      - `reaction` string, required: Canonical unicode emoji (e.g. ❤️, 🎉)
      - `count` number, required: Authoritative total number of distinct users with this reaction (never capped)
      - `user_ids` string[], required: A capped preview of users who reacted with this emoji — a sample, not the full list
  - `name` string, nullable
  - `is_text_message` boolean, required
  - `status` 'offline' | 'paused' | 'processing' | 'scheduled' | 'active' | 'deleted' | 'account-deleted' | 'initializing' | 'inprogress' | 'canceled' | 'failed', required
  - `label_ids` string[], required
  - `audio_models` AudioModelV2[], required
    - `_id` string, required
    - `url` string, required
    - `extension` string, nullable, required
    - `streaming` boolean, required
    - `language` string, required
    - `duration_ms` number, required
    - `waveform_percentages` number[], required
    - `is_original_audio` boolean, required
  - `text_models` TextModel[], required
    - `type` 'transcript' | 'transcript_with_timecode' | 'summary' | 'topic' | 'bullet_list', required
    - `audio_id` string, nullable, required
    - `language_id` string, required
    - `value` string, required
    - `timecodes` TimedText[], required
      - `t` string, required: The text
      - `s` number, required: The start time in ms
      - `e` number, required: The end time in ms
  - `source_message_id` string, nullable, required
  - `cache_key` string, required
  - `audio_delivery` 'recording' | 'streaming', required
  - `users_not_allowed_to_receive_notifications` UsersNotAllowedReceiveNotifications[]
    - `user_id` string, required
    - `phone` string, required
  - `users_not_allowed_to_receive_notifications_v2` UsersNotAllowedReceiveNotificationsV2[]
    - `user_id` string, required
    - `phone` string, nullable
    - `email` string, nullable
  - `duration_ms` number, required: The length of the message in milliseconds
  - `total_heard_ms` number, required: The number of ms of audio listened to by all users
  - `notified_users` number, required: Then number of users who have a notification for this message and have not listened to the audio.
  - `users_caught_up` 'all' | 'some' | 'none', required: The number of users that listened to the audio or removed the notification
  - `forward_id` string, nullable: The ID of a forwarded message (Deprecated, for new implementations we should start using share_link_id
  - `share_link_id` string, nullable: The ID of a Share Link to a message
  - `stream_key` string, nullable: The stream key used to add audio to the message
  - `socket_disconnects_while_streaming` number, required: The number of times the socket disconnected while the creator was sending audio
  - `type` 'channel' | 'prerecorded' | 'voicememo' | 'stored' | 'welcome', required: Message type
  - `channel_sequence` number, required: The sequencial id of the message within the channel
  - `last_heard_at` string, date-time, required: The last time anyone listened or cleared notified on this message
  - `folder_id` string, nullable: Folder ID, only present when the message type is one of: voicememo,prerecorded
  - `tagged_user_ids` string[], required: IDs of users tagged in the message

---

[API](https://skmtc.dev/carbonvoice/apis/carbon-voice-api.md) · [All operations](https://skmtc.dev/carbonvoice/apis/carbon-voice-api/llms.txt) · [OpenAPI document](https://skmtc.dev/carbonvoice/apis/carbon-voice-api/revisions/b91c5c845122?raw)