Messaging API

Direct messaging, group conversations, typing indicators, and read receipts for BeatPass users.

Overview

The Messaging API enables direct and group conversations between BeatPass users. It supports real-time features including typing indicators and read receipts.

Base URL: https://open.beatpass.ca/api/v1/messaging

Authentication: All messaging endpoints require a valid Bearer token.

---

Conversations

List Conversations

Retrieve the authenticated user’s conversations, ordered by most recent activity.

GET /api/v1/messaging/conversations

limit · integer

Number of conversations to return. Default: 20.

Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "type": "direct",
      "participants": [...],
      "last_message": {
        "id": 42,
        "message_text": "Hey, love your beats!",
        "created_at": "2025-01-15T14:30:00Z"
      },
      "unread_count": 2
    }
  ]
}

---

Start Conversation

Start a new direct or group conversation with an initial message.

POST /api/v1/messaging/conversations/start

Direct Message

user_id · integer

Recipient user ID for a direct message.

message_text · string · required

Initial message text. Max 2,000 characters.

Group Conversation

user_ids · array

Array of user IDs for a group conversation. At least 2 recipients required (3 participants total including the sender).

title · string

Optional group conversation title. Max 255 characters.

message_text · string · required

Initial message text. Max 2,000 characters.

Provide either user_id (direct) or user_ids (group), not both. You cannot start a conversation with yourself.

Response (201):

{
  "success": true,
  "data": {
    "conversation": {
      "id": 5,
      "type": "direct"
    },
    "message": {
      "id": 100,
      "message_text": "Hey, want to collab?",
      "created_at": "2025-01-15T14:30:00Z"
    }
  }
}

---

Delete Conversation

Remove a conversation from the authenticated user’s view. This does not delete it for other participants.

DELETE /api/v1/messaging/conversations/{conversationId}

---

Messages

Get Messages

Retrieve messages for a specific conversation. Only accessible to conversation participants.

GET /api/v1/messaging/conversations/{conversationId}/messages

conversationId · integer · required

Conversation ID.

limit · integer

Number of messages. Default: 50.

offset · integer

Offset for pagination. Default: 0.

Get Messages with Read Receipts

Same as above but includes per-message read receipt data.

GET /api/v1/messaging/conversations/{conversationId}/messages-with-receipts

---

Send Message

Send a message to an existing conversation.

POST /api/v1/messaging/messages

conversation_id · integer · required

Target conversation ID.

message_text · string · required

Message content. Max 2,000 characters.

Response (201):

{
  "success": true,
  "data": {
    "id": 101,
    "conversation_id": 5,
    "message_text": "Sounds great, let's do it!",
    "user": { "id": 1, "name": "Producer A" },
    "created_at": "2025-01-15T14:31:00Z"
  }
}

---

Read Status

Mark Conversation as Read

Mark all messages in a conversation as read for the authenticated user.

POST /api/v1/messaging/conversations/{conversationId}/read

Mark Single Message as Read

Mark an individual message as read. Used for granular read receipts.

POST /api/v1/messaging/messages/{messageId}/read

Mark Conversation as Unread

Mark a conversation as unread (useful for reminders).

POST /api/v1/messaging/conversations/{conversationId}/unread

Get Unread Count

Get the total unread message count across all conversations.

GET /api/v1/messaging/unread-count

Response:

{
  "success": true,
  "data": {
    "unread_count": 5
  }
}

---

Typing Indicators

Set Typing Status

Notify participants that the authenticated user is typing.

POST /api/v1/messaging/conversations/{conversationId}/typing

Get Typing Status

Check who is currently typing in a conversation.

GET /api/v1/messaging/conversations/{conversationId}/typing

Typing indicators are delivered in real-time. The REST endpoints provide fallback support.

---

User Discovery

Search Users

Search for users to start a conversation with.

GET /api/v1/messaging/search-users

Get Followed Users

Get the authenticated user’s followed users for quick messaging.

GET /api/v1/messaging/followed-users

---

Integration Example

// Start a conversation and send a message
async function startConversation(userId, message) {
  const response = await fetch('https://open.beatpass.ca/api/v1/messaging/conversations/start', {
    method: 'POST',
    headers: {
      'Accept': 'application/json',
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_TOKEN_HERE'
    },
    body: JSON.stringify({
      user_id: userId,
      message_text: message
    })
  });

  return response.json();
}

---

Validation Rules

Field	Rule
message_text	Required, string, max 2,000 characters
user_id	Must exist in users table
user_ids	Array, min 2 participants for groups
title	Optional, max 255 characters

---

Related Resources

Authentication

API authentication for messaging.

Error Catalog

Messaging error codes and resolutions.