Channels

A channel is one conversation. Messages live inside channels. Users join channels via memberships. Everything else (typing, presence) is scoped to channels too.

Cariosan has two channel types and is opinionated about keeping it that way.

Direct channels

Exactly two members. Meant for DMs between a buyer and a seller, a patient and a doctor, a rider and a driver. The server can auto-generate a stable external_id or you can supply your own.

ch, _ := client.CreateChannel(ctx, cariosan.CreateChannelRequest{
    Type:              cariosan.ChannelDirect,
    MemberExternalIDs: []string{"user_alice", "user_bob"},
})

Group channels

Any number of members. Use them for support rooms, project threads, anything not strictly 1-on-1. Group channels require an explicit external_id so your backend can address them later.

ch, _ := client.CreateChannel(ctx, cariosan.CreateChannelRequest{
    Type:              cariosan.ChannelGroup,
    ExternalID:        "order_123",
    Name:              "Order #123 support",
    MemberExternalIDs: []string{"user_alice", "user_support_1"},
})

Group channels can grow and shrink over their lifetime:

client.AddChannelMembers(ctx, "order_123", []string{"user_support_2"})
client.RemoveChannelMember(ctx, "order_123", "user_alice")

Group avatars

Group channels can carry an optional avatar_url (an icon). Set it when you create the channel, or change it later. Direct channels have no avatar — clients render the other participant instead.

curl -X POST https://api.cariosan.com/v1/channels \
  -H "Authorization: Bearer pk_live_...:sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "group",
    "external_id": "order_123",
    "name": "Order #123",
    "avatar_url": "https://cdn.example.com/g/order_123.png",
    "created_by": "user_alice",
    "member_external_ids": ["user_alice", "user_support_1"]
  }'

Roles & group admins

Every group member has a role: admin or member (direct channels have neither). Pass created_by on create — that user is added as a member (if missing) and made the admin; everyone else starts as a member.

Management follows a hybrid model:

• Your backend (API key) is god-mode. It created the channel and can rename it, change the avatar, and add/remove members with no role checks — exactly what you want for trusted server-side automation (PATCH /v1/channels/:id, POST/DELETE /v1/channels/:id/members).
• An admin can also manage the group from the app with their user JWT. Cariosan enforces the admin role on these client routes (/v1/me/channels/:id/...); a non-admin member gets 403 FORBIDDEN.

import { Cariosan } from "@cariosan/client";
 
const cariosan = new Cariosan({ apiUrl, token }); // token = a user JWT
const channel = cariosan.channel("order_123");
 
// All four require the acting user to be an admin (else they throw 403):
await channel.updateChannel({ name: "Order #123 — VIP", avatarUrl: "https://cdn.example.com/g/v2.png" });
await channel.addMembers(["user_support_2"]);
await channel.setMemberRole("user_support_2", "admin"); // promote (or "member" to demote)
await channel.removeMember("user_support_1");           // kick
 
// Roles + presence in one call:
const { members } = await channel.getPresence();
members.find((m) => m.external_id === "user_alice")?.role; // "admin"

Membership enforcement

Every client-JWT read (GET /v1/me/channels, GET /v1/channels/:id/messages, GET /v1/channels/:id/presence) filters by membership automatically. Non-members get 403 NOT_A_MEMBER.

Deleting a channel

client.DeleteChannel(ctx, "order_123")