Jira

Esta página é para quem já usa Jira como sistema de trabalho do time técnico. Com ele conectado, o agente de atendimento pode abrir item no Jira durante a conversa, e os chamados do ChatMade escalam sozinhos acima de uma prioridade que você define.

O que você precisa antes

• Um site Jira Cloud.
• Um aplicativo OAuth 2.0 (3LO) criado em developer.atlassian.com.
• Numa instalação própria, três variáveis no .env do backend: JIRA_CLIENT_ID, JIRA_CLIENT_SECRET e JIRA_REDIRECT_URI.
• Um administrador do ChatMade com a permissão manage_organization.

Atenção: o Jira é a única integração cuja URL de retorno não é derivada do BACKEND_URL — você a escreve na variável JIRA_REDIRECT_URI e ela precisa bater exatamente com a que você cadastrou no aplicativo da Atlassian. O caminho é {seu-backend}/api/v1/jira/callback. Uma barra a mais e a autorização falha.

Você não cola client id nem client secret no painel. O aplicativo é do servidor.

Conectar

1. No painel, abra Settings → Integrations (“Configurações → Integrações”).
2. Ache o cartão Jira, com a legenda PROJECT MANAGEMENT e a descrição “Connect to Jira to create issues directly from ChatterMate.”
3. Clique em Connect (“Conectar”). O navegador vai para a autorização da Atlassian.
4. Autorize.

Você volta para as integrações. O cartão passa a mostrar Connected (“Conectado”), os botões Manage (“Gerenciar”) e Disconnect (“Desconectar”), e o link ↗ Visit Jira Site (“Visitar o site do Jira”).

Bom saber: você não escolhe o site do Jira. O ChatMade pega o primeiro site acessível pela autorização e guarda esse. É um site Jira por organização. Se a sua conta administra vários, confirme que a autorização foi dada no site certo.

Apontar o projeto — por agente

Conectar não basta. O projeto e o tipo de item são escolhidos em cada agente, não na organização.

1. Main Menu → AI Agents (“Menu principal → Agentes de IA”), abra o agente.
2. Aba Integrations (“Integrações”), seção Jira — auto-ticketing (“Jira — abertura automática”), com a linha “Create Jira tickets for issues that need follow-up.”
3. Ligue o interruptor Create Jira Tickets (“Criar chamados no Jira”).
4. Com o Jira conectado, aparecem dois seletores: Jira Project (“Projeto do Jira”) e Issue Type (“Tipo de item”).
5. Salve.

Se o Jira ainda não estiver conectado, a seção mostra “Jira is not connected” e um botão Connect Jira (“Conectar o Jira”).

O que o agente pode fazer no Jira

Três ferramentas, e só três:

Abrir um item. O agente cria um item com resumo, descrição e prioridade. As prioridades aceitas são Highest, High, Medium, Low e Lowest — e Medium é o padrão. Se o projeto ou o tipo de item escolhido não tiver campo de prioridade, o campo é omitido.

Consultar o estado de um item. O agente lê o estado atual, por chave do item ou, sem chave, o item ligado àquela conversa.

Conferir se já existe. Antes de abrir, o agente verifica se aquela conversa já gerou um item.

Essa terceira ferramenta importa: se já existir um item para a conversa, o agente não abre um segundo. Ele atualiza a descrição do item existente, acrescentando o que há de novo sob um separador com data e hora. Uma conversa vira um item, não uma pilha deles.

Atenção: as ferramentas do Jira e as de chamado nativo do ChatMade são mutuamente exclusivas. Se o agente tem o Jira configurado, ele usa o Jira; se não tem, usa os chamados nativos. Nunca as duas — duas funções de “abrir chamado” confundiriam o modelo. Isso é decidido no código, não na tela.

Escalonamento automático dos chamados nativos

Independente do que o agente faz na conversa, os chamados nativos do ChatMade podem abrir item no Jira automaticamente.

1. Vá em Settings → Ticketing (“Configurações → Chamados”).
2. Ache a seção Jira escalation (“Escalonamento para o Jira”) e marque Enabled (“Ativo”). Vem desmarcado.
3. Escolha em Escalate tickets with priority (“Escalar chamados com prioridade”) o mínimo. As opções aparecem como Urgent or higher, High or higher, Medium or higher e Low or higher.

A própria tela explica a regra:

One-way sync: tickets at or above the chosen priority also open a Jira issue (using your connected Jira and the agent’s project). ChatterMate stays the source of truth.

O item criado no Jira recebe o resumo [TKT-n] {título do chamado} e uma descrição com prioridade, severidade, resumo da IA e a descrição original. O chamado no ChatMade ganha uma atividade Escalated to Jira as {chave} e o painel lateral passa a mostrar o cartão External reference (“Referência externa”) com o link.

O escalonamento é disparado quando o chamado é atualizado — uma mudança de prioridade, por exemplo. E falha em silêncio: se o Jira estiver fora do ar, o chamado continua funcionando normalmente e o erro vai só para o log.

Bom saber: a palavra “higher” no seletor confunde. Urgent or higher significa “só os urgentes”; Low or higher significa “todos”. Pense em “desta prioridade para cima, em gravidade”.

Só de ida

O escalonamento é de mão única, e isso está escrito em três lugares no código.

• O chamado do ChatMade abre um item no Jira.
• Nada volta. Fechar o item no Jira não fecha o chamado no ChatMade. Mudar o estado, a prioridade, o responsável ou o comentário no Jira não reflete em lugar nenhum.
• Um chamado já escalado nunca é escalado de novo — não existe re-sincronização.
• Não há webhook de entrada do Jira. O estado do item só é lido quando o agente pergunta, na hora.

Isso é decisão de projeto, não limitação temporária: o ChatMade continua sendo a fonte da verdade dos chamados dele.

Limites

• Um site Jira por organização.
• O resumo do item escalado é cortado em 250 caracteres.
• A descrição é cortada em 4.000 caracteres.
• A API usada é a /rest/api/3/ do Jira Cloud.

Desconectar

Botão Disconnect (“Desconectar”) no cartão de integrações.

Próximo passo

Se você vende no Shopify, veja Shopify — mas leia o aviso do começo daquela página antes.