Team chat API
REST endpoints for team chat in SKUFlow: 7 operations with parameters, request and response fields, permissions and curl examples.
Base URL: https://app.skuflow.ai/api. Every call needs Authorization: Bearer skf_… (Authentication); {organizationId} ($ORGANIZATION_ID in the examples) is your business's id.
| Operation | Endpoint | Risk |
|---|---|---|
| What's waiting for me (badge counts) | GET /organizations/{organizationId}/badges | read |
| My conversations | GET /organizations/{organizationId}/chat | read |
| Who I can message | GET /organizations/{organizationId}/chat/people | read |
| Open a direct message | POST /organizations/{organizationId}/chat/direct | write |
| A conversation's messages | GET /organizations/{organizationId}/chat/{conversationId}/messages | read |
| Write in a conversation | POST /organizations/{organizationId}/chat/{conversationId}/messages | write |
| Mark a conversation read | POST /organizations/{organizationId}/chat/{conversationId}/read | write |
What's waiting for me (badge counts)
GET /organizations/{organizationId}/badges
The counts behind the red badges in the app: unread team chat messages (and which conversations), unread notifications, customers' texts waiting (messages: unread customer-text notifications, engagement.read), and what waits in the inbox: new requests (requests.read). Counts the caller may not see are 0. Read-only.
| Permission | organization.read (Owner, Admin, Staff, Member) |
| Risk | read, OAuth scope skuflow.read. Read: reads only. |
| MCP tool | chat_badges (toolset team) |
Example
curl "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/badges" \
-H "Authorization: Bearer $SKUFLOW_API_KEY"Response
200: the answer's fields
| Field | Type | Description |
|---|---|---|
chat | integer | |
chatConversations | array of string | |
notifications | integer | |
messages | integer | Unread customer-text notifications in this business (the Messages badge); already counted in notifications. |
inbox | object | |
inbox.requests | integer | NEW requests. |
inbox.total | integer | |
total | integer | chat + notifications + inbox.total: the app icon's badge. |
My conversations
GET /organizations/{organizationId}/chat
The caller's team chat, most recent first: the whole team and their direct messages, each with a title, the last message and the caller's unread count. Read-only.
| Permission | organization.read (Owner, Admin, Staff, Member) |
| Risk | read, OAuth scope skuflow.read. Read: reads only. |
| MCP tool | chat_conversations (toolset team) |
Example
curl "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/chat" \
-H "Authorization: Bearer $SKUFLOW_API_KEY"Response
200: the answer's fields
An array of objects:
| Field | Type | Description |
|---|---|---|
id | string | Conversation id (for …/chat/{conversationId}/messages). |
kind | enum | One of TEAM, DIRECT. |
title | string | Team, or the other person's name. |
lastMessage | object or null | The latest message (first 200 characters). |
lastMessage.body | string | |
lastMessage.author | string | |
lastMessage.at | string (date-time) | |
unread | integer | Messages from others since the caller last read it. |
Who I can message
GET /organizations/{organizationId}/chat/people
The business's members (name and role) to start a direct message with; not the caller. Read-only.
| Permission | organization.read (Owner, Admin, Staff, Member) |
| Risk | read, OAuth scope skuflow.read. Read: reads only. |
| MCP tool | chat_people (toolset team) |
Example
curl "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/chat/people" \
-H "Authorization: Bearer $SKUFLOW_API_KEY"Response
200: the answer's fields
An array of objects:
| Field | Type | Description |
|---|---|---|
userId | string | The member's user id (for POST /chat/direct). |
name | string | |
role | string |
Open a direct message
POST /organizations/{organizationId}/chat/direct
The caller's conversation with another member of the business (made on first use). 404 for someone who isn't a member.
| Permission | organization.read (Owner, Admin, Staff, Member) |
| Risk | write, OAuth scope skuflow.write. Write: creates or changes records inside the business; nothing leaves it. |
| MCP tool | chat_openDirect (toolset team) |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | Up to 200 characters. |
Example
curl -X POST "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/chat/direct" \
-H "Authorization: Bearer $SKUFLOW_API_KEY" \
-H "Content-Type: application/json" \
-d '{"userId":"user_id"}'Response
200: the answer's fields
| Field | Type | Description |
|---|---|---|
id | string | Conversation id (for …/chat/{conversationId}/messages). |
kind | enum | One of TEAM, DIRECT. |
A conversation's messages
GET /organizations/{organizationId}/chat/{conversationId}/messages
The latest messages, oldest first (before for older ones), with who wrote each. 404 for a conversation the caller can't see. Read-only.
| Permission | organization.read (Owner, Admin, Staff, Member) |
| Risk | read, OAuth scope skuflow.read. Read: reads only. |
| MCP tool | chat_messages (toolset team) |
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
conversationId | path | string | Yes | |
before | query | string (date-time) | No | |
limit | query | integer | No | 1–100. |
Example
curl "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/chat/{conversationId}/messages" \
-H "Authorization: Bearer $SKUFLOW_API_KEY"Response
200: the answer's fields
An array of objects:
| Field | Type | Description |
|---|---|---|
id | string | |
userId | string | The author's user id. |
body | string | |
createdAt | string (date-time) | |
author | string | The author's name. |
mine | boolean | Sent by the caller. |
Write in a conversation
POST /organizations/{organizationId}/chat/{conversationId}/messages
Posts a message (up to 4000 characters); the others in the conversation are notified. Returns it.
| Permission | organization.read (Owner, Admin, Staff, Member) |
| Risk | write, OAuth scope skuflow.write. Write: creates or changes records inside the business; nothing leaves it. |
| MCP tool | chat_send (toolset team) |
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
conversationId | path | string | Yes |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
body | string | Yes | Up to 4000 characters. |
Example
curl -X POST "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/chat/{conversationId}/messages" \
-H "Authorization: Bearer $SKUFLOW_API_KEY" \
-H "Content-Type: application/json" \
-d '{"body":"string"}'Response
201: the answer's fields
| Field | Type | Description |
|---|---|---|
id | string | |
userId | string | The author's user id. |
body | string | |
createdAt | string (date-time) | |
mine | boolean | Sent by the caller. |
Mark a conversation read
POST /organizations/{organizationId}/chat/{conversationId}/read
Everything in it up to now counts as read for the caller.
| Permission | organization.read (Owner, Admin, Staff, Member) |
| Risk | write, OAuth scope skuflow.write. Write: creates or changes records inside the business; nothing leaves it. |
| MCP tool | chat_read (toolset team) |
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
conversationId | path | string | Yes |
Example
curl -X POST "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/chat/{conversationId}/read" \
-H "Authorization: Bearer $SKUFLOW_API_KEY"Response
200: the answer's fields
| Field | Type | Description |
|---|---|---|
ok | true |