Construir sobre o Antimatter

Este guia destina-se a desenvolvedores. Aborda scripts e bots que utilizam a API, integrações baseadas em webhooks e comandos de barra, aplicações (plugins) que adicionam funcionalidades ao servidor e à aplicação web, e a compilação do Antimatter a partir do código-fonte para contribuir para o projeto.

Formas de estender o Antimatter

Escolha a ferramenta mais leve que cumpra a tarefa. As quatro primeiras não requerem acesso ao próprio servidor; as aplicações são executadas dentro dele.

Ferramenta	O que faz	Adequada para
API REST	Tudo o que as aplicações fazem: mensagens, canais, pessoas, ficheiros, definições. Um WebSocket envia eventos à medida que ocorrem.	Scripts, sincronização com outros sistemas, clientes personalizados.
Webhooks de entrada	Uma URL secreta que publica uma mensagem num canal quando algo envia JSON.	Alertas, resultados de CI, monitorização, notificações de outras ferramentas.
Webhooks de saída	O Antimatter chama a sua URL quando uma mensagem num canal público começa com uma palavra de gatilho, ou quando alguém seleciona a sua ação no menu de uma mensagem, e publica a sua resposta.	Automações simples impulsionadas por chat, envio de mensagens para outra ferramenta.
Comandos de barra	As pessoas escrevem `/something`; o Antimatter chama o seu URL e mostra a sua resposta a elas ou ao canal.	Consultas, ações iniciadas a partir do chat.
Bots	Contas criadas para programas, com os seus próprios tokens, uma etiqueta BOT, e mensagens e diálogos interativos.	Assistentes, notificadoras, qualquer coisa que converse com pessoas.
Aplicações (plugins)	Código que é executado dentro do servidor (Go) e na aplicação web (React): ganchos em todas as mensagens, novos menus, painéis, tipos de mensagem, páginas.	Funcionalidades: sondagens, notas, calendários, integrações que necessitam da interface do utilizador.

Na interface, as pessoas chamam aos plugins “aplicações”. Este guia diz “aplicações (plugins)” onde ambas as palavras ajudam, porque o código, a API e a configuração ainda dizem “plugin”.

Compatibilidade com o Mattermost

O Antimatter é um fork do Mattermost. A maior parte do que funciona com um servidor Mattermost funciona com o Antimatter.

O que é igual

A API REST em /api/v4, a sua autenticação, o seu WebSocket e o seu formato de erro. O servidor reporta a versão 12.0.0, pelo que os clientes e as aplicações que verificam a versão do servidor veem um Mattermost recente.
Webhooks e comandos de barra, incluindo os respetivos payloads compatíveis com o Slack.
A API e os hooks de plugins do servidor: o Antimatter mantém-nos tal como estão. O código do servidor compila contra o mesmo módulo Go, github.com/mattermost/mattermost/server/public. O Antimatter apenas adiciona métodos, para o seu serviço de IA (ver O serviço de IA).
O registo de plugins da aplicação web: todos os métodos register… do registo do Mattermost existem em ambas as interfaces web do Antimatter.
Bibliotecas de cliente: o cliente Go model.Client4 e o cliente TypeScript @mattermost/client (ver Bibliotecas de cliente).
Empacotamentos de plugins: um .tar.gz com um manifesto plugin.json. Os plugins assinados com a chave do Mattermost são instalados, tal como os assinados com a chave do Antimatter.

O que é diferente

Duas interfaces web. A nova interface, Fusion, é a predefinida; a interface clássica do Mattermost continua a estar disponível. A Fusion renderiza a maioria dos componentes dos plugins, mas coloca alguns de forma diferente e omite alguns. Uma aplicação pode determinar qual interface está em execução. Ver Suporte para a interface Fusion.
API adicional. O Antimatter adiciona endpoints para as suas próprias funcionalidades: atributos da comunidade, timeouts, mensagens no topo, pedidos de mensagens, substituições de canais e categorias, exportação de canais, movimentação de tópicos, ligações de modelos, ações de mensagens e novos campos nas comunidades. Ver O que o Antimatter adiciona à API.
Funcionalidades adicionais de mensagens. Os anexos de mensagens podem mostrar estágios de pipeline e um pequeno gráfico; as publicações podem ser respostas em linha ou spoilers.
Hooks adicionais da aplicação web para as aplicações: um item no menu "+" do compositor, separadores no seletor de emojis, um painel na vista do canal, um rodapé abaixo dos canais na barra lateral, uma entrada nas páginas de integrações, as vistas de adição e gestão do seletor de emojis, e um painel lateral que reabre onde estava numa nova janela. Ver Hooks exclusivos do Antimatter.
Sem licenças. Todas as funcionalidades estão disponíveis sem uma chave de licença. Os pontos de acesso para licença, período de teste e atualização para a edição empresarial foram removidos; GET /api/v4/license/client permanece para clientes que o solicitem. Algumas aplicações criadas para as edições pagas do Mattermost verificam a presença de uma licença por si mesmas e recusam-se a executar.
Nomes. As equipas são chamadas comunidades na interface, mas a API e o código continuam a usar team. As variáveis de ambiente usam o prefixo AM_, a ferramenta de linha de comandos é amctl e o binário do servidor é antimatter.

Onde reside o código

Tudo é código aberto, na organização AntimatterChat no GitHub. Todos os repositórios funcionam no ramo main.

Repositório	Conteúdo
antimatter	O servidor (Go, em `server/`), ambas as interfaces web (`webapp/fusion` e `webapp/channels`), o cliente TypeScript e `amctl`.
antimatter-docker	As imagens Docker, com as aplicações incluídas, e os ficheiros compose.
`antimatter-plugin-*`	Um repositório por cada aplicação incluída: polls, todo, notes, whiteboard, calendar, mail, gifs, memes, voice-channels, calls, boards (Kanban), playbooks, agents e metrics.
gifs-server	O serviço autoalojado de GIFs e figurinhas utilizado pela aplicação GIFs.
desktop-app, mobile-app, push-proxy	As aplicações para desktop e telemóvel, e o serviço que retransmite notificações push para os telemóveis.
antimatter.chat	Este website e a respetiva documentação.
community	Problemas e discussões para todas as partes do Antimatter.

Antes de começar

Obter um servidor de teste. A opção mais rápida é a imagem Docker: consulte Instalar o Antimatter. Para trabalhar no próprio Antimatter, consulte Compilar a partir do código-fonte.
Verificar o que o servidor permite. Várias funcionalidades de integração estão desativadas por predefinição e requerem um administrador do sistema: tokens de acesso pessoal, contas de bot, substituição de nomes de utilizador e ícones, e carregamento de aplicações. Cada página indica a definição necessária.
Conhecer o URL do seu site. Os exemplos utilizam https://chat.example.com. Substitua-o pelo endereço do seu servidor.

Neste guia

A API REST: autenticação, recursos principais, paginação, erros, limites de taxa, WebSocket, bibliotecas de cliente e as adições do Antimatter.
Webhooks: webhooks de entrada e saída, cargas úteis, anexos e cartões.
Comandos de barra: comandos personalizados, o seu pedido e resposta, preenchimento automático.
Bots e mensagens interativas: contas de bot, botões, menus e diálogos.
Escrever aplicações: a estrutura do plugin, ganchos do servidor, o registo da aplicação web, Fusion, definições, armazenamento, traduções e empacotamento.
Compilar a partir do código-fonte: o servidor, as interfaces web, a imagem Docker e as aplicações.
Contribuir: problemas, pedidos de extração, estilo, traduções, segurança e licenças.

As perguntas são bem-vindas nas discussões da comunidade. Reporte os erros nos problemas da comunidade.