Company messaging

Create a conversation

Create a conversation on behalf of a company admin. The admin whose email you pass in user.email becomes the creator and is always added as a participant.

It requires a Bearer token for a company admin (for example a company API token) whose role includes the messaging update permission. If user.email does not match an admin of the company, the request returns 403.

Set conversation.type to choose what to create:

ChannelConversation: a named channel. recipients is ignored. Members are the acting admin 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.

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 the acting admin 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. To find a company member by email or phone instead, pass email or phone with receivable_type: UserCompany. Any other recipient given by email or phone becomes one of the acting admin’s contacts, found or created; this applies only to direct, group, SMS, and email conversations.

A conversation that fails validation, such as a channel without a name, is not saved. The response is still a 200, with id set to null.

POST

api

company

messaging

conversations

curl --request POST \
  --url https://api.fluid.app/api/company/messaging/conversations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "user": {
    "email": "dana.whitfield@acmewellness.com"
  },
  "conversation": {
    "type": "DirectConversation"
  },
  "recipients": [
    {
      "email": "priya.shah@acmewellness.com",
      "receivable_type": "UserCompany"
    }
  ]
}
'

{
  "id": 90418,
  "type": "DirectConversation",
  "kind": "direct",
  "name": "Priya Shah",
  "description": null,
  "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-30T16:05:22Z",
  "pinned_messages_count": 0,
  "total_recipients": 2,
  "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": "Dana",
      "last_name": "Whitfield",
      "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
    }
  ],
  "creator": {
    "id": 48102,
    "first_name": "Dana",
    "last_name": "Whitfield",
    "avatar_background": "#4F46E5",
    "image_url": null,
    "pro_user": true,
    "blocked": false,
    "blocker": false,
    "discarded_at": null
  }
}

{}

{
  "message": "Invalid credentials."
}

{
  "error": "You do not have sufficient privileges to perform this action."
}

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

Authorizations

Authorization

string

header

required

Bearer token authentication

Body

application/json

user

object

required

The company admin to act as.

Show child attributes

conversation

object

required

The conversation to create.

Show child attributes

recipients

object[]

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

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/company/messaging/conversations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "user": {
    "email": "dana.whitfield@acmewellness.com"
  },
  "conversation": {
    "type": "DirectConversation"
  },
  "recipients": [
    {
      "email": "priya.shah@acmewellness.com",
      "receivable_type": "UserCompany"
    }
  ]
}
'

{
  "id": 90418,
  "type": "DirectConversation",
  "kind": "direct",
  "name": "Priya Shah",
  "description": null,
  "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-30T16:05:22Z",
  "pinned_messages_count": 0,
  "total_recipients": 2,
  "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": "Dana",
      "last_name": "Whitfield",
      "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
    }
  ],
  "creator": {
    "id": 48102,
    "first_name": "Dana",
    "last_name": "Whitfield",
    "avatar_background": "#4F46E5",
    "image_url": null,
    "pro_user": true,
    "blocked": false,
    "blocker": false,
    "discarded_at": null
  }
}

{}

{
  "message": "Invalid credentials."
}

{
  "error": "You do not have sufficient privileges to perform this action."
}

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

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