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

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

Members

Messaging

People

Payments

DAM

Website

Portal

Content and tools

Analytics

Sales channels

Settings

FairShare SDK

Droplets

Developers

Portal & Widgets

Create a conversation

Authorizations

Body

Response