Domínios — Chat
O chat é servido por uma API própria, o Semear.Chat.Api, separada das APIs de administração, console e lending. Ela atende as rotas REST em /v5/chats e o hub SignalR em /v5/chats/hub, e aceita o mesmo token de login usado no admin, no console e no lending. Chaves de API não usam o chat.
Como funciona
- Grupo: conversa com nome e vários participantes da mesma empresa, criada por quem tem a permissão "Criar conversa em grupo". Quem cria é o dono; administradores alteram o nome, incluem e removem participantes e escolhem outros administradores. Cada alteração aparece na conversa como mensagem do sistema. Quem sai ou é removido deixa de ver o grupo; o histórico de participação é mantido. Se o dono sair, um administrador (ou o participante mais antigo) passa a ser o dono.
- Conversa direta: liga dois usuários humanos. Pedir de novo uma conversa com a mesma pessoa devolve a conversa que já existe.
- Quem pode conversar com quem: o usuário só encontra e abre conversa com usuários ativos da própria empresa que estejam dentro do seu nível de acesso do chat. Quando o perfil tem regras de nível próprias do chat, elas valem no lugar do nível de acesso global.
- Mensagem gravada primeiro: toda mensagem é gravada pela API REST e só depois avisada pelo hub. Quem perde a conexão recupera pela API o que chegou nesse intervalo.
- Envio sem duplicar: cada mensagem leva um
clientMessageIdgerado pelo aplicativo. Reenviar com o mesmo identificador devolve a mensagem já gravada. - Não lidas: cada participante guarda a última mensagem que leu. São não lidas as mensagens posteriores a ela enviadas por outras pessoas.
- Anexos: documentos, fotos, vídeos e áudios ficam no armazenamento de arquivos da empresa de quem enviou, na pasta Sistema/Chat. O tipo do anexo é definido pelo tipo do arquivo.
- Nada é apagado: mensagens só recebem linhas novas; conversa e participação não são excluídas.
Conexão em tempo real
O aplicativo conecta em /v5/chats/hub informando o token em access_token. O token precisa ter o identificador de chat do usuário (signal_id); tokens emitidos antes dessa mudança são recusados e o usuário precisa entrar de novo.
Eventos enviados pelo hub:
| Evento | Conteúdo | Quando |
|---|---|---|
MessageCreated | A mensagem gravada | Uma mensagem nova foi gravada numa conversa do usuário, inclusive as enviadas por ele em outra aba. |
ConversationUpdated | O id da conversa | Uma conversa nova incluiu o usuário. |
Read | Conversa, usuário e última mensagem lida | Um participante leu mensagens. |
Endpoints
| Método | Rota | Uso |
|---|---|---|
GET | /v5/chats | Conversas do usuário, das mais recentes para as mais antigas, com a quantidade de não lidas e o outro participante das conversas diretas. |
GET | /v5/chats/unread-count | Total de mensagens não lidas do usuário. |
POST | /v5/chats/users/search | Usuários com quem o usuário pode abrir conversa. |
POST | /v5/chats/direct | Abre a conversa direta com o usuário informado em userId, ou devolve a que já existe. |
GET | /v5/chats/{id} | Uma conversa do usuário. |
POST | /v5/chats/group | Cria um grupo com name e os participantes em userIds. |
PUT | /v5/chats/{id} | Altera nome e descrição do grupo. Só administradores. |
GET | /v5/chats/{id}/participants | Participantes ativos da conversa, com o papel de cada um. |
POST | /v5/chats/{id}/participants | Inclui os usuários de userIds no grupo. Só administradores. |
DELETE | /v5/chats/{id}/participants/{userId} | Remove um participante do grupo. Só administradores; o dono não pode ser removido. |
PUT | /v5/chats/{id}/participants/{userId}/role | Torna o participante administrador (admin) ou participante comum (member). Só administradores. |
POST | /v5/chats/{id}/leave | Sai do grupo. |
POST | /v5/chats/{id}/read | Marca como lidas as mensagens até messageId; sem messageId, até a última. |
GET | /v5/chats/{id}/messages | Mensagens em ordem de envio. before traz as anteriores a uma mensagem, after as posteriores e limit define a quantidade. |
POST | /v5/chats/{id}/messages | Envia uma mensagem de texto com clientMessageId e content. |
POST | /v5/chats/{id}/attachments | Envia um arquivo (formulário com file, clientMessageId e, opcionalmente, content como legenda). Cada arquivo vira uma mensagem. |
GET | /v5/chats/attachments/{attachmentId}/download | Endereço temporário para abrir ou baixar o anexo. Só participantes da conversa recebem o endereço. |
Configuração
Configuração da empresa na funcionalidade Chat (1181):
| Key | Nome | Uso |
|---|---|---|
max_message_length | Tamanho Máximo da Mensagem do Chat | Quantidade máxima de caracteres de uma mensagem. Sem valor, vale 4000. |
max_attachment_size_mb | Tamanho Máximo do Anexo do Chat (MB) | Tamanho máximo de cada arquivo enviado. Sem valor, vale 25. |
max_group_participants | Máximo de Participantes por Grupo do Chat | Quantidade máxima de participantes de um grupo, contando quem criou. Sem valor, vale 256. |
Valores fixos
ChatConversationType
| Code | Key | Nome |
|---|---|---|
1 | direct | Direta |
2 | group | Grupo |
ChatConversationStatus
Devolvido em status da conversa como StatusField.
| Code | Key | Nome | Cor | Significado |
|---|---|---|---|---|
1 | active | Ativo | Verde | A conversa recebe mensagens. |
2 | closed | Encerrada | Cinza | A conversa pode ser lida, mas não recebe mensagens. |
ChatParticipantRole
| Code | Key | Nome |
|---|---|---|
1 | owner | Dono |
2 | admin | Administrador |
3 | member | Membro |
ChatAttachmentKind
| Code | Key | Nome |
|---|---|---|
1 | document | Documento |
2 | image | Imagem |
3 | video | Vídeo |
4 | audio | Áudio |
ChatMessageType
| Code | Key | Nome |
|---|---|---|
1 | text | Texto |
2 | attachment | Anexo |
3 | system | Sistema |
Mensagens de erro
| Código | Mensagem |
|---|---|
1181001 | Conversa não encontrada |
1181002 | Informe o usuário da conversa |
1181003 | Usuário não encontrado ou inativo |
1181004 | Não é possível abrir uma conversa com você mesmo |
1181005 | Você não tem permissão para conversar com este usuário |
1181006 | Esta conversa está encerrada |
1181007 | Escreva a mensagem |
1181008 | A mensagem passa do tamanho máximo permitido |
1181009 | Identificador da mensagem é obrigatório |
1181010 | Mensagem não encontrada |
1181011 | Sessão sem identificador de chat. Entre novamente no sistema |
1181012 | Selecione o arquivo |
1181013 | O arquivo passa do tamanho máximo permitido no chat |
1181014 | Não foi possível enviar o arquivo |
1181015 | Anexo não encontrado |
1181016 | Informe o nome do grupo |
1181017 | O nome do grupo passa do tamanho máximo permitido |
1181018 | Selecione ao menos um participante |
1181019 | O grupo passa da quantidade máxima de participantes |
1181020 | Esta conversa não é um grupo |
1181021 | Só administradores do grupo podem fazer esta alteração |
1181022 | Participante não encontrado no grupo |
1181023 | O dono do grupo não pode ser removido nem ter o papel alterado |
1181024 | Papel do participante inválido |