--- title: "ChatService API reference" description: "Every ChatService call of the Sblurp community server: what it does, who may call it, and its request and response fields." nav: "ChatService" doc_version: 1 last_updated: 2026-10-18 --- # ChatService Each call is `POST {base}/sblurp.v1.ChatService/` with a Connect, gRPC or gRPC-Web body. See [Protocol and transport](/docs/api) for the basics. Field types in links are on the [Types](/docs/api/types) page. Tools can read every call and type from [schema.json](/docs/api/schema.json). ## Channels and messages ### CreateChannel Admin or owner only. Names are normalized: "Book Club" becomes book-club. Request `CreateChannelRequest`: | Field | Type | Notes | |---|---|---| | `name` | `string` | | | `kind` | [ChannelKind](/docs/api/types#channelkind) | TEXT or PRIVATE | | `topic` | `string` | | | `category` | `string` | | Response `CreateChannelResponse`: | Field | Type | Notes | |---|---|---| | `channel` | [Channel](/docs/api/types#channel) | | ### UpdateChannel Admin or owner only. DMs cannot be updated. Request `UpdateChannelRequest`: | Field | Type | Notes | |---|---|---| | `channel_id` | `string` | | | `name` | optional `string` | | | `topic` | optional `string` | | | `category` | optional `string` | | | `position` | optional `int32` | | | `header_image_id` | optional `string` | An uploaded image's id (POST /upload) for the header; "" removes it. | Response `UpdateChannelResponse`: | Field | Type | Notes | |---|---|---| | `channel` | [Channel](/docs/api/types#channel) | | ### OpenDM Any member, with 1 to 8 others. Returns the existing DM when one has exactly these members, and puts the caller back in it if they left it. PERMISSION_DENIED when the caller and one of the others blocked each other (either way). Request `OpenDMRequest`: | Field | Type | Notes | |---|---|---| | `member_ids` | repeated `string` | the others; the caller is added | Response `OpenDMResponse`: | Field | Type | Notes | |---|---|---| | `channel` | [Channel](/docs/api/types#channel) | | ### ListMessages Request `ListMessagesRequest`: | Field | Type | Notes | |---|---|---| | `channel_id` | `string` | | | `thread_root_id` | `string` | set to list a thread's replies | | `before_id` | `string` | page backwards from this message; empty = newest | | `limit` | `int32` | default 50, max 200 | | `around_id` | `string` | Set at most one of before_id, after_id and around_id. this message, about limit/2 older ones and the rest newer (jump to a search hit) | | `after_id` | `string` | page forwards from this message (newer ones) | Response `ListMessagesResponse`: | Field | Type | Notes | |---|---|---| | `messages` | repeated [Message](/docs/api/types#message) | oldest first | | `has_more` | `bool` | older messages exist before the first one | | `has_more_after` | `bool` | newer messages exist after the last one (after_id and around_id only) | ### SendMessage Any member who can see the channel. Text up to 8,000 characters, at most 10 attachments. In a DM, PERMISSION_DENIED when the sender and another member blocked each other (either way). A DM message puts members who left that DM back in it (they get channel_updated). People may send 5 messages per second (burst 10); bots follow the server's -bot-rate and -bot-burst. Request `SendMessageRequest`: | Field | Type | Notes | |---|---|---| | `channel_id` | `string` | | | `text` | `string` | | | `thread_root_id` | `string` | | | `client_id` | `string` | idempotency key from the client | | `attachment_ids` | repeated `string` | | Response `SendMessageResponse`: | Field | Type | Notes | |---|---|---| | `message` | [Message](/docs/api/types#message) | | ### EditMessage Your own messages only. Request `EditMessageRequest`: | Field | Type | Notes | |---|---|---| | `message_id` | `string` | | | `text` | `string` | | Response `EditMessageResponse`: | Field | Type | Notes | |---|---|---| | `message` | [Message](/docs/api/types#message) | | ### DeleteMessage Your own messages, or anyone's for a moderator or higher. Request `DeleteMessageRequest`: | Field | Type | Notes | |---|---|---| | `message_id` | `string` | | Response `DeleteMessageResponse`: No fields. ### React At most 50 different emoji per message. Request `ReactRequest`: | Field | Type | Notes | |---|---|---| | `message_id` | `string` | | | `emoji` | `string` | | | `remove` | `bool` | | Response `ReactResponse`: | Field | Type | Notes | |---|---|---| | `message` | [Message](/docs/api/types#message) | | ### MarkRead Request `MarkReadRequest`: | Field | Type | Notes | |---|---|---| | `channel_id` | `string` | | | `seq` | `int64` | | Response `MarkReadResponse`: | Field | Type | Notes | |---|---|---| | `read_state` | [ReadState](/docs/api/types#readstate) | | ### SetTyping Request `SetTypingRequest`: | Field | Type | Notes | |---|---|---| | `channel_id` | `string` | | | `thread_root_id` | `string` | | Response `SetTypingResponse`: No fields. ### Search Request `SearchRequest`: | Field | Type | Notes | |---|---|---| | `query` | `string` | | | `channel_id` | `string` | optional filter | | `limit` | `int32` | default 20, max 100 | Response `SearchResponse`: | Field | Type | Notes | |---|---|---| | `messages` | repeated [Message](/docs/api/types#message) | | ### GetLinkPreviews Previews of up to 5 http(s) links in a message I can see. The server fetches each page once, caches it for a day and serves the image itself, so viewers never contact the linked site. Links that have no preview are left out. Request `GetLinkPreviewsRequest`: | Field | Type | Notes | |---|---|---| | `message_id` | `string` | | Response `GetLinkPreviewsResponse`: | Field | Type | Notes | |---|---|---| | `previews` | repeated [LinkPreview](/docs/api/types#linkpreview) | | ## Membership and moderation Rank: owner > admin > moderator > member. Nobody acts on a member of equal or higher rank. ### AddChannelMembers Any member of a private channel may add others to it. The new members get channel_updated (treat it as an upsert). Request `AddChannelMembersRequest`: | Field | Type | Notes | |---|---|---| | `channel_id` | `string` | | | `member_ids` | repeated `string` | max 50 | Response `AddChannelMembersResponse`: | Field | Type | Notes | |---|---|---| | `channel` | [Channel](/docs/api/types#channel) | | ### RemoveChannelMember Removes a member from a private channel. Your own id leaves the channel, and in a DM (your own id only) hides it until someone writes there again; anyone else needs moderator or higher and a higher rank than theirs. The removed member gets channel_deleted (the channel is gone for them); the rest get channel_updated. Request `RemoveChannelMemberRequest`: | Field | Type | Notes | |---|---|---| | `channel_id` | `string` | | | `member_id` | `string` | | Response `RemoveChannelMemberResponse`: | Field | Type | Notes | |---|---|---| | `channel` | [Channel](/docs/api/types#channel) | | ## Channels and messages ### SetChannelAccess Who can see a TEXT channel, and whether OPT_IN joins new members to it. Admins only. Replaces role_ids. Request `SetChannelAccessRequest`: | Field | Type | Notes | |---|---|---| | `channel_id` | `string` | | | `role_ids` | repeated `string` | | | `is_default` | `bool` | | Response `SetChannelAccessResponse`: | Field | Type | Notes | |---|---|---| | `channel` | [Channel](/docs/api/types#channel) | | ### BrowseChannels Every TEXT channel I can see, joined or not (OPT_IN's "Browse channels"). Request `BrowseChannelsRequest`: No fields. Response `BrowseChannelsResponse`: | Field | Type | Notes | |---|---|---| | `channels` | repeated [Channel](/docs/api/types#channel) | | ### JoinChannel OPT_IN mode only (FAILED_PRECONDITION in ROLES mode). TEXT channels only. Request `JoinChannelRequest`: | Field | Type | Notes | |---|---|---| | `channel_id` | `string` | | Response `JoinChannelResponse`: | Field | Type | Notes | |---|---|---| | `channel` | [Channel](/docs/api/types#channel) | | ### LeaveChannel Request `LeaveChannelRequest`: | Field | Type | Notes | |---|---|---| | `channel_id` | `string` | | Response `LeaveChannelResponse`: No fields. ## Sitemap - [Sblurp: chat for communities](https://sblurp.chat/index.md): Sblurp is group chat with channels, threads and roles. Each community runs on its own server, and one Sblurp account signs you in to all of them. - [About Sblurp](https://sblurp.chat/about.md): Why Sblurp exists: chat for communities that each run their own server, with no ads, no unasked-for AI and an honest word on encryption. - [Privacy at Sblurp](https://sblurp.chat/privacy.md): What sblurp.chat stores about you, what it never stores, what it shares with communities you join, and how to get a copy or delete it. - [Terms of use](https://sblurp.chat/terms.md): The terms for a sblurp.chat account: who can sign up, what you must not do, and what we do and do not promise. A first draft. - [Create your Sblurp account](https://sblurp.chat/signup.md): Create a Sblurp account: one account for every Sblurp community you join. You need an email, a username, a password and to be 13 or older. - [Sign in to Sblurp](https://sblurp.chat/login.md): Sign in to your Sblurp account with your email or username and password, or with a passkey. One account works in every Sblurp community. - [Reset your password](https://sblurp.chat/forgot.md): Forgot your Sblurp password? Type the email you signed up with and we send a link to choose a new one. The link works once, for one hour. - [Sblurp docs](https://sblurp.chat/docs.md): Sblurp documentation: how accounts and communities work, how to run a community server, how to add bots, and the full API reference. - [Accounts and communities](https://sblurp.chat/docs/accounts.md): How a Sblurp account relates to the communities you join: what sblurp.chat keeps, what each community server sees, and what stays private. - [Join a community](https://sblurp.chat/docs/join.md): Join a Sblurp community: add it by address or invite link, answer its questions, choose what to share, and join. - [Sblurp glossary](https://sblurp.chat/docs/glossary.md): The words the Sblurp docs use, from account and community to issuer, track, bot token and seq, each with a link to the page that explains it. - [Run a Sblurp community](https://sblurp.chat/docs/self-host.md): Run a Sblurp community on your own server: one small program and one data folder. What you need, how to start it, and what it stores. - [Run a server](https://sblurp.chat/docs/create.md): For developers: start your own Sblurp community. Run the open-source server, join it first to become the owner, then set it up and invite people. - [Set up a server with AI](https://sblurp.chat/docs/ai.md): Not a developer? Ask an AI assistant such as Claude to set up your Sblurp community server. - [Sblurp server sizes and costs](https://sblurp.chat/docs/hosting.md): Which server size to rent for a Sblurp community and what it costs each month: measured limits per size and prices at Fly.io, DigitalOcean, Hetzner, OVHcloud and AWS Lightsail. - [Run Sblurp on Render](https://sblurp.chat/docs/render.md): Run a Sblurp community server on Render: one Starter web service with a persistent disk, the released image, and optional backups to Cloudflare R2. - [Run Sblurp on Railway](https://sblurp.chat/docs/railway.md): Run a Sblurp community server on Railway: one service from the released image, a volume for /data, and optional backups to Cloudflare R2. - [Run Sblurp on Fly.io](https://sblurp.chat/docs/fly.md): Run a Sblurp community server on Fly.io: one always-on machine with a volume, h2c streaming, and optional backups to Cloudflare R2. - [Run Sblurp on any VPS](https://sblurp.chat/docs/vps.md): Run a Sblurp community server on a small virtual server from Hetzner, OVHcloud, Akamai Linode, Vultr, DigitalOcean or any other host, with Docker Compose. - [Run Sblurp with Docker and Compose](https://sblurp.chat/docs/docker.md): Run a Sblurp community server with Docker Compose and Caddy: the files, the settings, where the data lives, and how to run it behind your own proxy. - [Run Sblurp with Podman](https://sblurp.chat/docs/podman.md): Run a Sblurp community server with a Podman Quadlet file, with daily automatic updates that roll back when a new image does not start. - [Sblurp server configuration](https://sblurp.chat/docs/configuration.md): Every flag and environment variable of the Sblurp community server, with defaults, plus the backup variables of the container image and the built-in limits. - [TLS and reverse proxies for Sblurp](https://sblurp.chat/docs/proxies.md): Put Caddy, nginx or Cloudflare in front of a Sblurp community server without breaking live streams: h2c, no buffering, no compression. - [Back up a Sblurp server](https://sblurp.chat/docs/backups.md): Back up a Sblurp community server: Litestream copies the database to Cloudflare R2 within 10 seconds, an encrypted backup tool copies the files, or make a plain copy. How to restore. - [Update a Sblurp server](https://sblurp.chat/docs/updates.md): Release tracks for the Sblurp server image, the daily update check, manual and automatic updates, and how to roll back. - [Verify a Sblurp release](https://sblurp.chat/docs/provenance.md): Check that a Sblurp server image was built by the public release workflow, with GitHub attestations or cosign. - [Troubleshooting a Sblurp server](https://sblurp.chat/docs/troubleshooting.md): Fix common problems with a Sblurp community server: sign-in fails, messages arrive late, certificates, file links, and where the logs are. - [Invites in Sblurp](https://sblurp.chat/docs/invites.md): Make a Sblurp community invite only, create invite links with an expiry and a use limit, and revoke them. - [Moderation and roles in Sblurp](https://sblurp.chat/docs/moderation.md): Permissions in a Sblurp community (owner, admin, moderator, member), custom roles that limit channels, channel modes, kicks and bans. - [Safety in Sblurp](https://sblurp.chat/docs/safety.md): Who can read your messages, how to protect your account, what to do about unwanted messages, how to report a message, what moderators can do, age rules, and how to reach sblurp.chat. - [Your data in Sblurp](https://sblurp.chat/docs/data.md): What sblurp.chat stores about your account, what a community server stores, who controls each, how long data is kept, backups, export and deletion. - [Sblurp bots](https://sblurp.chat/docs/bots.md): Two ways to add a bot to a Sblurp community: a JavaScript plugin on the server, or a program anywhere that uses the API with a bot token. - [Sblurp bot tokens](https://sblurp.chat/docs/bot-tokens.md): Make a Sblurp bot with a token, run the example bot, and call the API from any language: subscribe to events and reply to mentions. - [Connect an AI agent to Sblurp](https://sblurp.chat/docs/agents.md): How to connect a self-hosted AI agent, such as OpenClaw, NanoClaw or Hermes Agent, to a Sblurp community with a bot token. No built-in connector exists yet. - [Use Sblurp from Claude Code and other MCP clients](https://sblurp.chat/docs/mcp.md): Add a Sblurp community to Claude Code, Claude Desktop, VS Code or another MCP client by URL, sign in with your sblurp.chat account, and let the agent read and post as you. - [Sblurp plugins](https://sblurp.chat/docs/plugins.md): Write a Sblurp bot as one JavaScript file and install it in the app, with the API or in the plugins folder: hooks for joins, messages, slash commands and timers, replies, limits and the dice example. - [Sblurp API: protocol and transport](https://sblurp.chat/docs/api.md): How clients and bots talk to a Sblurp community server: Connect RPC over HTTP, the proto contract, JSON and binary bodies, auth, streaming and versioning. - [Sblurp API explorer](https://sblurp.chat/docs/api/explorer.md): Browse and try every call of the Sblurp community server API in your browser, from the OpenAPI 3.1 description in openapi.json. - [Sblurp API: sign-in and tokens](https://sblurp.chat/docs/api/auth.md): How sign-in works across Sblurp: OAuth 2.0 with PKCE at sblurp.chat, per-server access tokens, JWT claims, refresh token rotation, JWKS, and bot tokens. - [Sblurp API: events](https://sblurp.chat/docs/api/events.md): The Sblurp live event stream: Subscribe, sequence numbers, replay and resync, heartbeats, every event kind, who receives it, and unread counts. - [Sblurp API: uploads and files](https://sblurp.chat/docs/api/files.md): The plain HTTP endpoints of a Sblurp community server: uploads, signed file URLs, custom emoji, invite links and the health check. - [Sblurp API: errors and rate limits](https://sblurp.chat/docs/api/errors.md): Error codes the Sblurp community server returns, what each one means for a client, and the rate limits for people and bots. - [ServerService API reference](https://sblurp.chat/docs/api/server-service.md): Every ServerService call of the Sblurp community server: what it does, who may call it, and its request and response fields. - [ChatService API reference](https://sblurp.chat/docs/api/chat-service.md): Every ChatService call of the Sblurp community server: what it does, who may call it, and its request and response fields. - [BotService API reference](https://sblurp.chat/docs/api/bot-service.md): Every BotService call of the Sblurp community server: what it does, who may call it, and its request and response fields. - [API types](https://sblurp.chat/docs/api/types.md): The messages and enums the Sblurp community server API shares between calls, with every field.