---
title: "Create named conversation"
method: POST
path: "/channels/namedConversation"
tags: ["Channels"]
---

# Create named conversation

`POST /channels/namedConversation`

## Request

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

## Request body

- CreateNamedConversation
  - `workspace_guid` string, required
  - `users` RoleAssignment[], required
    - `value_type` 'userGuid' | 'phoneNumber' | 'emailAddress', required
    - `unique_value` string, required
    - `role` 'admin' | 'owner' | 'creator' | 'member' | 'guest', required
    - `required_for_active_span` boolean, nullable
  - `description` string
  - `background_color` string
  - `text_color` string
  - `image_url` string
  - `post_rule` string
  - `type` 'directMessage' | 'customerConversation' | 'namedConversation' | 'asyncMeeting', required
  - `sms_phone` string
  - `name` string, required
  - `is_private` boolean: Stop using this and start using channel visibility to control who has access
  - `visibility` 'private' | 'workspace' | 'public': Public can be viewed and joined by anyone, Private can only be view by members, Workspace means only members of the workspace can view and join
  - `default_role` 'admin' | 'owner' | 'creator' | 'member' | 'guest': The role used to add people who join the channel

## Response `201`

- PersonalizedChannel
  - `workspace_guid` string, required
  - `channel_guid` string, required
  - `channel_name` string, required
  - `channel_kind` 'standard' | 'derived', required
  - `source_channel_ids` string[], required
  - `channel_description` string, nullable
  - `bg_rrggbb` string, nullable
  - `txt_rrggbb` string, nullable
  - `channel_settings` string, required
  - `image_url` string, nullable
  - `is_private` string, required
  - `post_rule` string, nullable
  - `dm_hash` string, nullable
  - `last_updated_ts` number, required
  - `sort_order` string, date-time, required
  - `created_ts` number, required
  - `deleted_at` number, nullable
  - `owner_name` string, required
  - `sms_phone` string, nullable
  - `json_collaborators` ChannelCollaborator[], required
    - `user_guid` string, required
    - `image_url` string, required
    - `first_name` string, required
    - `last_name` string, required
    - `permission` 'admin' | 'owner' | 'creator' | 'member' | 'guest', required
    - `joined` string, date-time, nullable
    - `last_posted` string, date-time, nullable
    - `first_accessed_at` string, date-time, nullable, required
    - `last_viewed_at` string, date-time, nullable, required
    - `status` 'active' | 'user_left' | 'removed_from_channel' | 'removed_from_workspace'
    - `primary_language` string
  - `joined_ts` number, nullable
  - `is_favorite` 'N' | 'Y', required
  - `last_heard_ts` number, nullable
  - `last_posted_ts` number, nullable
  - `last_viewed_at` string, date-time, nullable
  - `workspace_name` string, required
  - `workspace_image_url` string, nullable
  - `type` 'directMessage' | 'customerConversation' | 'namedConversation' | 'asyncMeeting', required
  - `images` string[], required
  - `moreCount` number, required
  - `unread_cnt` number, required
  - `avatars` AvatarLayout
    - `avatars` AvatarGridItem[], required
      - `children` AvatarGridItem[], required
      - `type` 'row' | 'column' | 'image' | 'text', required
      - `image_url` string, nullable
      - `text` string, nullable
    - `numRows` number, required
    - `numColumns` number, required
  - `createdNew` boolean, required
  - `settings` object, required
  - `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
  - `channel_spans` PersonalizedChannelSpan[], required
    - `id` string, required
    - `begin` string, date-time, required
    - `end` string, date-time, required
    - `deleted_at` string, date-time, nullable, required
    - `required_users` string[], required
    - `type` 'Meeting' | 'RecurringMeeting', required
    - `topic` string, required
  - `visibility` 'private' | 'workspace' | 'public', required
  - `total_messages` number, required
  - `total_duration_milliseconds` number, required
  - `summaries` ConversationSummary[], required
    - `channel_id` string, required
    - `span_id` string, nullable, required
    - `items` ConversationSummaryItem[], required
      - `user_id` string, required
      - `text` string, required
      - `type` 'takeaway' | 'question' | 'answer' | 'comment' | 'note' | 'task' | 'action-item', required
  - `is_async` boolean, required
  - `async_stats` AsyncMeetingStatsApiResponse
    - `channel_stats` AsyncMeetingStats, required
      - `total_duration_milliseconds` number, required: Total duration in milliseconds
      - `total_heard_milliseconds` number, required: Total heard in milliseconds
      - `total_engaged_percentage` number, required: Total engaged percentage
      - `total_messages_posted` number, required: Total messages posted
      - `total_users` number, required: Total users
    - `user_stats` UserStats[], required
      - `user_id` string, required: User unique ID
      - `total_messages_posted` number, required: Total messages posted
      - `total_sent_milliseconds` number, required: Total sent in milliseconds
      - `total_heard_milliseconds` number, required: Total heard in milliseconds
      - `total_engaged_percentage` number, required: Total engaged percentage
      - `total_heard_messages` number, required: Total heard messages
      - `total_unheard_messages` number, required: Total unheard messages
  - `retention_days` number, nullable
  - `engagement_percentage` number
  - `max_sequence_number` number, required
  - `default_role` 'admin' | 'owner' | 'creator' | 'member' | 'guest', required
  - `sources` DerviedConversationSource[], required
    - `type` 'user_id' | 'channel_id' | 'workspace_id' | 'message_id' | 'share_link_id', required
    - `value` string, required
  - `seen_seq` number, nullable, required

---

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