Collab Chat | FastComments Docs

Adicionar Comentários Inline em Tempo Real a Documentos, Livros, Etc

O FastComments Collab Chat permite que os usuários destaquem e anotem qualquer conteúdo de texto no seu site, criando discussões em tópicos vinculadas a seleções de texto específicas. Os usuários podem selecionar palavras, frases ou parágrafos inteiros para iniciar conversas colaborativas diretamente dentro do seu conteúdo.

Esse recurso é perfeito para feedback editorial, ambientes de leitura colaborativa, plataformas educacionais, revisão de documentos e qualquer cenário em que você deseje discussões contextuais ancoradas a um texto específico.

Observe que esta documentação é específica da funcionalidade Collab Chat. Você pode adicionar comentários para conteúdo com muitas páginas, como Livros, com thread-per-page, sem usar collab chat. O FastComments também não cobra por página ou por thread. Collab Chat é especificamente quando você quer permitir que os usuários selecionem texto e comentem na seção de texto destacada.

Você pode ver um exemplo aqui.

Primeiros passos

Início Rápido

Começar com o Collab Chat é simples. Você precisa do script FastComments Collab Chat, de um elemento HTML contendo o texto que você deseja anotar, e de um objeto de configuração com seu Tenant ID.

Instalação

Adicione o script do Collab Chat à sua página:

Carregando o script do Collab Chat

Copy

<script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>

Implementação Básica

Aqui está um exemplo mínimo:

Implementação Básica do Collab Chat

Copy

Run

<!DOCTYPE html>
<html>
<head>
    <title>My Article with Collab Chat</title>
</head>
<body>
    <!-- Seu contêiner de conteúdo -->
    <div id="article-content" style="min-height: 500px;">
        <h1>My Article Title</h1>
        <p>This is a paragraph that users can annotate. Simply highlight any text to start a discussion!</p>
        <p>You can have multiple paragraphs, and users can highlight text across any of them.</p>
    </div>
    <!-- Load the Collab Chat script -->
    <script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
    <!-- Inicialize o Collab Chat -->
    <script>
        FastCommentsCollabChat(document.getElementById('article-content'), {
            tenantId: 'demo'
        });
    </script>
</body>
</html>

Replace 'demo' with your actual FastComments Tenant ID if it's not already, which you can find in your FastComments dashboard.

Como Funciona

Uma vez inicializado, os usuários podem selecionar qualquer texto dentro do elemento alvo. Após um breve atraso (3,5 segundos no desktop), um prompt aparece permitindo que iniciem uma discussão. Quando uma discussão é criada, um destaque visual aparece no texto. Outros usuários podem passar o cursor sobre o destaque ou clicar nele para visualizar e participar da discussão. Todas as discussões sincronizam em tempo real entre todos os visitantes.

Demo ao Vivo

Você pode ver o Collab Chat em ação em nossa página de demonstração ao vivo.

Próximos Passos

Agora que você tem o básico funcionando, você pode personalizar a aparência e o comportamento no guia de Opções de Configuração. Consulte o guia de Comportamento de Seleção de Texto para entender como a seleção de texto funciona. Saiba sobre estilização e suporte ao modo escuro no guia de Personalização. Para integrações avançadas, explore a Referência da API.

Bibliotecas Frontend

Todas as bibliotecas frontend do FastComments (react, vue, angular, etc) incluem o Collab Chat.

Exemplos

Exemplo Básico

A maneira mais simples de usar o Collab Chat é direcionar um único contêiner de conteúdo. Este exemplo mostra como habilitar anotações de texto em um artigo:

Exemplo básico de Collab Chat

Copy

Run

<!DOCTYPE html>
<html>
<head>
    <title>My Article with Collab Chat</title>
</head>
<body>
    <div id="article-content" style="min-height: 500px">
        <h1>My Article Title</h1>
        <p>This is a paragraph that users can annotate. Simply highlight any text to start a discussion!</p>
        <p>You can have multiple paragraphs, and users can highlight text across any of them.</p>
    </div>
    <script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
    <script>
        FastCommentsCollabChat(document.getElementById('article-content'), {
            tenantId: 'demo'
        });
    </script>
</body>
</html>

Exemplo com ID de URL Personalizado (por página de livro, artigo, etc.)

Por padrão, o Collab Chat usa a URL da página combinada com o caminho do elemento e o intervalo de texto para identificar conversas. Você pode fornecer um urlId personalizado para ter mais controle sobre como as conversas são agrupadas:

Collab Chat com ID de URL Personalizado

Copy

<script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
<script>
    FastCommentsCollabChat(document.getElementById('article-content'), {
        tenantId: 'demo',
        urlId: 'book-one-page-2'
    });
</script>

Isso é útil se a estrutura da sua URL mudar, mas você quiser manter as mesmas conversas, ou se quiser compartilhar as mesmas anotações de conversa em várias páginas.

Exemplo com Modo Escuro

Se seu site tiver um fundo escuro, ative o suporte ao modo escuro para garantir que a interface do chat apareça corretamente:

Collab Chat com Modo Escuro

Copy

Run

<!DOCTYPE html>
<html>
<head>
    <title>My Article with Collab Chat - Dark Mode</title>
    <style>
        body {
            background-color: #1a1a1a !important;
            color: #e0e0e0 !important;
            font-family: system-ui, -apple-system, sans-serif;
            padding: 20px;
            margin: 0;
        }
        #article-content {
            max-width: 800px;
            margin: 0 auto;
            background-color: #2d2d2d;
            padding: 20px;
            border-radius: 8px;
        }
        h1 {
            color: #ffffff !important;
        }
        p {
            color: #e0e0e0 !important;
            line-height: 1.6;
        }
        .fastcomments-collab-chat-top-bar {
            background-color: #2d2d2d !important;
            color: #e0e0e0 !important;
            border-bottom: 1px solid #444 !important;
        }
    </style>
</head>
<body>
    <div id="article-content" style="min-height: 500px">
        <h1>My Article Title</h1>
        <p>This is a paragraph that users can annotate. Simply highlight any text to start a discussion!</p>
        <p>You can have multiple paragraphs, and users can highlight text across any of them.</p>
    </div>
    <script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
    <script>
        FastCommentsCollabChat(document.getElementById('article-content'), {
            tenantId: 'demo',
            hasDarkBackground: true
        });
    </script>
</body>
</html>

Exemplo com Barra Superior Desativada

Por padrão, o Collab Chat exibe uma barra superior com a contagem de usuários e de discussões. Você pode desativá-la:

Collab Chat com Barra Superior Desativada

Copy

Run

<!DOCTYPE html>
<html>
<head>
    <title>My Article with Collab Chat - No Top Bar</title>
</head>
<body>
    <div id="article-content" style="min-height: 500px">
        <h1>My Article Title</h1>
        <p>This is a paragraph that users can annotate. Simply highlight any text to start a discussion!</p>
        <p>You can have multiple paragraphs, and users can highlight text across any of them.</p>
    </div>
    <script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
    <script>
        FastCommentsCollabChat(document.getElementById('article-content'), {
            tenantId: 'demo',
            topBarTarget: null
        });
    </script>
</body>
</html>

Exemplo com Callback de Contagem de Comentários

Você pode rastrear quando comentários são adicionados ou atualizados usando o callback commentCountUpdated:

Collab Chat com Callback de Contagem de Comentários

Copy

<script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
<script>
    FastCommentsCollabChat(document.getElementById('article-content'), {
        tenantId: 'demo',
        commentCountUpdated: function(count) {
            console.log('Total comments:', count);
            document.getElementById('comment-badge').textContent = count;
        }
    });
</script>

Exemplo com Múltiplas Seções

Você pode inicializar o Collab Chat em várias seções separadas da sua página. Cada seção terá suas próprias anotações independentes:

Collab Chat em Múltiplas Seções

Copy

<div id="intro-section">
    <h2>Introduction</h2>
    <p>Content for the introduction...</p>
</div>
<div id="main-section">
    <h2>Main Content</h2>
    <p>Content for the main article...</p>
</div>
<script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
<script>
    // Initialize on intro section
    FastCommentsCollabChat(document.getElementById('intro-section'), {
        tenantId: 'demo',
        urlId: 'my-article-intro'
    });
    // Initialize on main section
    FastCommentsCollabChat(document.getElementById('main-section'), {
        tenantId: 'demo',
        urlId: 'my-article-main'
    });
</script>

Adicionando comentários em tempo real a livros online

Você pode inicializar o Collab Chat por página, se desejar, e ter threads separadas por página; basta passar ao parâmetro urlId um valor como book-one-page1. Essa configuração também funciona para o widget de comentários normal.

Opções de configuração

Visão Geral

FastComments Collab Chat estende o widget de comentários padrão do FastComments, portanto herda todas as opções de configuração do widget base enquanto adiciona algumas específicas para anotações de texto.

Configuração Obrigatória

tenantId

Seu ID de Tenant do FastComments é obrigatório. Você pode encontrá-lo no seu painel do FastComments.

Exemplo de configuração

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo'
});

Opções específicas do Collab Chat

urlId

Por padrão, o Collab Chat gera um identificador único para cada conversa com base na URL da página, no caminho DOM até o elemento e na faixa de texto selecionada. Você pode sobrescrever isso com um urlId personalizado.

Exemplo de configuração

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo',
    urlId: 'my-custom-page-id'
});

Isso é útil quando sua estrutura de URL pode mudar mas você quer manter as mesmas conversas, ou quando você quer compartilhar anotações entre várias páginas.

topBarTarget

Controla a exibição da barra superior que mostra a contagem de usuários e a contagem de discussões. Defina como null para desativar completamente a barra superior, ou forneça um elemento DOM para renderizá-la em um local específico.

Exemplo de configuração

Copy

// Desativar barra superior
FastCommentsCollabChat(element, {
    tenantId: 'demo',
    topBarTarget: null
});
// Renderizar barra superior em local personalizado
FastCommentsCollabChat(element, {
    tenantId: 'demo',
    topBarTarget: document.getElementById('custom-header')
});

hasDarkBackground

Habilita o estilo de modo escuro quando sua página tem um fundo escuro. Essa detecção é automática, mas pode ser desejável sobrescrevê-la.

Exemplo de configuração

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo',
    hasDarkBackground: true
});

commentCountUpdated

Uma função de callback que é acionada sempre que a contagem de comentários muda. Isso é útil para atualizar elementos da UI como badges ou títulos da página.

Exemplo de configuração

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo',
    commentCountUpdated: function(count) {
        console.log('Total comments:', count);
        document.getElementById('badge').textContent = count;
    }
});

Opções de Configuração Herdadas

Como o Collab Chat estende o widget de comentários padrão, você pode usar qualquer opção de configuração do widget base do FastComments. Aqui estão algumas opções comumente usadas:

locale

Define o idioma da interface do widget. O FastComments suporta dezenas de idiomas.

Exemplo de configuração

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo',
    locale: 'es'  // Espanhol
});

readonly

Torna todas as conversas somente leitura. Os usuários podem ver anotações existentes, mas não podem criar novas nem responder.

Exemplo de configuração

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo',
    readonly: true
});

sso and simpleSSO

Integre com seu sistema de autenticação usando Single Sign-On.

Exemplo de configuração

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo',
    sso: {
        // Configuração de SSO
    }
});

Consulte a documentação de SSO para detalhes completos sobre as opções de autenticação.

maxReplyDepth

Controle quantos níveis de profundidade as respostas podem ter. Por padrão, o Collab Chat define isso como 0, significando que todos os comentários são planos (sem respostas aninhadas). Você pode alterar isso se quiser conversas encadeadas.

Exemplo de configuração

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo',
    maxReplyDepth: 3  // Permitir 3 níveis de aninhamento
});

Configuração interna

Essas opções são definidas automaticamente pelo Collab Chat e não devem ser sobrescritas:

O productId é definido automaticamente como 3 para o Collab Chat. A extensão floating-chat é carregada automaticamente para fornecer a funcionalidade da janela de chat. O widget detecta automaticamente dispositivos móveis (telas com menos de 768px de largura) e ajusta a UI de acordo.

Exemplo completo

Aqui está um exemplo mostrando várias opções de configuração juntas:

Exemplo de configuração

Copy

FastCommentsCollabChat(document.getElementById('article'), {
    tenantId: 'demo',
    urlId: 'my-article-v2',
    hasDarkBackground: false,
    locale: 'en',
    topBarTarget: document.getElementById('custom-header'),
    commentCountUpdated: function(count) {
        document.title = count > 0 ? `(${count}) My Article` : 'My Article';
    },
    sso: {
        // Sua configuração de SSO
    },
    maxReplyDepth: 1
});

Para uma lista completa de todas as opções de configuração disponíveis herdadas do widget base, consulte a documentação principal de configuração do FastComments.

Comportamento da seleção de texto

Como a Seleção de Texto Funciona

Quando os usuários selecionam texto dentro do contêiner do Collab Chat, o widget captura essa seleção e permite que eles iniciem uma discussão. A seleção pode ser tão pequena quanto uma única palavra ou tão grande quanto vários parágrafos que abrangem diferentes elementos.

Atraso na Seleção

Em desktops, há um atraso de 3,5 segundos entre o momento em que um usuário seleciona o texto e quando o prompt de discussão aparece. Isso evita que a interface pisque quando os usuários estão apenas destacando texto para copiar ou ler. Em dispositivos móveis, o prompt aparece imediatamente, já que a seleção de texto é mais intencional em telas sensíveis ao toque.

IDs exclusivos de conversa

Cada conversa recebe um urlId único que combina a URL da página, o caminho do elemento no DOM e o intervalo de texto serializado. Isso garante que cada seleção de texto crie uma conversa distinta que possa ser encontrada novamente depois.

Se você fornecer um urlId personalizado na sua configuração, ele será combinado com o caminho do elemento e o intervalo de texto para criar o identificador final.

Destaques Visuais

Quando existe uma discussão para uma seleção de texto específica, esse texto recebe um destaque visual. O destaque é implementado usando cores de fundo e aparece ao passar o cursor ou quando a janela de chat associada está aberta.

O sistema de destaque funciona envolvendo o texto selecionado em um elemento especial que pode ser estilizado. Essa abordagem garante que os destaques permaneçam precisos mesmo quando a estrutura HTML subjacente é complexa.

Posicionamento da Janela de Chat

Quando um usuário clica em um destaque ou cria uma nova anotação, uma janela de chat aparece perto do texto selecionado. O widget calcula automaticamente a melhor posição para essa janela com base no espaço disponível na viewport.

O sistema de posicionamento usa classes CSS como to-right, to-left, to-top e to-bottom para indicar em que direção a janela de chat deve se estender a partir do destaque. Em dispositivos móveis (telas com menos de 768px de largura), a janela de chat sempre aparece em tela cheia para melhor usabilidade.

Dimensões da Janela de Chat

As janelas de chat têm 410px de largura em desktops, com espaçamento de 20px e uma seta visual de 16px apontando para o texto destacado. Essas dimensões são fixas para garantir comportamento consistente, mas você pode personalizar a aparência com CSS.

Seleções entre Elementos

Os usuários podem selecionar texto que abrange múltiplos elementos HTML, como destacar do meio de um parágrafo até o início de outro. O sistema de serialização de intervalo lida com isso corretamente e destacará todo o texto selecionado mesmo através das fronteiras dos elementos.

Compatibilidade com Navegadores

O sistema de seleção de texto usa a API padrão window.getSelection(), que é suportada em todos os navegadores modernos. Para versões antigas do Internet Explorer, ele recorre a document.selection para compatibilidade.

Persistência da Seleção

Uma vez que uma conversa é criada para uma seleção de texto, essa anotação persiste mesmo se a página for recarregada. O intervalo serializado e o caminho no DOM permitem que o widget restaure os destaques exatamente na mesma localização quando os usuários retornarem à página.

Isso funciona de forma confiável desde que o conteúdo da sua página permaneça estável. Se você alterar o conteúdo de texto ou reestruturar seu HTML, as anotações existentes podem não mais se alinhar corretamente com o texto. Por esse motivo, é melhor evitar mudanças significativas no conteúdo em páginas com anotações ativas, ou considerar migrar as anotações quando alterações no conteúdo forem necessárias.

Personalização

Suporte ao Modo Escuro

Modo Escuro Dinâmico

Se o modo escuro do seu site é controlado adicionando a classe .dark ao elemento body, a UI do Collab Chat respeitará isso automaticamente sem exigir reinicialização. Os estilos do widget são projetados para responder à presença dessa classe.

Exemplo de CSS para Modo Escuro

Copy

/* Seu CSS de modo escuro */
body.dark {
    background: #1a1a1a;
    color: #ffffff;
}

Estilização personalizada com CSS

Você pode personalizar a aparência dos destaques, janelas de chat e outros elementos usando CSS. O widget adiciona classes específicas que você pode direcionar em sua folha de estilo.

Os destaques de texto usam o sistema de estilização de balões de comentário do FastComments, então quaisquer personalizações aplicadas ao widget de comentários padrão também afetarão o Collab Chat.

Personalização da Barra Superior

A barra superior mostra o número de usuários online e o número de discussões. Você pode personalizar sua posição fornecendo um elemento personalizado como topBarTarget:

Localização personalizada da barra superior

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo',
    topBarTarget: document.getElementById('my-custom-header')
});

Ou desativá-la completamente definindo-a como null:

Desativar barra superior

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo',
    topBarTarget: null
});

Comportamento em dispositivos móveis

Em telas com largura inferior a 768px, o Collab Chat alterna automaticamente para um layout otimizado para dispositivos móveis. As janelas de chat aparecem em tela cheia em vez de flutuarem ao lado do texto, e a demora na seleção é removida para uma interação mais imediata.

Esse comportamento é embutido e não requer nenhuma configuração. O widget detecta o tamanho da tela automaticamente e ajusta-se conforme necessário.

Aparência das janelas de chat

As janelas de chat têm 410px de largura no desktop com uma seta de 16px apontando para o texto destacado. As janelas se posicionam automaticamente com base no espaço disponível na viewport, usando classes de posicionamento como to-right, to-left, to-top e to-bottom.

Você pode adicionar CSS personalizado para ajustar cores, fontes, espaçamento ou outras propriedades visuais dessas janelas. As janelas de chat usam a mesma estrutura de componentes que o widget padrão do FastComments, portanto herdam quaisquer personalizações globais que você aplicou.

Localização

O Collab Chat oferece todas as mesmas opções de localização que o widget padrão do FastComments. Defina a opção locale para exibir o texto da UI em diferentes idiomas:

Definir localidade

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo',
    locale: 'es'  // Espanhol
});

O FastComments suporta dezenas de idiomas. A configuração de locale afeta todos os textos da UI, incluindo prompts, botões e texto de espaço reservado.

Opções de personalização herdadas

Como o Collab Chat estende o widget de comentários padrão, ele herda todas as opções de personalização do widget base. Isso inclui classes CSS personalizadas, traduções personalizadas, personalização de avatar, formatação de datas e muito mais.

Consulte a documentação principal de personalização do FastComments para a lista completa de opções de personalização disponíveis.

Trabalhando com fontes personalizadas

Se o seu site usa fontes personalizadas, a UI do Collab Chat herdará essas fontes do CSS da sua página. Pode ser necessário criar uma regra de personalização do widget e @import quaisquer fontes no CSS personalizado nessa regra se você quiser que a janela de chat flutuante use as mesmas fontes.

Sincronização em tempo real

Atualizações em Tempo Real

Collab Chat usa conexões WebSocket para sincronizar todas as conversas em tempo real entre todos os usuários conectados. Quando alguém cria uma nova anotação, adiciona um comentário ou exclui uma discussão, todos os outros usuários visualizando a mesma página veem a atualização imediatamente sem precisar atualizar.

Como a Sincronização via WebSocket Funciona

Quando você inicializa o Collab Chat, o widget estabelece uma conexão WebSocket com os servidores do FastComments. Essa conexão permanece aberta durante a sessão do usuário e escuta por atualizações relacionadas à página atual.

O sistema WebSocket usa três tipos de mensagens de broadcast para o Collab Chat. O evento new-text-chat é disparado quando alguém cria uma nova anotação na página. O evento updated-text-chat é disparado quando alguém atualiza uma conversa existente. O evento deleted-text-chat é disparado quando alguém exclui uma anotação.

Sistema de ID de Broadcast

Para evitar efeitos de eco onde os usuários veem suas próprias ações sendo transmitidas de volta para eles, cada atualização inclui um broadcastId único. Quando um usuário cria ou atualiza uma anotação, seu cliente gera um UUID para essa operação. Quando o WebSocket retransmite a atualização para todos os clientes, o cliente de origem ignora a atualização porque ela corresponde ao seu próprio broadcastId.

Isso garante uma interação suave em que os usuários veem suas alterações imediatamente na interface sem esperar a ida e volta pelo servidor, enquanto ainda assegura que todos os outros usuários recebam a atualização.

Contagem de Usuários em Tempo Real

A barra superior exibe o número de usuários atualmente visualizando a página. Essa contagem é atualizada em tempo real conforme os usuários entram e saem. A contagem de usuários é fornecida pela mesma conexão WebSocket e incrementa/decrementa automaticamente com base nos eventos de conexão e desconexão.

Resiliência de Conexão

Se a conexão WebSocket cair devido a problemas de rede ou manutenção do servidor, o widget tenta se reconectar automaticamente. Durante o período de reconexão, os usuários ainda podem interagir com as anotações existentes, mas não verão atualizações em tempo real de outros usuários até que a conexão seja restabelecida.

Uma vez reconectado, o widget ressincroniza para garantir que nenhuma atualização tenha sido perdida. Isso acontece de forma transparente sem exigir intervenção do usuário.

Considerações sobre Largura de Banda

As mensagens WebSocket são leves e contêm apenas as informações essenciais necessárias para sincronizar o estado. Criar uma nova anotação normalmente usa menos de 1KB de largura de banda. O sistema também inclui agrupamento inteligente para reduzir a frequência de mensagens durante períodos de alta atividade.

Suas métricas de uso no painel do FastComments acompanham pubSubMessageCount e pubSubBandwidth para que você possa monitorar a atividade de sincronização em tempo real em seus sites.

Sincronização entre Abas

Se um usuário tiver a mesma página aberta em múltiplas abas do navegador, as atualizações em uma aba aparecem imediatamente nas outras. Isso funciona através do mesmo mecanismo de sincronização via WebSocket e não requer nenhuma configuração adicional.

Segurança

As mensagens WebSocket são transmitidas por conexões seguras (WSS) e incluem validação do tenant para garantir que os usuários recebam apenas atualizações de conversas que estão autorizados a ver. O servidor valida todas as operações antes de retransmiti-las para prevenir acesso ou manipulação não autorizados.

Referência da API

Visão Geral da API

Collab Chat fornece três endpoints REST da API para gerenciar conversas de texto programaticamente. Esses endpoints permitem que você recupere, crie e exclua anotações sem usar o widget no navegador.

Estes são endpoints públicos que autenticam usuários via cookies do navegador. Eles não usam chaves de API. Os usuários devem estar logados no FastComments no navegador para acessar esses endpoints.

URL base

Todos os endpoints da API do Collab Chat estão em:

URL base

Copy

https://fastcomments.com/comment-collab-chats

Autenticação

Esses endpoints autenticam usuários via cookies do navegador. Eles não usam chaves de API. Os usuários devem estar logados no FastComments no navegador para acessar esses endpoints.

Obter todas as conversas

Recupere todas as conversas de texto para uma página específica.

Endpoint

Endpoint GET

Copy

GET /comment-collab-chats/:tenantId?urlId=<urlId>

Parâmetros

tenantId (parâmetro de caminho, obrigatório) é o seu FastComments Tenant ID.

urlId (parâmetro de query, obrigatório) é o identificador da página para a qual você deseja recuperar conversas.

Resposta

A resposta inclui o status da API, informações da sessão do usuário atual se autenticado, um array de conversas com seus IDs, URLs e intervalos de texto, um identificador de URL limpo, uma flag indicando se o usuário atual é administrador do site ou moderador, e detalhes de conexão WebSocket para sincronização ao vivo incluindo tenantIdWS, urlIdWS, e userIdWS.

Exemplo de requisição

Exemplo de requisição GET

Copy

curl "https://fastcomments.com/comment-collab-chats/demo?urlId=my-article-page" \
  --cookie "your-session-cookie"

Exemplo de resposta

Exemplo de resposta GET

Copy

{
  "status": "success",
  "user": {
    "id": "user123",
    "username": "john_doe"
  },
  "conversations": [
    {
      "_id": "conv123",
      "urlId": "my-article-page:p:0:15,0:45{abc123}",
      "range": "0:15,0:45{abc123}"
    },
    {
      "_id": "conv456",
      "urlId": "my-article-page:h1:5:20,5:35{def456}",
      "range": "5:20,5:35{def456}"
    }
  ],
  "urlIdClean": "my-article-page",
  "isSiteAdmin": false,
  "tenantIdWS": "demo",
  "urlIdWS": "my-article-page",
  "userIdWS": "user123"
}

Criar conversa

Crie uma nova conversa de texto para uma seleção de texto específica.

Endpoint

Endpoint POST

Copy

POST /comment-collab-chats/:tenantId

Parâmetros

tenantId (parâmetro de caminho, obrigatório) é o seu FastComments Tenant ID.

O corpo da requisição deve ser JSON e incluir os seguintes campos obrigatórios.

urlId (string, obrigatório) é o identificador base da página.

urlIdWithRange (string, obrigatório) é a URL combinada com o intervalo de texto, por exemplo my-page:p:0:15,0:45{abc123}.

pageTitle (string, obrigatório) é o título da página.

selector (string, obrigatório) é o caminho DOM para o elemento que contém o texto selecionado.

range (string, obrigatório) é o intervalo de texto serializado no formato startOffset:endOffset,startOffset:endOffset{checksum}.

createdFromCommentId (string, obrigatório) é o ID do comentário que iniciou este chat.

broadcastId (string, obrigatório) é um UUID para sincronização ao vivo para prevenir efeitos de eco.

Resposta

A resposta inclui o status da API e o ID da conversa recém-criada.

Exemplo de requisição

Exemplo de requisição POST

Copy

curl -X POST "https://fastcomments.com/comment-collab-chats/demo" \
  --cookie "your-session-cookie" \
  -H "Content-Type: application/json" \
  -d '{
    "urlId": "my-article-page",
    "urlIdWithRange": "my-article-page:p:0:15,0:45{abc123}",
    "pageTitle": "My Article Title",
    "selector": "div#article > p:nth-child(2)",
    "range": "0:15,0:45{abc123}",
    "createdFromCommentId": "comment789",
    "broadcastId": "550e8400-e29b-41d4-a716-446655440000"
  }'

Exemplo de resposta

Exemplo de resposta POST

Copy

{
  "status": "success",
  "createdChatId": "conv789"
}

Excluir conversa

Exclua uma conversa de texto existente. Este endpoint requer permissões de administrador ou moderador, ou a conversa deve ter sido criada pelo usuário autenticado.

Endpoint

Endpoint DELETE

Copy

DELETE /comment-collab-chats/:tenantId/:chatId

Parâmetros

tenantId (parâmetro de caminho, obrigatório) é o seu FastComments Tenant ID.

chatId (parâmetro de caminho, obrigatório) é o ID da conversa a ser excluída.

broadcastId (corpo da requisição, obrigatório) é um UUID para sincronização ao vivo.

Exemplo de requisição

Exemplo de requisição DELETE

Copy

curl -X DELETE "https://fastcomments.com/comment-collab-chats/demo/conv789" \
  --cookie "your-session-cookie" \
  -H "Content-Type: application/json" \
  -d '{
    "broadcastId": "550e8400-e29b-41d4-a716-446655440001"
  }'

Exemplo de resposta

Exemplo de resposta DELETE

Copy

{
  "status": "success"
}

Limitação de taxa

Esses endpoints estão sujeitos à limitação de taxa padrão da API do FastComments. O middleware de limitação de taxa aplica-se por tenant para prevenir abusos ao mesmo tempo em que permite padrões normais de uso.

Respostas de erro

Todos os endpoints retornam códigos de status HTTP padrão. Uma resposta 400 indica parâmetros de requisição inválidos. Uma resposta 401 significa que a autenticação falhou. Uma resposta 403 indica permissões insuficientes. Uma resposta 404 significa que a conversa não foi encontrada. Uma resposta 429 indica que o limite de taxa foi excedido.

As respostas de erro incluem um corpo JSON com detalhes:

Exemplo de resposta de erro

Copy

{
  "status": "error",
  "message": "Conversation not found"
}

Rastreamento de uso

Criar conversas incrementa sua métrica de uso conversationCreateCount. Toda a atividade de sincronização via WebSocket incrementa pubSubMessageCount e pubSubBandwidth. Você pode monitorar essas métricas no painel do FastComments em analytics de uso.

Tem perguntas?

Isso é tudo sobre o FastComments Collab Chat! Se você tiver alguma pergunta, precisar de ajuda com a implementação ou tiver sugestões de recursos, por favor nos avise abaixo ou entre em contato com nossa equipe de suporte.

Para ver exemplos ao vivo, confira Govscent.org, que usa o Collab Chat em produção.

Idioma 🇧🇷 Português (Brasil)

Primeiros passos

Configuração

Personalização

Avançado

Adicionar Comentários Inline em Tempo Real a Documentos, Livros, Etc

Primeiros passos

Início Rápido

Instalação

Implementação Básica

Como Funciona

Demo ao Vivo

Próximos Passos

Bibliotecas Frontend

Exemplos

Exemplo Básico

Exemplo com ID de URL Personalizado (por página de livro, artigo, etc.)

Exemplo com Modo Escuro

Exemplo com Barra Superior Desativada

Exemplo com Callback de Contagem de Comentários

Exemplo com Múltiplas Seções

Adicionando comentários em tempo real a livros online

Opções de configuração

Visão Geral

Configuração Obrigatória

tenantId

Opções específicas do Collab Chat

urlId

topBarTarget

hasDarkBackground

commentCountUpdated

Opções de Configuração Herdadas

locale

readonly

sso and simpleSSO

maxReplyDepth

Configuração interna

Exemplo completo

Comportamento da seleção de texto

Como a Seleção de Texto Funciona

Atraso na Seleção

IDs exclusivos de conversa

Destaques Visuais

Posicionamento da Janela de Chat

Dimensões da Janela de Chat

Seleções entre Elementos

Compatibilidade com Navegadores

Persistência da Seleção

Personalização

Suporte ao Modo Escuro

Modo Escuro Dinâmico

Estilização personalizada com CSS

Personalização da Barra Superior

Comportamento em dispositivos móveis

Aparência das janelas de chat

Localização

Opções de personalização herdadas

Trabalhando com fontes personalizadas

Sincronização em tempo real

Atualizações em Tempo Real

Como a Sincronização via WebSocket Funciona

Sistema de ID de Broadcast

Contagem de Usuários em Tempo Real

Resiliência de Conexão

Considerações sobre Largura de Banda

Sincronização entre Abas

Segurança

Referência da API

Visão Geral da API

URL base

Autenticação

Obter todas as conversas

Endpoint

Parâmetros

Resposta

Exemplo de requisição

Exemplo de resposta

Criar conversa

Endpoint

Parâmetros