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

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

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

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

Use Cases

Automated Notifications

Send personalized notifications to users:

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

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:

{
  "detail": "User not found"
}

User suspended:

{
  "detail": "User is suspended"
}

Sender not found:

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

400 Bad Request

Empty message:

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

API Reference