Custom Publishers

Custom publishers are bot-like senders that allow you to send messages via the API with a branded identity. Instead of messages appearing from a user, they appear from your custom publisher.

What is a Custom Publisher?

A custom publisher is a virtual sender identity with:

A custom name (e.g., "HR Bot", "Schedule Assistant")
A custom avatar/icon
A unique ID used in API calls

When you send messages via the Chat API, the senderId parameter refers to the custom publisher's ID.

Setting Up Custom Publishers

Custom publishers are configured in the Connecteam admin dashboard:

Log in to Connecteam Admin
Navigate to Settings → Feed settings
Find the Custom Publishers section
Click Add Custom Publisher
Configure:
- Name: Display name for the bot
- Avatar: Icon/image for the bot
Save and note the Publisher ID

📝
Publisher ID
The Publisher ID is the integer value you'll use as senderId in all Chat API calls.

Using Custom Publishers

In API Calls

The senderId field in message requests must be a valid custom publisher ID:

{
  "senderId": 12345,
  "text": "This message appears from the custom publisher"
}

Example: Different Publishers for Different Purposes

// Define publishers for different use cases
const PUBLISHERS = {
  HR_BOT: 12345,
  SCHEDULE_BOT: 12346,
  ALERTS_BOT: 12347
};

// HR announcements
await sendMessage(conversationId, PUBLISHERS.HR_BOT, 'Reminder: Benefits enrollment ends Friday!');

// Schedule notifications
await sendMessage(conversationId, PUBLISHERS.SCHEDULE_BOT, 'Your shift has been updated.');

// System alerts
await sendMessage(conversationId, PUBLISHERS.ALERTS_BOT, 'Maintenance scheduled for tonight.');

Best Practices

Create Purpose-Specific Publishers

Create different publishers for different automation purposes:

Publisher	Use Case
HR Bot	HR announcements, policy updates
Schedule Bot	Shift notifications, schedule changes
Alerts Bot	System alerts, maintenance notices
Onboarding Bot	New employee welcome messages

Use Descriptive Names

Choose names that make it clear who/what is sending:

✅ "Schedule Assistant"
✅ "HR Updates"
❌ "Bot 1"
❌ "API Sender"

Add Recognizable Avatars

Use distinct icons so users can quickly identify automated messages.

Error Handling

If you use an invalid senderId, you'll receive:

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

Common causes:

Publisher ID doesn't exist
Publisher was deleted
Typo in the ID

Integration Pattern

class ChatPublisher {
  constructor(apiKey, publisherId, publisherName) {
    this.apiKey = apiKey;
    this.publisherId = publisherId;
    this.publisherName = publisherName;
  }

  async sendToConversation(conversationId, text, attachments = []) {
    const response = await fetch(
      `https://api.connecteam.com/chat/v1/conversations/${conversationId}/message`,
      {
        method: 'POST',
        headers: {
          'X-API-KEY': this.apiKey,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          senderId: this.publisherId,
          text,
          attachments
        })
      }
    );
    return response.json();
  }

  async sendPrivate(userId, text, attachments = []) {
    const response = await fetch(
      `https://api.connecteam.com/chat/v1/conversations/privateMessage/${userId}`,
      {
        method: 'POST',
        headers: {
          'X-API-KEY': this.apiKey,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          senderId: this.publisherId,
          text,
          attachments
        })
      }
    );
    return response.json();
  }
}

// Create publisher instances
const hrBot = new ChatPublisher('YOUR_API_KEY', 12345, 'HR Bot');
const scheduleBot = new ChatPublisher('YOUR_API_KEY', 12346, 'Schedule Bot');

// Use them
await hrBot.sendToConversation('conv-123', 'New policy update posted!');
await scheduleBot.sendPrivate(9170357, 'Your shift starts in 1 hour.');

API Reference