Skip to content
Honeycomb Docs

Messaging

Base URL: /v1

All endpoints in this section require authentication via Bearer token.

Chats

Section titled “Chats”

List Chats

Section titled “List Chats”
GET /v1/messages

Returns the authenticated user’s chats with participants and their profiles.

Query Parameters

Section titled “Query Parameters”
ParameterTypeDefaultMaxDescription
limitnumber2050Number of chats to return
cursorstring——Pagination cursor for the next page

Response 200 OK

Section titled “Response 200 OK”
{
  "chats": [
    {
      "id": "chat_abc123",
      "type": "dm",
      "name": null,
      "avatar_url": null,
      "updated_at": "2026-03-30T12:00:00Z",
      "created_at": "2026-03-28T09:15:00Z",
      "chat_participants": [
        {
          "user_id": "user_xyz",
          "profiles": {
            "id": "user_xyz",
            "username": "janedoe",
            "first_name": "Jane",
            "last_name": "Doe",
            "avatar_url": "https://cdn.example.com/avatars/jane.jpg"
          }
        }
      ]
    },
    {
      "id": "chat_def456",
      "type": "group",
      "name": "Project Alpha",
      "avatar_url": "https://cdn.example.com/groups/alpha.jpg",
      "updated_at": "2026-03-30T11:45:00Z",
      "created_at": "2026-03-20T14:00:00Z",
      "chat_participants": [
        {
          "user_id": "user_xyz",
          "profiles": {
            "id": "user_xyz",
            "username": "janedoe",
            "first_name": "Jane",
            "last_name": "Doe",
            "avatar_url": "https://cdn.example.com/avatars/jane.jpg"
          }
        },
        {
          "user_id": "user_qrs",
          "profiles": {
            "id": "user_qrs",
            "username": "bobsmith",
            "first_name": "Bob",
            "last_name": "Smith",
            "avatar_url": null
          }
        }
      ]
    }
  ]
}

Create Chat

Section titled “Create Chat”
POST /v1/messages/chat

Create a new DM or group chat. The authenticated user is automatically added as a participant.

Request Body

Section titled “Request Body”
FieldTypeRequiredDescription
participant_idsstring[]YesArray of user IDs to add. Must be non-empty.
typestringNo"dm" or "group". Auto-detected: dm if 1 participant, group if more.
namestringNoDisplay name for the group chat.

Request Example

Section titled “Request Example”
{
  "participant_ids": ["user_xyz", "user_qrs"],
  "name": "Project Alpha"
}

Response 201 Created

Section titled “Response 201 Created”
{
  "chat": {
    "id": "chat_def456",
    "type": "group",
    "name": "Project Alpha",
    "avatar_url": null,
    "created_at": "2026-03-30T12:00:00Z",
    "updated_at": "2026-03-30T12:00:00Z"
  }
}

Response (Existing DM) 200 OK

Section titled “Response (Existing DM) 200 OK”

When a DM already exists between the two users:

{
  "chat": {
    "id": "chat_abc123",
    "type": "dm",
    "name": null,
    "avatar_url": null,
    "created_at": "2026-03-28T09:15:00Z",
    "updated_at": "2026-03-30T11:00:00Z"
  },
  "existing": true
}

Get Messages

Section titled “Get Messages”
GET /v1/messages/{chatId}

Retrieve paginated messages for a chat. Messages are returned in chronological order (oldest first). Internally ordered descending by created_at, then reversed.

Path Parameters

Section titled “Path Parameters”
ParameterTypeDescription
chatIdstringThe chat ID

Query Parameters

Section titled “Query Parameters”
ParameterTypeDefaultMaxDescription
limitnumber50100Number of messages to return
cursorstring——Pagination cursor (created_at of last message)

Response 200 OK

Section titled “Response 200 OK”
{
  "messages": [
    {
      "id": "msg_001",
      "chat_id": "chat_abc123",
      "user_id": "user_xyz",
      "content": "Hey, how's the project going?",
      "created_at": "2026-03-30T11:00:00Z",
      "updated_at": "2026-03-30T11:00:00Z",
      "author": {
        "id": "user_xyz",
        "username": "janedoe",
        "first_name": "Jane",
        "last_name": "Doe",
        "avatar_url": "https://cdn.example.com/avatars/jane.jpg"
      }
    },
    {
      "id": "msg_002",
      "chat_id": "chat_abc123",
      "user_id": "user_me",
      "content": "Going well! Almost done with the API.",
      "created_at": "2026-03-30T11:02:00Z",
      "updated_at": "2026-03-30T11:02:00Z",
      "author": {
        "id": "user_me",
        "username": "currentuser",
        "first_name": "Alex",
        "last_name": "Johnson",
        "avatar_url": "https://cdn.example.com/avatars/alex.jpg"
      }
    }
  ],
  "next_cursor": "2026-03-30T11:00:00Z"
}

Send Message

Section titled “Send Message”
POST /v1/messages/{chatId}

Send a message to a chat. Also updates the chat’s updated_at timestamp.

Path Parameters

Section titled “Path Parameters”
ParameterTypeDescription
chatIdstringThe chat ID

Request Body

Section titled “Request Body”
FieldTypeRequiredDescription
contentstringYesMessage content. Must be non-empty.

Request Example

Section titled “Request Example”
{
  "content": "Hey, how's the project going?"
}

Response 201 Created

Section titled “Response 201 Created”
{
  "message": {
    "id": "msg_003",
    "chat_id": "chat_abc123",
    "user_id": "user_me",
    "content": "Hey, how's the project going?",
    "created_at": "2026-03-30T12:30:00Z",
    "updated_at": "2026-03-30T12:30:00Z",
    "author": {
      "id": "user_me",
      "username": "currentuser",
      "first_name": "Alex",
      "last_name": "Johnson",
      "avatar_url": "https://cdn.example.com/avatars/alex.jpg"
    }
  }
}

Update Chat

Section titled “Update Chat”
PATCH /v1/messages/{chatId}

Update chat metadata. Only whitelisted fields are accepted; all other fields in the request body are silently ignored.

Path Parameters

Section titled “Path Parameters”
ParameterTypeDescription
chatIdstringThe chat ID

Request Body (Whitelisted Fields)

Section titled “Request Body (Whitelisted Fields)”
FieldTypeRequiredDescription
namestringNoNew display name for chat
avatar_urlstringNoNew avatar URL for chat

Request Example

Section titled “Request Example”
{
  "name": "Project Alpha v2",
  "avatar_url": "https://cdn.example.com/groups/alpha-v2.jpg"
}

Response 200 OK

Section titled “Response 200 OK”
{
  "chat": {
    "id": "chat_def456",
    "type": "group",
    "name": "Project Alpha v2",
    "avatar_url": "https://cdn.example.com/groups/alpha-v2.jpg",
    "created_at": "2026-03-20T14:00:00Z",
    "updated_at": "2026-03-30T13:00:00Z"
  }
}

Archive Chat

Section titled “Archive Chat”
POST /v1/messages/{chatId}/archive

Archive a chat for the authenticated user. This is a per-user operation (upsert on chat_id + user_id) and does not affect other participants.

Path Parameters

Section titled “Path Parameters”
ParameterTypeDescription
chatIdstringThe chat ID

Response 200 OK

Section titled “Response 200 OK”
{
  "message": "Chat archived"
}

Invite to Chat

Section titled “Invite to Chat”
POST /v1/messages/{chatId}/invite

Add a user to an existing chat.

Path Parameters

Section titled “Path Parameters”
ParameterTypeDescription
chatIdstringThe chat ID

Request Body

Section titled “Request Body”
FieldTypeRequiredDescription
user_idstringYesUser ID to add to chat

Request Example

Section titled “Request Example”
{
  "user_id": "user_newmember"
}

Response 200 OK

Section titled “Response 200 OK”
{
  "message": "User added to chat"
}

Delete Message

Section titled “Delete Message”
DELETE /v1/messages/msg/{messageId}

Delete a message. Only the message author can delete their own messages. If the authenticated user is not the owner, the request silently succeeds without deleting.

Path Parameters

Section titled “Path Parameters”
ParameterTypeDescription
messageIdstringThe message ID

Response 200 OK

Section titled “Response 200 OK”
{
  "message": "Message deleted"
}

Notifications

Section titled “Notifications”

List Notifications

Section titled “List Notifications”
GET /v1/notifications

Returns the authenticated user’s notifications in descending order (newest first), along with the total unread count.

Query Parameters

Section titled “Query Parameters”
ParameterTypeDefaultMaxDescription
limitnumber2050Number of notifications to return
cursorstring——Pagination cursor for the next page

Response 200 OK

Section titled “Response 200 OK”
{
  "notifications": [
    {
      "id": "notif_001",
      "notifiable_id": "user_me",
      "type": "new_message",
      "title": "New message from Jane",
      "message": "Hey, how's the project going?",
      "data": {
        "chat_id": "chat_abc123",
        "sender_id": "user_xyz"
      },
      "read_at": null,
      "created_at": "2026-03-30T12:30:00Z",
      "updated_at": "2026-03-30T12:30:00Z"
    },
    {
      "id": "notif_002",
      "notifiable_id": "user_me",
      "type": "follow_request",
      "title": "New follow request",
      "message": "Bob Smith wants to follow you.",
      "data": {
        "follower_id": "user_qrs"
      },
      "read_at": "2026-03-30T10:00:00Z",
      "created_at": "2026-03-29T08:00:00Z",
      "updated_at": "2026-03-30T10:00:00Z"
    }
  ],
  "unread_count": 1,
  "next_cursor": "2026-03-29T08:00:00Z"
}

Mark Notification as Read

Section titled “Mark Notification as Read”
PATCH /v1/notifications/{id}/read

Mark a single notification as read by setting read_at to the current timestamp. Only the notification owner can mark it.

Path Parameters

Section titled “Path Parameters”
ParameterTypeDescription
idstringThe notification ID

Response 200 OK

Section titled “Response 200 OK”
{
  "message": "Marked as read"
}

Mark All Notifications as Read

Section titled “Mark All Notifications as Read”
POST /v1/notifications/read-all

Mark all of the authenticated user’s unread notifications as read.

Response 200 OK

Section titled “Response 200 OK”
{
  "message": "All marked as read"
}

Dismiss Notification

Section titled “Dismiss Notification”
DELETE /v1/notifications/{id}

Permanently delete a notification. Only the notification owner can dismiss it.

Path Parameters

Section titled “Path Parameters”
ParameterTypeDescription
idstringThe notification ID

Response 200 OK

Section titled “Response 200 OK”
{
  "message": "Notification dismissed"
}