> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beatpass.ca/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Info>
  **Base URL:** `https://open.beatpass.ca/api/v1/messaging`

  **Authentication:** All messaging endpoints require a valid Bearer token.
</Info>

***

## Conversations

### List Conversations

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

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/messaging/conversations
```

<ParamField query="limit" type="integer">
  Number of conversations to return. Default: `20`.
</ParamField>

**Response:**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "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.

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
POST /api/v1/messaging/conversations/start
```

#### Direct Message

<ParamField body="user_id" type="integer">
  Recipient user ID for a direct message.
</ParamField>

<ParamField body="message_text" type="string" required>
  Initial message text. Max 2,000 characters.
</ParamField>

#### Group Conversation

<ParamField body="user_ids" type="array">
  Array of user IDs for a group conversation. At least 2 recipients required (3 participants total including the sender).
</ParamField>

<ParamField body="title" type="string">
  Optional group conversation title. Max 255 characters.
</ParamField>

<ParamField body="message_text" type="string" required>
  Initial message text. Max 2,000 characters.
</ParamField>

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

**Response (201):**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "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.

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
DELETE /api/v1/messaging/conversations/{conversationId}
```

***

## Messages

### Get Messages

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

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/messaging/conversations/{conversationId}/messages
```

<ParamField path="conversationId" type="integer" required>
  Conversation ID.
</ParamField>

<ParamField query="limit" type="integer">
  Number of messages. Default: `50`.
</ParamField>

<ParamField query="offset" type="integer">
  Offset for pagination. Default: `0`.
</ParamField>

### Get Messages with Read Receipts

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

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/messaging/conversations/{conversationId}/messages-with-receipts
```

***

### Send Message

Send a message to an existing conversation.

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
POST /api/v1/messaging/messages
```

<ParamField body="conversation_id" type="integer" required>
  Target conversation ID.
</ParamField>

<ParamField body="message_text" type="string" required>
  Message content. Max 2,000 characters.
</ParamField>

**Response (201):**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "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.

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
POST /api/v1/messaging/conversations/{conversationId}/read
```

### Mark Single Message as Read

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

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
POST /api/v1/messaging/messages/{messageId}/read
```

### Mark Conversation as Unread

Mark a conversation as unread (useful for reminders).

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
POST /api/v1/messaging/conversations/{conversationId}/unread
```

### Get Unread Count

Get the total unread message count across all conversations.

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/messaging/unread-count
```

**Response:**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "success": true,
  "data": {
    "unread_count": 5
  }
}
```

***

## Typing Indicators

### Set Typing Status

Notify participants that the authenticated user is typing.

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
POST /api/v1/messaging/conversations/{conversationId}/typing
```

### Get Typing Status

Check who is currently typing in a conversation.

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/messaging/conversations/{conversationId}/typing
```

<Note>
  Typing indicators are delivered in real-time. The REST endpoints provide fallback support.
</Note>

***

## User Discovery

### Search Users

Search for users to start a conversation with.

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/messaging/search-users
```

### Get Followed Users

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

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/messaging/followed-users
```

***

## Integration Example

```javascript theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
// 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

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/developers/auth">
    API authentication for messaging.
  </Card>

  <Card title="Error Catalog" icon="triangle-exclamation" href="/developers/error-catalog">
    Messaging error codes and resolutions.
  </Card>
</CardGroup>