Como criar um aplicativo de barra lateral de tickets do Zendesk: Um guia completo para desenvolvedores
Stevia Putri
Última edição March 2, 2026
Imagine um agente de suporte trabalhando em um ticket complexo. Ele precisa verificar o histórico de pedidos do cliente, procurar seu registro de CRM e pesquisar na base de conhecimento. Sem sair do Zendesk. É exatamente isso que um aplicativo de barra lateral de tickets faz. Ele traz dados e ferramentas externas diretamente para o espaço de trabalho do agente, economizando tempo e reduzindo a troca de contexto.
A barra lateral de tickets é um dos locais mais poderosos para aplicativos Zendesk. Ela fica na bandeja de aplicativos no lado direito de cada ticket, dando aos agentes acesso instantâneo a informações contextuais. Se você estiver criando uma integração para sua equipe ou planejando publicar no Zendesk Marketplace, este guia o guiará na criação de um aplicativo de barra lateral de tickets do zero.
O que você vai precisar
Antes de começar a construir, certifique-se de ter estes pré-requisitos prontos:
- Uma conta Zendesk com o plano Suite Growth ou superior, ou o plano Support Professional ou superior. Você pode obter uma conta de avaliação gratuita para desenvolvimento, se necessário.
- Node.js 14.17.3 ou posterior instalado em sua máquina
- A Interface de Linha de Comando do Zendesk (ZCLI) para construir e testar aplicativos localmente
- Um navegador da web que permita conteúdo misto HTTP e HTTPS, como Chrome ou Firefox. O Safari não funcionará para desenvolvimento local porque não oferece suporte a conteúdo misto.
- Familiaridade básica com HTML, CSS e JavaScript
Passo 1: Configure seu ambiente de desenvolvimento
Primeiro, você precisará instalar o ZCLI e criar a estrutura do seu aplicativo. O ZCLI é a ferramenta de linha de comando oficial do Zendesk que lida com tudo, desde a criação de novos aplicativos até o empacotamento para implantação.
Para instalar o ZCLI globalmente, execute:
npm install -g @zendesk/zcli
Uma vez instalado, crie um novo aplicativo executando:
zcli apps:new
Você será solicitado a fornecer alguns detalhes:
- Nome do diretório: Isso cria a pasta para os arquivos do seu aplicativo
- Nome e e-mail do autor: Para o manifesto do aplicativo
- Nome do aplicativo: O nome de exibição do seu aplicativo
O ZCLI gera um modelo inicial com os arquivos essenciais:
manifest.json: Define a configuração do seu aplicativo, incluindo o localassets/iframe.html: O conteúdo HTML exibido na barra lateralassets/logo.png: O ícone do seu aplicativotranslations/en.json: Para internacionalização
Passo 2: Configure o local da barra lateral de tickets
O coração da configuração do seu aplicativo reside em manifest.json. Este arquivo diz ao Zendesk onde seu aplicativo deve aparecer e qual conteúdo carregar.
Para um aplicativo de barra lateral de tickets, seu manifesto precisa de uma propriedade location que especifique a chave ticket_sidebar:
{
"name": "Meu Aplicativo da Barra Lateral",
"author": {
"name": "Seu Nome",
"email": "voce@exemplo.com"
},
"defaultLocale": "en",
"private": true,
"location": {
"support": {
"ticket_sidebar": {
"url": "assets/iframe.html",
"flexible": true
}
}
},
"version": "1.0.0"
}
Vamos detalhar as propriedades principais:
url: Aponta para o arquivo HTML que carrega no iframe da barra lateral. É aqui que a interface do usuário do seu aplicativo reside.flexible: Controla se o iframe redimensiona com a bandeja de aplicativos. Defina comotruepara comportamento responsivo oufalsepara bloquear a largura em 320px.
Há também um local new_ticket_sidebar para aplicativos que devem aparecer quando os agentes estão criando novos tickets, antes de serem enviados. Depois que um ticket é criado, ele se move para o local padrão ticket_sidebar.
Passo 3: Acesse os dados do ticket com as APIs ZAF
Agora a parte interessante: fazer com que seu aplicativo realmente faça algo. O Zendesk Apps Framework (ZAF) fornece um SDK JavaScript que permite que seu aplicativo interaja com dados de tickets, informações do usuário e a interface do Zendesk.
Primeiro, inclua o SDK ZAF em seu iframe.html:
<script src="https://static.zdassets.com/zendesk_app_framework_sdk/2.0/zaf_sdk.min.js"></script>
Em seguida, inicialize o cliente e comece a buscar dados:
var client = ZAFClient.init();
// Obtenha o assunto e o status do ticket atual
client.get('ticket.subject').then(function(data) {
console.log('Assunto do ticket:', data['ticket.subject']);
});
// Busque várias propriedades de uma vez
client.get(['ticket.subject', 'ticket.status', 'ticket.priority']).then(function(data) {
console.log('Informações do ticket:', data);
});
O local da barra lateral de tickets oferece acesso a objetos de dados ricos:
- Objeto Ticket: status, prioridade, assunto, descrição, campos personalizados, tags
- Objetos User: detalhes do solicitante, usuário atual, colaboradores
- Objetos Comment: comentários e anexos do ticket
- Dados da marca e da organização: contexto sobre a conta
Você também pode ouvir as mudanças em tempo real. Se um agente atualizar o status do ticket ou o responsável, seu aplicativo poderá responder imediatamente:
client.on('ticket.status.changed', function() {
console.log('O status do ticket foi atualizado');
// Atualize os dados ou a interface do usuário do seu aplicativo
});
Passo 4: Projete para layouts responsivos
Aqui está algo que muitos desenvolvedores perdem: a largura da barra lateral de tickets não é mais fixa. Com o Agent Workspace, os agentes podem redimensionar a bandeja de aplicativos de 200px a essencialmente largura ilimitada. Seu aplicativo precisa lidar com isso de forma elegante.
Se você definir flexible: true em seu manifesto, o iframe será redimensionado automaticamente. Mas seu CSS precisa responder também. Considere usar uma estrutura responsiva como Tailwind CSS ou escrever consultas de mídia que adaptem seu layout:
/* Estilos padrão para barra lateral estreita */
.app-container {
padding: 12px;
font-size: 14px;
}
/* Barra lateral mais larga - mostre mais detalhes */
@media (min-width: 400px) {
.app-container {
padding: 16px;
}
.detail-view {
display: block;
}
}
Pense no foco do agente. Quando a barra lateral é estreita, eles provavelmente estão se concentrando na conversa. Mostre apenas informações essenciais. Quando eles expandem a bandeja, provavelmente estão tentando concluir uma tarefa em seu aplicativo. É quando você pode revelar mais funcionalidades.
Passo 5: Teste e implante seu aplicativo
Com seu aplicativo construído, é hora de testá-lo localmente antes de implantar. O ZCLI inclui um servidor local que permite que você execute seu aplicativo em seu ambiente Zendesk real.
Inicie o servidor de desenvolvimento:
zcli apps:server
Isso inicia um servidor web local para seu aplicativo. Para vê-lo em ação:
- Abra uma janela anônima ou privada do navegador (isso evita problemas de cache)
- Faça login no Zendesk e abra qualquer ticket
- Anexe
?zcli_apps=trueao URL - Seu aplicativo aparece na bandeja de aplicativos
Faça alterações em seu código, salve e atualize a página para ver as atualizações instantaneamente.
Quando estiver pronto para implantar, empacote seu aplicativo:
zcli apps:package
Isso cria um arquivo ZIP que você pode carregar diretamente em sua instância do Zendesk para uso privado ou enviar para o Zendesk Marketplace se quiser compartilhá-lo com outras organizações.
Casos de uso comuns para aplicativos de barra lateral de tickets
Agora que você entende a mecânica, o que você deve construir? Aqui estão alguns padrões que funcionam bem na barra lateral de tickets:
- Pesquisas de dados do cliente: Extraia o histórico de pedidos do Shopify, detalhes da conta do Salesforce ou status da assinatura do seu sistema de cobrança. Os agentes veem tudo sem trocar de guias.
- Fluxos de trabalho entre plataformas: Crie problemas do Jira, adicione cartões do Trello ou registre bugs no GitHub diretamente de um ticket. O aplicativo pré-preenche os dados do ticket do Zendesk para economizar tempo.
- Assistência de conhecimento: Pesquise sua central de ajuda, wiki interna ou tickets anteriores para encontrar soluções relevantes. Alguns aplicativos usam IA para sugerir respostas com base no conteúdo do ticket.
- Suporte alimentado por IA: Ferramentas como eesel AI funcionam na barra lateral para redigir respostas, revelar conhecimento relevante de várias fontes e ajudar os agentes a resolver tickets mais rapidamente.
A chave é o contexto. Os melhores aplicativos de barra lateral mostram automaticamente informações relevantes para o ticket específico e o cliente que o agente está visualizando.
Dicas e práticas recomendadas
Antes de terminar seu aplicativo, tenha estas diretrizes em mente:
- Mantenha-o leve: Os aplicativos da barra lateral carregam em todos os tickets. Bibliotecas JavaScript pesadas ou ativos grandes diminuem a experiência do agente.
- Lide com erros com elegância: APIs externas falham. As conexões de rede caem. Crie o tratamento de erros para que seu aplicativo falhe silenciosamente em vez de interromper o fluxo de trabalho do agente.
- Use o Zendesk Garden: O sistema de design do Zendesk fornece componentes que correspondem à interface nativa. Isso faz com que seu aplicativo pareça parte do Zendesk, não um elemento estranho.
- Proteja suas chaves de API: Nunca codifique credenciais em seu aplicativo. Use as configurações seguras do Zendesk ou o OAuth para autenticação.
- Teste com dados reais: Um aplicativo que funciona perfeitamente com tickets de teste pode ter problemas com caracteres incomuns, linhas de assunto longas ou campos personalizados ausentes.
Comece a construir seu aplicativo de barra lateral do Zendesk hoje
Agora você tem tudo o que precisa para construir um aplicativo de barra lateral de tickets. Desde a configuração do seu ambiente de desenvolvimento com o ZCLI até a configuração do manifesto, o acesso aos dados do ticket por meio do ZAF e o design para layouts responsivos, a base está no lugar.
A barra lateral de tickets é uma maneira poderosa de estender os recursos do Zendesk. Se você estiver resolvendo um fluxo de trabalho específico para sua equipe ou construindo algo para a comunidade Zendesk mais ampla, os aplicativos neste local colocam informações e ações exatamente onde os agentes precisam.
Se você deseja adicionar recursos de IA à sua configuração do Zendesk, o eesel AI funciona como um aplicativo de barra lateral que traz conhecimento de sua central de ajuda, tickets anteriores e documentação interna diretamente para o espaço de trabalho do agente. É um bom exemplo do que é possível quando você combina o Zendesk Apps Framework com os recursos modernos de IA.
Pronto para começar? Pegue suas credenciais do Zendesk, instale o ZCLI e construa algo que torne o dia da sua equipe de suporte um pouco mais fácil.
Perguntas Frequentes
Share this article
Article by
Stevia Putri
Stevia Putri is a marketing generalist at eesel AI, where she helps turn powerful AI tools into stories that resonate. She’s driven by curiosity, clarity, and the human side of technology.
