---
title: "Create a MessageShareLink"
method: POST
path: "/v6/message-sharelinks"
tags: ["Message Share Links"]
---

# Create a MessageShareLink

`POST /v6/message-sharelinks`

## Request

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

Same as the unversioned route, returning the link with the shared message in the MessageV6 shape (the same body as `GET /v6/message-sharelinks/{share_link_id}`).

## Request body

- CreateMessageShareLink
  - `shared_message_id` string, required: Message ID that will be shared/forwarded
  - `share_type` 'forward' | 'link', required: What is the ShareType of the MessageShareLink
  - `message_id` string, nullable: Message ID that will have the forward on it. Only required if share_type is forward.
  - `access_type` 'public' | 'specified' | 'forward', required: What is the access type for the MessageShareLink
  - `specified_access` SpecifiedAccess[], nullable: List of Specified Access for the MessageShareLink
    - `type` 'channel' | 'workspace' | 'workspace_group' | 'user', required: What is the Specified access type for the MessageShareLink
    - `ids` string[], required: List of IDs that have access to the MessageShareLink
  - `end_access_at` string, date-time, nullable: Date when the access to MessageShareLink ends
  - `reply_type` 'shared' | 'private_only', nullable: How replies to this share link behave. "shared" allows replies to go to a shared conversation (POST /channels/sharelink/{share_link_id}); "private_only" keeps the legacy behavior where each reply is a private DM to the sharer. Only valid when share_type is link. Omitted = private_only (legacy default).

## Response `201`

- MessageShareLinkWithMessageV6
  - `_id` string, required: Unique Identifier of share link
  - `created_by` string, required: Identifier of the User who created the share/forward
  - `channel_id` string, nullable: Channel ID where forwarded message was sent to
  - `message_id` string, nullable: Message ID that has the share_link_id attached to
  - `created_at` number, required
  - `last_updated_at` number, required
  - `end_access_at` number, nullable: Date when the access to shared message ends
  - `revoked_at` number, nullable
  - `revoked_by` string, nullable
  - `share_type` 'forward' | 'link', required: What is the ShareType of the MessageShareLink
  - `access_type` 'public' | 'specified' | 'forward', required: What is the access type for the MessageShareLink
  - `specified_access` SpecifiedAccess[]: List of Specified Access for the MessageShareLink
    - `type` 'channel' | 'workspace' | 'workspace_group' | 'user', required: What is the Specified access type for the MessageShareLink
    - `ids` string[], required: List of IDs that have access to the MessageShareLink
  - `reply_type` 'shared' | 'private_only', required: How replies to this share link behave. Legacy links without the field are private_only.
  - `reply_conversation_id` string, nullable: Conversation holding the shared replies to this link, if one was already created
  - `shared_message` MessageV6, required
    - `id` string, 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
    - `name` string: User-assigned name (title) of the message. Omitted when the message has none.
    - `created_at` string, date-time, required: Creation timestamp
    - `updated_at` string, date-time, required: Last update timestamp
    - `deleted_at` string, date-time: Deletion timestamp
    - `conversation_id` string: Conversation ID
    - `workspace_id` string, required: Workspace ID
    - `creator_id` string, required: Creator ID
    - `status` 'offline' | 'paused' | 'processing' | 'scheduled' | 'active' | 'deleted' | 'account-deleted' | 'initializing' | 'inprogress' | 'canceled' | 'failed', required
    - `audio_delivery` 'recording' | 'streaming', required
    - `thread_id` string, 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_key` string: Optional canonical idempotency key surfaced when the underlying message data carries one. Not guaranteed to be present on every message.
    - `attachments` AttachmentV6[]: List of attachments for the message
      - `presigned_url` string, nullable: Presigned URL for direct S3 access
      - `presigned_url_expiration_date` string, date-time, nullable: Expiration date for the presigned URL
      - `id` string, required: Attachment ID
      - `idempotency_key` string, nullable: Optional attachment-level idempotency key. Surfaced when the underlying attachment was created with a client-supplied `idempotency_key` (legacy `client_id`).
      - `creator_id` string, required: Creator ID
      - `created_at` string, date-time, required: Creation timestamp
      - `type` 'link' | 'file' | 'location' | 'ai-response-id' | 'ai-prompt-id' | 'action-item-id' | 'ask-id', required
      - `url` string, required: URL/Link to the attachment
      - `filename` string, nullable: Filename of the attachment
      - `mime_type` string, nullable: MIME type of the attachment
      - `length_in_bytes` number, nullable: Size of the attachment in bytes
      - `status` 'Initializing' | 'Uploading' | 'Uploaded' | 'Failed'
      - `percent_complete` number, nullable: Upload progress percentage (0-100) for the attachment. Surfaced when the underlying attachment row carries one.
      - `latitude` number, double, nullable: Latitude of a location attachment
      - `longitude` number, double, nullable: Longitude of a location attachment
    - `available_languages` string[]: List of available languages for the message
    - `original_language` string: The language the message was recorded in
    - `ai_response_ids` MessageAIResponse[]: List of AI response IDs associated with the message
      - `id` string, required: AI Response ID
      - `prompt_id` string, required: Prompt ID
    - `share_link_id` string: Share Link ID to a message
    - `link` string, required: Link to Message
    - `folder_id` string: Folder ID where the message is stored
    - `utm_data` UtmDataV5
      - `utm_source` string, nullable: UTM source parameter
      - `utm_medium` string, nullable: UTM medium parameter
      - `utm_campaign` string, nullable: UTM campaign parameter
      - `utm_content` string, nullable: UTM content parameter
      - `utm_term` string, nullable: UTM term parameter
    - `conversation_sequence` number: Sequence number of the message in the conversation
    - `source_message_id` string: Source message ID if this is a forwarded message
    - `content` MessageContentV6
      - `presigned_url` string, nullable: Presigned URL for direct S3 access
      - `presigned_url_expiration_date` string, date-time, nullable: Expiration date for the presigned URL
      - `id` string: The audio id of this rendition. Send it back as `content_id` to update it (e.g. `PUT /v6/messages/transcript`). Omitted when the message has no audio yet.
      - `ai_summary` string, nullable: AI summary of the message in this language
      - `transcript` string, nullable: Transcript of the message in this language
      - `time_codes` MessageTimeCode[]: Word-level time codes for this rendition
        - `t` string, required: Text/word for the time code
        - `s` number, required: Start time in milliseconds
        - `e` number, required: End time in milliseconds
      - `is_original_language` boolean, nullable: Whether this rendition is the language the message was recorded in
      - `language` string, nullable: Language of this rendition (transcript, AI summary, audio)
      - `url` string, nullable: URL to the audio file
      - `streaming_url` string, nullable: URL to the streaming audio file
      - `duration_ms` number, nullable: Duration of the audio in milliseconds
      - `waveform_percentage` string, nullable: Waveform amplitudes encoded as a compact string: one base-36 character per bar (`0` = silence .. `z` = full scale), at most 96 bars. Decode each character with `parseInt(ch, 36) / 35`. Omitted when the rendition has no waveform.
    - `users_caught_up` 'all' | 'some' | 'none': Users caught up status for the message
    - `reaction_summary` ReactionSummaryV6
      - `reaction_counts` object, required: Reaction counts by reaction ID
      - `top_user_reactions` UserReactionV5[], required: Top user reactions
        - `user_id` string, required: User ID
        - `reaction_id` string, required: Reaction ID
      - `top_user_emojis` TopUserEmojiV6[]: Every reaction (curated as its canonical emoji, plus arbitrary emoji), grouped per emoji. Authoritative when present, even when empty; absent only on summaries persisted before the field existed, in which case fall back to `top_user_reactions`.
        - `reaction` string, required: Canonical unicode emoji (e.g. ❤️, 🎉)
        - `count` number, required: Total number of distinct users with this reaction (never capped)
        - `user_ids` string[], required: A capped preview of the users who reacted with this emoji, not the full list
    - `users_not_allowed_to_receive_notifications` UserNotAllowedReceiveNotification[]: Users not allowed to receive notifications for this message
      - `user_id` string, required: User ID
      - `phone` string, nullable: Phone number
      - `email` string, nullable: Email address
    - `source` 'email_ingestion' | 'reminder_user_id': Where the message came from, when it was not recorded in the app
    - `source_value` string: Source-specific value (e.g. the ingested email address)
    - `tagged_user_ids` string[], required: IDs of users tagged in the message
    - `heard_ms` number: How far the requesting user has listened, in milliseconds. Only present when the message was read on behalf of a user.
    - `label_ids` string[]: Label IDs the requesting user applied to the message. Only present when the message was read on behalf of a user.
    - `notify` boolean: Whether the message is still in the requesting user's notifications (unheard). Only present when the message was read on behalf of a user.
    - `notes` string: Private notes the requesting user attached to the message. Only present when the message was read on behalf of a user.
    - `last_heard_update` string, 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.
  - `has_channel_access` boolean, required

## Other responses

- `400`
- `403`

---

[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)