---
updatedAt: 2026-01-28T15:05:08.000Z
---

Fetch the complete documentation index at: https://developer.connecteam.com/llms.txt. Use this file to discover all available pages before exploring further.

# Private Messages

Send direct private messages to individual users. If a conversation between the custom publisher and the user already exists, the message is added to it. Otherwise, a new private conversation is created.

## Endpoint

| Method | Endpoint                                       | Description                  |
| :----- | :--------------------------------------------- | :--------------------------- |
| POST   | /chat/v1/conversations/privateMessage/{userId} | Send private message to user |

***

## Send Private Message

### Path Parameters

| Parameter | Type    | Required | Description      |
| :-------- | :------ | :------- | :--------------- |
| userId    | integer | Yes      | Target user's ID |

### Request Body

| Field       | Type    | Required | Description                      |
| :---------- | :------ | :------- | :------------------------------- |
| senderId    | integer | Yes      | Custom publisher ID              |
| text        | string  | Yes      | Message content (max 1000 chars) |
| attachments | array   | No       | List of file/image attachments   |

***

## Examples

### Send Simple Private Message

```bash
curl --request POST \
  --url https://api.connecteam.com/chat/v1/conversations/privateMessage/9170357 \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "senderId": 12345,
    "text": "Hi! Your shift has been updated for tomorrow."
  }'
```

### Send Private Message with Attachment

```bash
curl --request POST \
  --url https://api.connecteam.com/chat/v1/conversations/privateMessage/9170357 \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "senderId": 12345,
    "text": "Here is your updated schedule",
    "attachments": [
      {
        "type": "file",
        "fileId": "file-schedule-123"
      }
    ]
  }'
```

### Response

```json
{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {}
}
```

***

## Use Cases

### Automated Notifications

Send personalized notifications to users:

```javascript
async function notifyUser(userId, senderId, message) {
  const response = await fetch(
    `https://api.connecteam.com/chat/v1/conversations/privateMessage/${userId}`,
    {
      method: 'POST',
      headers: {
        'X-API-KEY': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        senderId,
        text: message
      })
    }
  );
  return response.json();
}

// Notify about timesheet approval
await notifyUser(9170357, 12345, 'Your timesheet for last week has been approved!');

// Notify about shift assignment
await notifyUser(9170358, 12345, 'You have been assigned to the morning shift tomorrow.');
```

### Bulk Private Messaging

```javascript
async function sendBulkPrivateMessages(userIds, senderId, message) {
  const results = [];
  
  for (const userId of userIds) {
    try {
      await notifyUser(userId, senderId, message);
      results.push({ userId, success: true });
    } catch (error) {
      results.push({ userId, success: false, error: error.message });
    }
  }
  
  return results;
}

// Notify multiple users
const userIds = [9170357, 9170358, 9170359];
const results = await sendBulkPrivateMessages(
  userIds,
  12345,
  'Reminder: Complete your safety training by Friday.'
);
```

***

## Error Responses

### 404 Not Found

**User not found:**

```json
{
  "detail": "User not found"
}
```

**User suspended:**

```json
{
  "detail": "User is suspended"
}
```

**Sender not found:**

```json
{
  "detail": "Sender id not found"
}
```

### 400 Bad Request

**Empty message:**

```json
{
  "detail": [{
    "loc": ["body", "text"],
    "msg": "text must not be empty",
    "type": "value_error"
  }]
}
```

***

[API Reference](https://developer.connecteam.com/reference/)