Skip to content
CCS Chat Docs

Archive and reactivate conversations

Goal

Section titled “Goal”

When a relationship ends, for example a coach stops coaching a client, archive their conversation. Users keep reading it; nobody can post. If the relationship resumes, reactivate it.

Prerequisites

Section titled “Prerequisites”
Chat permission: conversations.updateMachine scope (any of): chat:conversations.managechat:sync
  • The conversation_id. Store it when you create the conversation, or look it up with chat.conversations.list.
  • To archive a GROUP or a channel, the client also needs chat:groups.manage or chat:channels.manage.

Steps

Section titled “Steps”

  1. Archive. Set the status to ARCHIVED. The library has archive(id) for it.

  2. Reactivate when needed. Set the status back to ACTIVE with reactivate(id). For a DIRECT conversation you can also create it again: creating from your backend reopens the pair’s archived conversation.

  3. Handle posts to an archived conversation. Sending answers 422 conversation_archived. Treat it as “not allowed now”, not as a failure to retry.

archive.ts
import { ChatUnprocessableError } from '@central-code-station/ccs-chat-client';
import { chat } from './guide-chat-client';


// The coaching relationship ends: users keep reading, nobody can post.
export async function endCoaching(conversationId: string): Promise<void> {
  const conversation = await chat.conversations.archive(conversationId);
  console.log(conversation.status); // 'ARCHIVED'
}


// The relationship resumes.
export async function resumeCoaching(conversationId: string): Promise<void> {
  await chat.conversations.reactivate(conversationId);
}


export async function postIfActive(conversationId: string, body: string): Promise<boolean> {
  try {
    await chat.messages.send(conversationId, { body, actor_user_id: 'coach-ana' });
    return true;
  } catch (error) {
    if (error instanceof ChatUnprocessableError && error.code === 'conversation_archived') return false;
    throw error;
  }
}

What archived means

Section titled “What archived means”
Who Effect
Members They keep reading the conversation. Sending a message answers conversation_archived.
Users They cannot reopen an archived DIRECT conversation. Creating it as a user returns the archived conversation unchanged.
Your backend It can reactivate it, or create the DIRECT conversation again.
Connected members They receive a conversation.updated event.

Only your backend can change the status of a DIRECT conversation. A user who tries gets direct_conversation_immutable, and so does anyone who tries to change anything else on a DIRECT conversation. Your backend client cannot delete conversations: no machine scope carries conversations.delete.

Verify

Section titled “Verify”

Archive a test conversation, then try to send a message into it. The call fails with 422 and error: "conversation_archived". Reactivate it and send again: the message is accepted. The archive and the status change appear in the audit log.

Troubleshooting

Section titled “Troubleshooting”
Symptom Cause and fix
403 insufficient_scope or missing_capability The client lacks chat:conversations.manage. For a group or channel it also needs chat:groups.manage or chat:channels.manage.
404 not_found The id is wrong, or the conversation belongs to another tenant or application. Chat does not say which.
422 direct_conversation_immutable You sent more than status for a DIRECT conversation.
A DIRECT conversation is active again Something created it again from your backend. Check your relationship data before calling create.
Section titled “Related”