FAQ
Short answers to the questions that come up most. Each links to the page with the full story.
Conversations
Section titled “Conversations”Who creates conversations?
Section titled “Who creates conversations?”In Integrated mode, your backend does. It applies your own rule, such as “a coach may message only their own clients”, and then creates the conversation with its backend client. The user’s app reads and writes in conversations the backend put the user in. In Standalone mode, people create them in the Chat app if their role has the permission. See Create direct conversations.
Why can a user not start a chat?
Section titled “Why can a user not start a chat?”Starting a conversation needs the Chat permission conversations.create, plus groups.create for a group or channels.create for a channel. Without it Chat answers 403 missing_capability. For integrated apps this is intended: leave these permissions out so conversations start only through your backend. Users take part in conversations others created without them. See Grant permissions to roles.
What does creating a DIRECT conversation twice do?
Section titled “What does creating a DIRECT conversation twice do?”Nothing new. A DIRECT conversation dedupes on its two members, so a second create returns the existing conversation. If it was archived, a backend client reopens it. A user gets the archived, read-only conversation back unchanged.
What does archive do?
Section titled “What does archive do?”An archived conversation has status: ARCHIVED. Users keep reading it. Nobody can post: a new message answers 422 conversation_archived. Only your backend client archives and reactivates a DIRECT conversation. See Archive and reactivate.
Can a conversation change its members?
Section titled “Can a conversation change its members?”A DIRECT conversation cannot: it answers 422 direct_conversation_immutable, except for its status by a backend client. Groups and channels can add and remove members. See Conversations.
Tokens and access
Section titled “Tokens and access”How long do tokens last?
Section titled “How long do tokens last?”A user token lasts at most 10 minutes and has no refresh token. Cache it in your app and fetch a new one shortly before it expires. A backend client caches its machine token until shortly before it expires, and ccs-chat-client does this for you. The realtime token that opens the live stream lasts at most 10 minutes, and ccs-chat-notifications-client renews it. See Identity and tokens.
Why do I get 401 with a token for my own API?
Section titled “Why do I get 401 with a token for my own API?”Chat accepts a user token only when its aud is chat-api and its scope contains chat:access. A token for your own API has another audience, so Chat answers 401 invalid_token. Your backend swaps your token for a Chat token with token exchange. See Issue Chat tokens to your users.
Do I send the resource identifier or the audience?
Section titled “Do I send the resource identifier or the audience?”The identifier. Send resource=https://chat.centralcodestation.com/api when you request a token. The audience chat-api appears only inside the token, and only Chat reads it. Sending resource=chat-api fails.
Why do I get 403 client_context_mismatch?
Section titled “Why do I get 403 client_context_mismatch?”A token issued to your application’s client works only in your application’s context: the tenant id and application id you configured. Any other context answers client_context_mismatch. Check tenantId and applicationId in the library options, or the ids in the URL. See Tenants and applications.
Does my web app need a second OAuth client?
Section titled “Does my web app need a second OAuth client?”No. Users sign in to the Identity Server as they do today. Your backend exchanges their token for a Chat token, so there is no redirect, no second client and no extra redirect URI.
Can a backend client delete messages?
Section titled “Can a backend client delete messages?”No. A backend client never gets messages.delete, administration permissions or directory search, whatever its scopes. Reactions, read state and typing are user-only. The author deletes a message with messages.update, or a moderator with messages.delete. See Machine scopes.
What happens if the Identity Server is down?
Section titled “What happens if the Identity Server is down?”When Chat cannot reach the Identity Server and has no recent answer, it responds with 503 identity_unavailable. Retry with a back-off. See The Identity Server comes first.
Web, mobile and features
Section titled “Web, mobile and features”Why does my browser block calls to Chat?
Section titled “Why does my browser block calls to Chat?”Your web origin must be in allowed_origins of your application’s web client at the Identity Server. Chat reads it from there and admits it, with no credentials. You configure nothing on the Chat side, and a new origin works within about a minute. See Register web origins.
Does it work with React Native?
Section titled “Does it work with React Native?”Partly. ccs-chat-user-client uses only the global fetch, so the REST calls work. ccs-chat-notifications-client is not covered: it needs EventSource and the browser’s Push API, which are not generally available in that runtime. You can pass your own eventSourceFactory, but this is untested. Native push registration is not covered. See Mobile and React Native.
Can I send files?
Section titled “Can I send files?”A message can carry up to 10 attachments, but Chat does not store files. An attachment references a file by file_id, and a separate File service is planned. See Messages and Roadmap and limitations.
Is there message search?
Section titled “Is there message search?”Not yet. Chat has no message search. See Roadmap and limitations.
Do I have to use TypeScript?
Section titled “Do I have to use TypeScript?”No. The libraries are TypeScript, but the REST API works from any stack, and you can generate a client from /openapi.json. See Use the REST API from any stack.