Concepts

This page explains the terms you'll meet over and over while integrating. Start with the quick reference below, and read the matching section when you need details.

Quick reference

Term	In one sentence	Identified by
Tenant	The company or team using the service; the unit of billing and management	org_name
App	A separate IM environment, with data isolated from other apps	app_name; the AppKey is org_name#app_name
App Token	The token your server uses to call the REST API, representing the whole app	Obtained with the Client ID and Client Secret
IM user	A person who chats in your app	username
User Token	The token a user gets after signing in on the client, representing only that user	Obtained at sign-in
Conversation	The message stream between two users or within a group	conversation_id; messages ordered by seq
Group	A group with fixed members	group_id
Chat room	A large room with no fixed members and no offline messages	room_id
Channel	A standalone audio/video channel, neither a group nor a chat room	channel_id
Runtime policy	Switches and values that control how the app behaves	Set in the console
Quotas, plans	Platform safety limits, and allowances given by plan	See Limits

Tenants and members

A tenant represents a company or team using the service, and is the unit of billing and management. Signing up for the console also creates a tenant, and the system gives it a unique org_name that can't be changed.

One console account can join several tenants, with one role in each:

Role	Description
owner	The person in charge of the tenant; one per tenant, transferable
admin	Admins can manage apps, credentials, members and policy
developer	Developers can view apps, manage IM users and most policy

See Members and roles.

Apps and AppKey

An app is a separate IM environment: users, friends, groups and messages all belong to an app, and data is fully isolated between apps. Create separate apps for testing and production.

Each app is identified by app_name, unique within the tenant, which can't be changed after creation or reused after deletion. org_name and app_name together make the app's AppKey:

1100250925#demo
└── org_name ┘└ app_name

Clients use the AppKey to sign in; server REST API URLs use org_name and app_name separately.

Server credentials and App Token

Each app has a set of server credentials: a Client ID and a Client Secret. Your server exchanges them for an App Token, then calls the server REST API with it. The App Token carries admin rights over the whole app and must only be used on your server. See Authentication and App Token.

IM users and User Token

An IM user is an end user in the app, i.e. someone who chats in your app, uniquely identified by a username (username). Usernames are unique within the app and case-insensitive. Usually your server creates an IM user when your user signs up, and the username can be the user ID from your own system.

After signing in on the client, a user gets a User Token, used to call client APIs and open the persistent connection. A User Token represents only that user and can only act on their own data. Each sign-in creates a session tied to one device; a user can be signed in on several devices at once, up to the number set in the runtime policy.

Conversations and messages

A conversation is the message stream between two users (one-to-one) or in a group (group chat), identified by conversation_id. Each message in a conversation has a sequence number seq that starts at 1 and increases within the conversation; clients sync and page by seq, so nothing is missed.

Each user has their own state for a conversation: how far they've read, unread count, whether it's pinned, whether they deleted it, and so on, which only affects them. See Message format and Conversations and history.

Friends and block list

Users can add each other as friends: one sends a request, and they become friends once the other accepts; your server can also make two users friends directly. Users can put others on their block list, and blocked people can't message them or add them as a friend. By default users can chat one-to-one without being friends; the runtime policy can limit messaging to friends only.

Groups

A group has fixed members and is identified by group_id. Member roles are owner, admin and regular member. A group can be public or private, and can set whether joining needs approval, who can invite members, and so on. Group messages go to all members of the group.

Chat rooms

A chat room has no fixed members: users join when they enter and leave when they exit or disconnect; only users currently in the room get messages, and no offline messages are kept. It suits live streams, events and other crowded, fast-moving scenes. Chat rooms are identified by room_id, have an owner and admins, and can mute and ban users. See Managing chat rooms.

Audio/video calls

Users can start one-to-one or group audio/video calls. The IM service handles signaling such as calling, ringing, answering and hanging up, plus call records, while audio and video travel through the platform's media service, so you don't need to integrate another audio/video service. See Audio and video calls.

Files

Message attachments such as images, voice, video and files, as well as user avatars, group avatars and group files, are first uploaded to the IM service with a use, which sets the size limit, who can download it and how long it's kept. File content goes straight to object storage, and when done you get:

• File URL: a fixed URL for attachments and group files, put in messages. It can't be downloaded directly; a user signed in to this app or your server exchanges it for a short-lived download URL, so others who get the URL can't download it;
• Public URL: the URL of an avatar, directly accessible, put in a user's or group's profile.

Attachments are kept for 30 days by default (adjustable in the runtime policy); after that the file is deleted but the message itself remains. See File overview.

Offline push

When a user's devices are offline, new messages, incoming calls and so on are notified through the phone's push channels (APNs, FCM and each phone maker's channel). You upload each channel's credentials in the console, and the client registers the device's push token after signing in. See Offline push.

Event callbacks

Event callbacks are HTTP requests the IM service sends to your server: notifying you when users, friends, groups, messages and so on change (event callbacks), or asking whether to allow an action such as sending a message, adding a friend or joining a group (sync callbacks). Callback endpoints and the events to receive are set in the console, and every request is signed. See Callback overview.

Content moderation

Content moderation checks messages, profiles, request notes and files for violations before and after they're sent, rejects, replaces or acts on them after the fact per the app's settings, and records violations and applies automatic penalties. See Content moderation.

Persistent connections and presence

After signing in, the client opens a WebSocket persistent connection to the service: new messages, friend requests, group changes and so on are pushed over it in real time to all of the user's online devices. A user is online while at least one device holds a persistent connection, and your server can query users' presence.

Runtime policy and quotas

The runtime policy controls how an app behaves, such as the message recall time limit, the number of devices signed in at once, whether read receipts are on, and token lifetimes. A tenant has a default policy, and each app can override any of its items. See Runtime policy.

Quotas are safety limits the platform sets per app, such as REST API calls per second and messages per minute; going over returns 429 rate_limited. See Rate limits and app status.

Plans and billing

Each app subscribes to a plan, which sets allowances such as registered users, concurrent connections, storage and concurrent calls; once one is used up, the matching actions are rejected. Usage is counted daily, and each tenant gets one bill a month. See Plans and billing.

Standalone RTC channels

A channel is identified by your business channel_id, separate from IM groups, chat rooms and regular calls. A channel session is one user's participation from one signed-in device, identified by a string session_id; the media room name isn't the business channel ID.

Open channels accept any user signed in to this app; ticket channels require a one-time ticket your server issues to a specific user. The publisher role can publish, while subscriber only receives. Tickets, IM sign-in tokens and media tokens each have their own purpose and can't stand in for each other. See Channel overview.