Channels

Create a conversation

Create a conversation as yourself: a signed-in company admin or rep whose role includes the messaging update permission. You are always added as a participant.

Set conversation.type to choose what to create:

ChannelConversation: a named channel. Only company admins can create one; a rep gets a 400. recipients is ignored. Members are you plus everyone matching conversation.filter.
DirectConversation: a one-to-one conversation with a company member or a contact.
GroupConversation: a named conversation with several participants.
SmsConversation and EmailConversation: a conversation with contacts over SMS or email.
BotConversation: a conversation with a bot.

For every type except a channel, if a conversation of that type already exists with exactly the same participants, it is returned instead of a new one. A conversation stays initiated until its first message. Any initiated conversation you created with the same name is deleted first.

Identify each participant in recipients by uid, the recipient ID of an existing company member or contact. A recipient given only by email or phone becomes one of your contacts, found or created; this applies only to direct, group, SMS, and email conversations.

To start several conversations and send each one the same first message, send conversations and message instead of conversation and recipients. The response is then a 201 with the conversations that were created.

POST

api

messaging

conversations

curl --request POST \
  --url https://api.fluid.app/api/v1/messaging/conversations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "conversation": {
    "type": "GroupConversation",
    "name": "Spring launch team",
    "description": "Planning the April product launch"
  },
  "recipients": [
    {
      "uid": 48211
    },
    {
      "uid": 48307
    }
  ]
}
'

{
  "id": 90412,
  "type": "GroupConversation",
  "kind": "group",
  "name": "Spring launch team",
  "description": "Planning the April product launch",
  "status": "initiated",
  "conversation_type": "internal",
  "broadcasting": null,
  "auto_add_recipients": null,
  "announcing": false,
  "avatar_background_color": null,
  "avatar_emoji": null,
  "avatar_url": null,
  "image_url": null,
  "created_at": "2026-09-30T15:42:07Z",
  "pinned_messages_count": 0,
  "total_recipients": 3,
  "unread": false,
  "pinned": false,
  "muted": false,
  "unread_messages_count": 0,
  "scheduled_messages_count": 0,
  "email_enabled?": false,
  "sms_enabled?": false,
  "messaging_enabled?": true,
  "draft_message": null,
  "recipients": [
    {
      "id": 48102,
      "receivable_id": 7731,
      "receivable_type": "UserCompany",
      "first_name": "Jordan",
      "last_name": "Reyes",
      "status": "active",
      "last_online": "2026-09-30T15:40:12Z",
      "avatar_background": "#4F46E5",
      "avatar_url": null,
      "image_url": null,
      "country_name": "United States",
      "pro_user": true,
      "blocked": false,
      "left_conversation_at": null,
      "discarded_at": null
    },
    {
      "id": 48211,
      "receivable_id": 7802,
      "receivable_type": "UserCompany",
      "first_name": "Priya",
      "last_name": "Shah",
      "status": "active",
      "last_online": "2026-09-29T21:03:55Z",
      "avatar_background": "#0EA5E9",
      "avatar_url": null,
      "image_url": null,
      "country_name": "United States",
      "pro_user": false,
      "blocked": false,
      "left_conversation_at": null,
      "discarded_at": null
    },
    {
      "id": 48307,
      "receivable_id": 7859,
      "receivable_type": "UserCompany",
      "first_name": "Marcus",
      "last_name": "Bell",
      "status": "active",
      "last_online": "2026-09-30T09:17:31Z",
      "avatar_background": "#F59E0B",
      "avatar_url": null,
      "image_url": null,
      "country_name": "Canada",
      "pro_user": false,
      "blocked": false,
      "left_conversation_at": null,
      "discarded_at": null
    }
  ],
  "creator": {
    "id": 48102,
    "first_name": "Jordan",
    "last_name": "Reyes",
    "avatar_background": "#4F46E5",
    "image_url": null,
    "pro_user": true,
    "blocked": false,
    "blocker": false,
    "discarded_at": null
  }
}

[
  {
    "id": 90415,
    "type": "DirectConversation",
    "kind": "direct",
    "name": "Maria Lopez",
    "description": null,
    "status": "open",
    "conversation_type": "external",
    "broadcasting": null,
    "auto_add_recipients": null,
    "announcing": false,
    "avatar_background_color": null,
    "avatar_emoji": null,
    "avatar_url": null,
    "image_url": null,
    "created_at": "2026-09-30T15:44:51Z",
    "pinned_messages_count": 0,
    "total_recipients": 2,
    "unread": false,
    "pinned": false,
    "muted": false,
    "unread_messages_count": 0,
    "scheduled_messages_count": 0,
    "email_enabled?": true,
    "sms_enabled?": false,
    "messaging_enabled?": true,
    "draft_message": null,
    "recipients": [
      {
        "id": 48102,
        "receivable_id": 7731,
        "receivable_type": "UserCompany",
        "first_name": "Jordan",
        "last_name": "Reyes",
        "status": "active",
        "last_online": "2026-09-30T15:40:12Z",
        "avatar_background": "#4F46E5",
        "avatar_url": null,
        "image_url": null,
        "country_name": "United States",
        "pro_user": true,
        "blocked": false,
        "left_conversation_at": null,
        "discarded_at": null
      },
      {
        "id": 51944,
        "receivable_id": 20318,
        "receivable_type": "Contact",
        "first_name": "Maria",
        "last_name": "Lopez",
        "email": "maria.lopez@gmail.com",
        "phone": null,
        "avatar_background": "#10B981",
        "avatar_url": null,
        "image_url": null,
        "country_name": null,
        "pro_user": false,
        "blocked": false,
        "left_conversation_at": null,
        "discarded_at": null
      }
    ],
    "creator": {
      "id": 48102,
      "first_name": "Jordan",
      "last_name": "Reyes",
      "avatar_background": "#4F46E5",
      "image_url": null,
      "pro_user": true,
      "blocked": false,
      "blocker": false,
      "discarded_at": null
    }
  }
]

{
  "creator": [
    "Channel can only be created by Admins"
  ]
}

{
  "message": "Invalid credentials."
}

{
  "message": "Not authorized."
}

{
  "error_message": "Invalid parameters",
  "errors": {
    "conversation": {
      "broadcasting": [
        "must be boolean"
      ]
    }
  },
  "meta": {
    "request_id": "3f6c2a9e-8b1d-4f7a-9c35-2e8d41b07a6f",
    "timestamp": "2026-09-30T15:42:07Z"
  }
}

Authorizations

Authorization

string

header

required

Bearer token authentication

Body

application/json

Send conversation (with recipients) to create one conversation, or conversations (with an optional message) to create several.

conversation

object

The conversation to create.

Show child attributes

recipients

object[]

The participants to add besides you. Required for every type except a channel, where it is ignored; send an empty array for a channel.

Show child attributes

conversations

object[]

Batch mode. Each entry creates one conversation.

Show child attributes

message

object

Batch mode only. A message sent from you to each conversation created from conversations. Ignored with conversation.

Show child attributes

Response

The conversation was created, or an existing conversation with the same participants was found.

A conversation as seen by the acting recipient. Per-recipient fields such as unread, pinned, and muted describe that recipient's view of the conversation. recipients lists at most six active participants; total_recipients is the full count.

integer | null

required

type

string

required

The conversation type, for example GroupConversation.

kind

string | null

required

The short conversation kind (direct, group, channel, or downline), or null for SMS, email, and bot conversations.

name

string | null

required

description

string | null

required

status

string | null

required

One of initiated, open, archived, or closed. A new conversation stays initiated until its first message.

conversation_type

string | null

required

internal for conversations between company members, external for conversations with contacts.

broadcasting

boolean | null

required

auto_add_recipients

boolean | null

required

announcing

boolean | null

required

avatar_background_color

string | null

required

avatar_emoji

string | null

required

avatar_url

string | null

required

image_url

string | null

required

created_at

string<date-time> | null

required

pinned_messages_count

integer | null

required

total_recipients

integer | null

required

unread

boolean | null

required

pinned

boolean | null

required

muted

boolean | null

required

unread_messages_count

integer | null

required

scheduled_messages_count

integer | null

required

email_enabled?

boolean | null

required

sms_enabled?

boolean | null

required

messaging_enabled?

boolean | null

required

Whether the acting recipient can post in the conversation.

draft_message

object | null

required

The acting recipient's unsent draft in this conversation, or null.

recipients

object[]

required

Show child attributes

creator

object | null

required

The recipient who created a conversation.

Show child attributes

audience

enum<string>

Who a channel is for; admins seats only the company's admins, now and as admins come and go.

Available options:

members,

admins

ticket

object | null

For a Cowork ticket's or board card's channel, what it discusses; null otherwise. A board card has only id, title and status; a Cowork ticket also has the rest, which names people by name and avatar only.

Show child attributes

host_company_name

string | null

For a guest from another company, the name of the company hosting the conversation; null for the host's own people.

purpose

string | null

What Fluid made the conversation for: support for the company's Fluid Support channel, ticket for a Cowork ticket's channel, or null for one people created.

uuid_v7

string<uuid>

The stable UUIDv7 identifier. Messaging routes accept it wherever they accept the numeric id.

unread_mentions_count

integer | null

Unread messages that need you — every unread message in a direct or group conversation, only mentions in a channel. Shown as the numbered badge.

can_delete_any_message

boolean

Whether you may delete other people's messages here. True for the company's own admins in a channel; false in direct and group conversations and for guests from a company the channel is shared with.

last_activity_at

string<date-time> | null

When anything last happened in the conversation.

last_opened_at

string<date-time> | null

When you last opened it (your seat's last read time); null without a seat.

last_replied_at

string<date-time> | null

When you last sent a message in it; null if you never have.

curl --request POST \
  --url https://api.fluid.app/api/v1/messaging/conversations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "conversation": {
    "type": "GroupConversation",
    "name": "Spring launch team",
    "description": "Planning the April product launch"
  },
  "recipients": [
    {
      "uid": 48211
    },
    {
      "uid": 48307
    }
  ]
}
'

{
  "id": 90412,
  "type": "GroupConversation",
  "kind": "group",
  "name": "Spring launch team",
  "description": "Planning the April product launch",
  "status": "initiated",
  "conversation_type": "internal",
  "broadcasting": null,
  "auto_add_recipients": null,
  "announcing": false,
  "avatar_background_color": null,
  "avatar_emoji": null,
  "avatar_url": null,
  "image_url": null,
  "created_at": "2026-09-30T15:42:07Z",
  "pinned_messages_count": 0,
  "total_recipients": 3,
  "unread": false,
  "pinned": false,
  "muted": false,
  "unread_messages_count": 0,
  "scheduled_messages_count": 0,
  "email_enabled?": false,
  "sms_enabled?": false,
  "messaging_enabled?": true,
  "draft_message": null,
  "recipients": [
    {
      "id": 48102,
      "receivable_id": 7731,
      "receivable_type": "UserCompany",
      "first_name": "Jordan",
      "last_name": "Reyes",
      "status": "active",
      "last_online": "2026-09-30T15:40:12Z",
      "avatar_background": "#4F46E5",
      "avatar_url": null,
      "image_url": null,
      "country_name": "United States",
      "pro_user": true,
      "blocked": false,
      "left_conversation_at": null,
      "discarded_at": null
    },
    {
      "id": 48211,
      "receivable_id": 7802,
      "receivable_type": "UserCompany",
      "first_name": "Priya",
      "last_name": "Shah",
      "status": "active",
      "last_online": "2026-09-29T21:03:55Z",
      "avatar_background": "#0EA5E9",
      "avatar_url": null,
      "image_url": null,
      "country_name": "United States",
      "pro_user": false,
      "blocked": false,
      "left_conversation_at": null,
      "discarded_at": null
    },
    {
      "id": 48307,
      "receivable_id": 7859,
      "receivable_type": "UserCompany",
      "first_name": "Marcus",
      "last_name": "Bell",
      "status": "active",
      "last_online": "2026-09-30T09:17:31Z",
      "avatar_background": "#F59E0B",
      "avatar_url": null,
      "image_url": null,
      "country_name": "Canada",
      "pro_user": false,
      "blocked": false,
      "left_conversation_at": null,
      "discarded_at": null
    }
  ],
  "creator": {
    "id": 48102,
    "first_name": "Jordan",
    "last_name": "Reyes",
    "avatar_background": "#4F46E5",
    "image_url": null,
    "pro_user": true,
    "blocked": false,
    "blocker": false,
    "discarded_at": null
  }
}

[
  {
    "id": 90415,
    "type": "DirectConversation",
    "kind": "direct",
    "name": "Maria Lopez",
    "description": null,
    "status": "open",
    "conversation_type": "external",
    "broadcasting": null,
    "auto_add_recipients": null,
    "announcing": false,
    "avatar_background_color": null,
    "avatar_emoji": null,
    "avatar_url": null,
    "image_url": null,
    "created_at": "2026-09-30T15:44:51Z",
    "pinned_messages_count": 0,
    "total_recipients": 2,
    "unread": false,
    "pinned": false,
    "muted": false,
    "unread_messages_count": 0,
    "scheduled_messages_count": 0,
    "email_enabled?": true,
    "sms_enabled?": false,
    "messaging_enabled?": true,
    "draft_message": null,
    "recipients": [
      {
        "id": 48102,
        "receivable_id": 7731,
        "receivable_type": "UserCompany",
        "first_name": "Jordan",
        "last_name": "Reyes",
        "status": "active",
        "last_online": "2026-09-30T15:40:12Z",
        "avatar_background": "#4F46E5",
        "avatar_url": null,
        "image_url": null,
        "country_name": "United States",
        "pro_user": true,
        "blocked": false,
        "left_conversation_at": null,
        "discarded_at": null
      },
      {
        "id": 51944,
        "receivable_id": 20318,
        "receivable_type": "Contact",
        "first_name": "Maria",
        "last_name": "Lopez",
        "email": "maria.lopez@gmail.com",
        "phone": null,
        "avatar_background": "#10B981",
        "avatar_url": null,
        "image_url": null,
        "country_name": null,
        "pro_user": false,
        "blocked": false,
        "left_conversation_at": null,
        "discarded_at": null
      }
    ],
    "creator": {
      "id": 48102,
      "first_name": "Jordan",
      "last_name": "Reyes",
      "avatar_background": "#4F46E5",
      "image_url": null,
      "pro_user": true,
      "blocked": false,
      "blocker": false,
      "discarded_at": null
    }
  }
]

{
  "creator": [
    "Channel can only be created by Admins"
  ]
}

{
  "message": "Invalid credentials."
}

{
  "message": "Not authorized."
}

{
  "error_message": "Invalid parameters",
  "errors": {
    "conversation": {
      "broadcasting": [
        "must be boolean"
      ]
    }
  },
  "meta": {
    "request_id": "3f6c2a9e-8b1d-4f7a-9c35-2e8d41b07a6f",
    "timestamp": "2026-09-30T15:42:07Z"
  }
}

Overview

Storefront

Commerce

Checkout

Member API

Member Sites APIs

Messaging

Cowork

People

Payments

DAM

Website

Portal

Mobile app

Content and tools

Analytics

Sales channels

Settings

FairShare SDK

Droplets

Developers

Unsorted endpoints

Portal & Widgets

Create a conversation

Authorizations

Body

Response