Conversations

List team chats and channels, and send messages to them.

Endpoints

Method	Endpoint	Description
GET	/chat/v1/conversations	Get team chats and channels
POST	/chat/v1/conversations/{conversationId}/message	Send message to conversation

Get Conversations

Retrieve a paginated list of team chats and channels. Private conversations are excluded.

Query Parameters

Parameter	Type	Required	Default	Description
limit	integer	No	10	Results per page (1-100)
offset	integer	No	0	Pagination offset

Example Request

curl --request GET \
  --url 'https://api.connecteam.com/chat/v1/conversations?limit=50' \
  --header 'X-API-KEY: YOUR_API_KEY'

Response

{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "conversations": [
      {
        "id": "conv-abc123",
        "title": "Engineering Team",
        "type": "team"
      },
      {
        "id": "conv-def456",
        "title": "Company Announcements",
        "type": "channel"
      }
    ]
  },
  "paging": {
    "offset": 2
  }
}

Response Fields

Field	Type	Description
id	string	Unique conversation identifier
title	string	Conversation display name
type	string	`team` or `channel`

Send Message to Conversation

Send a message to a team chat or channel.

Path Parameters

Parameter	Type	Required	Description
conversationId	string	Yes	Conversation 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

Attachment Object

Field	Type	Required	Description
type	string	Yes	`image` or `file`
fileId	string	Yes	File ID from Attachments API

Example: Send Text Message

curl --request POST \
  --url https://api.connecteam.com/chat/v1/conversations/conv-abc123/message \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "senderId": 12345,
    "text": "Daily standup reminder: Meeting starts in 15 minutes!"
  }'

Example: Send Message with Image

curl --request POST \
  --url https://api.connecteam.com/chat/v1/conversations/conv-abc123/message \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "senderId": 12345,
    "text": "Here is the updated floor plan",
    "attachments": [
      {
        "type": "image",
        "fileId": "file-abc123"
      }
    ]
  }'

Example: Send Message with File

curl --request POST \
  --url https://api.connecteam.com/chat/v1/conversations/conv-abc123/message \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "senderId": 12345,
    "text": "Attached is the weekly report",
    "attachments": [
      {
        "type": "file",
        "fileId": "file-def456"
      }
    ]
  }'

Response

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

Integration Example

class ChatIntegration {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.connecteam.com/chat/v1/conversations';
  }

  async getConversations(limit = 100) {
    const conversations = [];
    let offset = 0;

    while (true) {
      const response = await fetch(
        `${this.baseUrl}?limit=${limit}&offset=${offset}`,
        { headers: { 'X-API-KEY': this.apiKey } }
      );
      const data = await response.json();
      
      conversations.push(...data.data.conversations);
      
      if (data.data.conversations.length < limit) break;
      offset = data.paging.offset;
    }

    return conversations;
  }

  async sendMessage(conversationId, senderId, text, attachments = []) {
    const response = await fetch(
      `${this.baseUrl}/${conversationId}/message`,
      {
        method: 'POST',
        headers: {
          'X-API-KEY': this.apiKey,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ senderId, text, attachments })
      }
    );
    return response.json();
  }

  async broadcastToAllTeams(senderId, text) {
    const conversations = await this.getConversations();
    const teamChats = conversations.filter(c => c.type === 'team');
    
    for (const chat of teamChats) {
      await this.sendMessage(chat.id, senderId, text);
    }
  }
}

// Usage
const chat = new ChatIntegration('YOUR_API_KEY');
await chat.sendMessage('conv-abc123', 12345, 'Hello team!');

Error Responses

404 Not Found

Conversation not found:

{
  "detail": "Conversation not found"
}

Sender not found:

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

400 Bad Request

Multiple non-image attachments:

{
  "detail": "Multiple non-image attachments are not allowed"
}

Attachment not uploaded:

{
  "detail": "File upload not completed"
}

API Reference