Sblurp

ChatService

Each call is POST {base}/sblurp.v1.ChatService/<Call> with a Connect, gRPC or gRPC-Web body. See Protocol and transport for the basics. Field types in links are on the Types page. Tools can read every call and type from 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 TEXT or PRIVATE
topic string
category string

Response CreateChannelResponse:

Field Type Notes
channel 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

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

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 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

EditMessage

Your own messages only.

Request EditMessageRequest:

Field Type Notes
message_id string
text string

Response EditMessageResponse:

Field Type Notes
message 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

MarkRead

Request MarkReadRequest:

Field Type Notes
channel_id string
seq int64

Response MarkReadResponse:

Field Type Notes
read_state ReadState

SetTyping

Request SetTypingRequest:

Field Type Notes
channel_id string
thread_root_id string

Response SetTypingResponse:

No fields.

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

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

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

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

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

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

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

LeaveChannel

Request LeaveChannelRequest:

Field Type Notes
channel_id string

Response LeaveChannelResponse:

No fields.

View this page as Markdown · Glossary · API schema.json · openapi.json