Documentação
Última atualização: 3 de outubro de 2026
No Jira, o menu do app se chama sempre Sago Alerts — Google Chat; dentro, a página aparece no idioma do seu Jira (inglês, espanhol ou português). Aqui citamos os textos em português.
1. Antes de começar
- Um site do Jira Cloud com o app instalado pelo Atlassian Marketplace. Os espaços compartilhados são configurados por um administrador do Jira.
- Uma conta do Google Workspace Business ou Enterprise com o Google Chat. O administrador do Workspace precisa permitir webhooks de entrada. Contas pessoais do Gmail não podem criar webhooks.
- Um computador: o Google Chat não permite criar webhooks pelo app para celular.
2. Criar um webhook no Google Chat
- Abra o Google Chat no navegador e entre no espaço que vai receber as notificações (crie um novo, se precisar).
- Clique no nome do espaço, no topo → Apps e integrações.
- Clique em Adicionar webhooks, dê um nome como “Jira” (a URL do avatar é opcional) e clique em Salvar.
- Ao lado do novo webhook abra o menu Mais (⋮) → Copiar link. O link começa com
https://chat.googleapis.com/v1/spaces/.
Trate o link do webhook como uma senha. Quem tiver o link pode publicar no espaço. Cole-o só no app. Se vazar, exclua o webhook no Google Chat e crie outro.
Se você não vê Adicionar webhooks, o administrador do Google Workspace desativou os webhooks de entrada na sua organização. O Google pode mudar o nome desses menus; o guia oficial do Google está aqui.
3. Adicionar um espaço no Jira
- No Jira, vá em Configurações (⚙) → Apps e, no menu à esquerda, abra Sago Alerts — Google Chat. Só administradores do Jira veem esta página. Na primeira vez, o Jira pode mostrar a tela da Atlassian Permitir acesso (Allow access): o app a usa para verificar, como você, que você é administrador do Jira.
- Clique em Adicionar espaço e preencha o formulário (veja a tabela).
- Clique em Enviar teste. Em poucos segundos a mensagem “Conectado ao Jira ✅” deve aparecer no espaço.
- Clique em Salvar. O espaço aparece na lista com seu filtro e seus eventos.
| Campo | Para que serve |
|---|---|
| Nome | Um rótulo para você, ex.: “Time backend”. Também aparece na mensagem de teste e no título do resumo diário. |
| URL do webhook do Google Chat | O link que você copiou. Depois de salvar, a página só mostra uma versão mascarada; deixe o campo vazio para manter o link salvo. |
| Projetos | Vazio = todos os projetos. |
| Filtro JQL extra | Opcional. Veja Filtrar por projeto e JQL. |
| Notificar quando | Os eventos que este espaço recebe. Veja Escolher o que notificar. |
| Só mudanças de status para | Opcional; aparece quando “O status muda” está marcado. Veja Só certas mudanças de status. |
| Estilo da mensagem | Cartão com detalhes, ou compacto (uma linha). |
| Agrupar as atualizações de um item no mesmo tópico | Ativado por padrão. Veja Tópicos. |
| Idioma das mensagens | Inglês, espanhol ou português. |
| Resumo diário | Opcional. Veja Resumo diário. |
Você pode adicionar quantos espaços precisar, cada um com seus filtros, eventos, estilo e idioma. A mesma atualização do Jira pode ir para vários espaços.
4. Escolher o que notificar
| Opção | Notifica quando | Padrão |
|---|---|---|
| Um item é criado | Um novo item é criado. | ✓ |
| O status muda | O item passa para outro status. | ✓ |
| O responsável muda | O item é atribuído, reatribuído ou fica sem responsável. | ✓ |
| Há um novo comentário | Um novo comentário é publicado. Editar um comentário não notifica. | ✓ |
| Um item é resolvido | Uma resolução é definida. Reabrir (limpar a resolução) não conta. | ✓ |
| A prioridade muda | A prioridade muda. | |
| Outros campos mudam | Qualquer outro campo muda: resumo, descrição, etiquetas, data de vencimento, campos personalizados… Os campos internos do Jira (Rank, registro de tempo e similares) são ignorados. | |
| Um item é excluído | Um item é excluído. Veja Itens excluídos. |
Escolha pelo menos um evento, ou ative o resumo diário. Quando uma única edição muda várias coisas (por exemplo status e responsável), o espaço recebe uma mensagem: o título mostra a mudança mais importante e o cartão mostra as demais.
5. Filtrar por projeto e JQL
Projetos limita o espaço a um ou mais projetos. Filtro JQL extra adiciona qualquer condição JQL. Os dois são combinados com AND:
project in ("WEB", "API") AND (seu JQL)
Alguns filtros úteis:
labels = backend
priority in (High, Highest)
issuetype = Bug AND component = "Pagamentos"
assignee in membersOf("time-suporte")
- O JQL é validado ao salvar; se o Jira o rejeitar, o erro aparece abaixo do campo. Dica: teste a consulta antes na busca de itens do Jira.
- Quando chega uma atualização, é o próprio Jira que verifica se o item atende ao filtro, como ficou depois da mudança.
- O resumo diário usa os mesmos projetos e JQL.
6. Só certas mudanças de status
Com O status muda marcado, você pode preencher Só mudanças de status para com status do seu Jira, por exemplo Done e Em revisão. Assim só as transições para esses status notificam; as outras são ignoradas. Deixe vazio para receber todas as mudanças de status.
Se a mesma edição também mudar outra coisa que o espaço acompanha (por exemplo o responsável), a mensagem é enviada mesmo assim, com essa outra mudança como título.
7. Cartão ou compacto
- Cartão com detalhes: um cabeçalho com a chave, o resumo e o projeto; linhas de Status (com “de → para” quando mudou), Responsável e Prioridade; até quatro outros campos alterados com o novo valor; o texto do comentário (primeiros 600 caracteres, com as menções como nomes); e um botão Abrir no Jira que leva ao item ou ao comentário.
- Compacto (uma linha): chave, resumo, o que mudou, um trecho curto do comentário (200 caracteres) e um link. Bom para espaços movimentados.
8. Tópicos
Com Agrupar as atualizações de um item no mesmo tópico ativado, a primeira mensagem sobre um item abre um tópico e as atualizações seguintes desse item respondem nele. Se o Google Chat não encontrar o tópico, abre um novo. Desativado, cada atualização é uma mensagem separada. O resumo diário e as mensagens de teste nunca vão para os tópicos dos itens.
9. Idioma das mensagens
Cada espaço escolhe inglês, espanhol ou português para os textos do app (títulos, rótulos, botões). O conteúdo do item, como resumo, comentários e nomes de status, fica como está no Jira. As páginas de configuração seguem o idioma do Jira de cada usuário (inglês, espanhol ou português; nos demais idiomas aparecem em inglês).
10. Resumo diário
- Ative Resumo diário e escolha a hora, o fuso horário (por padrão, o do seu navegador) e os dias (por padrão, de segunda a sexta).
- O resumo pega os 50 itens atualizados mais recentemente nas últimas 24 horas que atendem aos projetos e ao JQL do espaço, conta-os por status e lista os 10 mais recentes com links, além de um botão Ver tudo no Jira. Se mais de 50 mudaram, o subtítulo mostra “50+” e as contagens cobrem só esses 50; o botão abre a lista completa no Jira.
- O app verifica a cada hora: o resumo chega durante a hora escolhida, ou até 2 horas depois se uma verificação falhou. Nunca mais de um por dia.
- Se nada mudou, chega uma linha: “Nenhum item foi atualizado nas últimas 24 h.”
- Um espaço pode receber só o resumo: desmarque todos os eventos e deixe o resumo ativado.
11. Notificações pessoais
Qualquer usuário do Jira pode receber notificações do próprio trabalho em um espaço do Google Chat só seu, sem administrador.
- No Google Chat, crie um espaço só para você e adicione um webhook nele (veja o passo 2).
- No Jira, abra sua foto do perfil (o menu de perfil na barra superior) e escolha Sago Alerts — Google Chat.
- Cole o link do webhook e escolha seus motivos (tabela abaixo).
- Clique em Enviar teste e depois em Salvar. Na primeira vez, o Jira pede que você permita que o app verifique suas permissões: aceite. Antes de cada notificação pessoal o app pergunta ao Jira, como você, se você pode ver o item (e o comentário). Sem essa verificação nada é enviado.
| Motivo | Você é notificado quando | Padrão |
|---|---|---|
| Um item é atribuído a mim | Alguém atribui um item a você, ou o cria já atribuído a você. | ✓ |
| Alguém me menciona | Você é @mencionado em um item ou em um comentário. | ✓ |
| Meus itens mudam de status ou recebem comentários | Um item atribuído a você tem uma mudança importante: status, comentário, resolução, prioridade ou responsável. | ✓ |
| Itens que relatei mudam | As mesmas mudanças importantes, em itens que você relatou. | |
| Itens que observo mudam | As mesmas mudanças importantes, em itens que você observa. |
- Ignorar minhas próprias mudanças (ativado por padrão) ignora o que você mesmo mudou.
- Você recebe uma única mensagem por atualização mesmo que vários motivos se apliquem; o subtítulo do cartão diz por quê (por exemplo “Atribuído a você”).
- As mensagens vão só para o espaço cujo webhook você colou. Use um espaço privado: se colar o webhook de um espaço compartilhado, todos os membros vão ler suas notificações.
- Desativar exclui sua assinatura e o link do seu webhook do app. Funciona também quando a licença do app não está ativa.
- Contas desativadas no Jira não recebem notificações pessoais. Quando uma conta Atlassian é encerrada ou excluída, o app remove a assinatura dessa pessoa na verificação semanal seguinte. Administradores não podem excluir pelo app a assinatura de outra pessoa; desinstalar o app remove todas.
- As notificações pessoais não incluem itens excluídos.
12. Comentários restritos e notas internas
Comentários restritos a um grupo ou a uma função do projeto e notas internas do Jira Service Management são tratados com cuidado:
- Os espaços nunca recebem nada sobre eles, porque no espaço do Google Chat pode haver pessoas sem permissão para vê-los.
- Comentários restritos a um grupo ou função normalmente nem chegam ao app: a Atlassian não envia aos apps os eventos de comentários que eles não podem ver. Na prática você não recebe nenhuma notificação por eles, nem pessoal.
- As notas internas dos projetos de serviço chegam ao app. Nesse caso a notificação pessoal diz só “… adicionou um comentário restrito (abra no Jira)”, sem o texto, e só se o Jira confirmar que você pode ver essa nota.
- @menções dentro de um comentário restrito não geram “mencionou você”.
13. Itens excluídos
Depois que um item é excluído, o Jira não consegue mais verificá-lo com JQL, então:
- Espaços sem filtros recebem a exclusão.
- Espaços filtrados só por projeto a recebem se o item era de um desses projetos.
- Espaços com filtro JQL extra não recebem exclusões. A página de configuração avisa sobre isso.
14. Pausar, editar ou excluir um espaço
- Chave Ativo na lista: pausa o espaço e mantém as configurações.
- Editar: mude o que quiser. Deixe o campo do webhook vazio para manter o link salvo, ou cole um novo para substituí-lo.
- Enviar teste: verifica se o webhook salvo continua funcionando.
- Excluir: remove do armazenamento do app as configurações do espaço e o link do seu webhook. Funciona também quando a licença não está ativa. As mensagens já publicadas no Google Chat continuam lá.
15. Teste e licença
- O app é vendido pelo Atlassian Marketplace: grátis para sites com até 10 usuários e pago por usuário acima disso, com 30 dias de teste grátis. A Atlassian cuida de cotações, cobrança e notas fiscais.
- Se a licença não estiver ativa (o teste terminou ou a assinatura foi cancelada), o app para de enviar notificações e resumos, e as páginas de configuração mostram um aviso. As configurações são mantidas enquanto o app estiver instalado e as notificações voltam quando a licença for reativada. As atualizações feitas nesse meio-tempo não são enviadas depois.
- Enquanto a licença não estiver ativa, você ainda pode excluir espaços (página de administração) e desativar as notificações pessoais (página pessoal).
- Se você desinstalar o app, a Atlassian guarda os dados armazenados por até 28 dias e depois os exclui definitivamente. Reinstalar não recupera as configurações anteriores e não oferecemos recuperação de dados, então anote suas configurações antes se pensa em voltar. Veja a política de privacidade.
16. Limitações conhecidas
- Atraso. A Atlassian entrega os eventos do Jira aos apps de forma assíncrona. A maioria chega em segundos, mas a Atlassian documenta que podem levar até cerca de 3 minutos, e mais durante incidentes da plataforma (veja a página de status do Atlassian Developer).
- Cotas e limites do Atlassian Forge. O app roda no Atlassian Forge e está sujeito às cotas e limites da plataforma: quanto tempo cada função pode rodar, quantas invocações e chamadas à API do Jira um app pode fazer e quanto pode guardar e ler. Se um limite for atingido, notificações ou resumos podem atrasar ou não ser enviados, e a Atlassian pode suspender temporariamente um app que os exceda. A Atlassian os publica em Forge platform quotas and limits.
- Limite do Google Chat. O Google aceita cerca de 1 mensagem por segundo por espaço, compartilhada entre todos os webhooks desse espaço. O app tenta de novo (até 4 tentativas em cerca de 20 segundos), mas em edições em massa de muitos itens algumas mensagens ainda podem se perder. Para projetos movimentados, use filtros, um espaço separado ou o resumo diário.
- Comentários editados. Editar um comentário não notifica, então quem for @mencionado pela primeira vez em um comentário editado não é notificado.
- Nomes de status. Os nomes de status, resolução e prioridade vêm do histórico de mudanças do Jira e podem aparecer no idioma padrão do site do Jira, não no de cada usuário.
- Mão única. As notificações vão do Jira para o Google Chat. Não é possível responder ao Jira nem criar itens pelo Google Chat.
- Formato fixo. As mensagens são ajustadas por estilo, tópicos e idioma, não por modelos.
- Tamanhos. Os trechos de comentários vão até 600 caracteres (200 no compacto) e os resumos até 180.
- Tamanho do resumo diário. As contagens por status cobrem no máximo os 50 itens atualizados mais recentemente; acima disso o resumo mostra “50+”.
- Comentários restritos. Comentários restritos a um grupo ou função normalmente nunca chegam ao app, então não geram notificações.
- Licença inativa. As atualizações feitas com a licença inativa não são enviadas depois.
- Verificação pessoal. Se você remover o acesso do app nas configurações da sua conta Atlassian, as notificações pessoais param até você salvar sua página pessoal de novo.
17. Solução de problemas
“Essa não é uma URL de webhook do Google Chat”
O link precisa começar com https://chat.googleapis.com/v1/spaces/ e conter key= e token=. Copie de novo com Mais (⋮) → Copiar link no Google Chat.
O teste falha com “Google Chat HTTP …”
- 404: o webhook ou o espaço foi excluído. Crie um webhook novo e cole.
- 403: o Google recusou a mensagem, geralmente porque os webhooks foram desativados na sua organização ou o webhook foi removido.
- 400: o link está danificado. Copie de novo.
- 429: mensagens demais para esse espaço agora. Espere um minuto e tente de novo.
O teste funciona mas as atualizações não chegam
- Confira se o espaço está Ativo, se o projeto do item está selecionado (ou a lista vazia) e se o item atende ao JQL depois da mudança.
- Confira se o evento está marcado e, para mudanças de status, a lista Só mudanças de status para.
- Comentários restritos nunca chegam aos espaços, e espaços com JQL não recebem exclusões.
- Confira se a licença do app está ativa (se não estiver, a página de configuração avisa).
- Espere até 3 minutos: a Atlassian pode entregar o evento com atraso.
As notificações pessoais não chegam
- Salve a página pessoal de novo e aceite a permissão se o Jira pedir.
- Ignorar minhas próprias mudanças oculta o que você mesmo mudou.
- Você só recebe atualizações de itens (e comentários) que pode ver no Jira.
- Comentários restritos a um grupo ou função normalmente nunca chegam ao app, então não geram notificações.
O resumo diário não chega
Confira a hora, o fuso horário e os dias. O resumo é enviado durante a hora escolhida ou até 2 horas depois.
Ainda não resolveu? Veja Suporte.