Skip to main content

​
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/messagingAuthentication: 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

FieldRule
message_textRequired, string, max 2,000 characters
user_idMust exist in users table
user_idsArray, min 2 participants for groups
titleOptional, max 255 characters

Authentication

API authentication for messaging.

Error Catalog

Messaging error codes and resolutions.
Last modified on February 7, 2026