zendesk-app-location-sidebar-ticket

{
  "title": "Como criar um aplicativo de barra lateral de tickets do Zendesk: Um guia completo para desenvolvedores",
  "slug": "zendesk-app-location-sidebar-ticket",
  "locale": "pt",
  "date": "2026-03-02",
  "updated": "2026-03-02",
  "template": "default",
  "excerpt": "Um guia passo a passo para desenvolvedores sobre como criar aplicativos para a barra lateral de tickets do Zendesk, desde a configuração do manifesto até o trabalho com dados de tickets por meio do Zendesk Apps Framework.",
  "categories": [
    "Guides",
    "Zendesk"
  ],
  "tags": [
    "Zendesk",
    "App Development",
    "Ticket Sidebar",
    "ZAF",
    "Developer Guide"
  ],
  "readTime": 8,
  "author": 16,
  "reviewer": 14,
  "seo": {
    "title": "Como criar um aplicativo de barra lateral de tickets do Zendesk: Um guia completo para desenvolvedores",
    "description": "Um guia passo a passo para desenvolvedores sobre como criar aplicativos para a barra lateral de tickets do Zendesk, desde a configuração do manifesto até o trabalho com dados de tickets por meio do Zendesk Apps Framework.",
    "image": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-23678d8a-12b3-4be7-b973-433f05e21354"
  },
  "coverImage": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-23678d8a-12b3-4be7-b973-433f05e21354",
  "coverImageAlt": "Imagem do banner para Como criar um aplicativo de barra lateral de tickets do Zendesk: Um guia completo para desenvolvedores",
  "coverImageWidth": 1920,
  "coverImageHeight": 1080,
  "faqs": {
    "heading": "Perguntas Frequentes",
    "type": "blog",
    "answerType": "html",
    "faqs": [
      {
        "question": "Qual é a diferença entre ticket_sidebar e new_ticket_sidebar em um local de aplicativo Zendesk?",
        "answer": "O local ticket_sidebar exibe seu aplicativo ao visualizar tickets existentes, enquanto new_ticket_sidebar aparece quando os agentes estão criando novos tickets antes do envio. Depois que um ticket é criado, ele se move para a barra lateral de tickets padrão. Você pode configurar ambos os locais em seu manifesto se seu aplicativo precisar funcionar durante a criação e após a criação do ticket."
      },
      {
        "question": "Posso usar o local da barra lateral de tickets do aplicativo Zendesk para aplicativos que precisam modificar os dados do ticket?",
        "answer": "Sim, o local da barra lateral de tickets oferece suporte para leitura e gravação de dados de tickets. Você pode usar os métodos do cliente ZAF para atualizar as propriedades do ticket, adicionar comentários ou modificar campos personalizados. No entanto, tenha cuidado com as permissões. Seu aplicativo só pode executar ações que o agente autenticado tem permissão para fazer."
      },
      {
        "question": "Como lidar com diferentes larguras de barra lateral ao criar um aplicativo de barra lateral de tickets do Zendesk?",
        "answer": "Defina flexible: true em seu manifest.json para ativar o redimensionamento responsivo. Em seguida, use consultas de mídia CSS ou uma estrutura responsiva como Tailwind CSS para adaptar seu layout. Projete para uma largura mínima de 200px e dimensione gradualmente. Considere quais informações são essenciais em larguras estreitas versus o que você pode revelar quando os agentes expandem a barra lateral."
      },
      {
        "question": "Quais APIs estão disponíveis especificamente para o local da barra lateral de tickets do Zendesk?",
        "answer": "A barra lateral de tickets fornece acesso ao objeto Ticket (status, prioridade, campos personalizados), objetos User (solicitante, usuário atual), objetos Comment, dados da Brand e informações da Organization. Você também pode se inscrever em eventos em tempo real, como ticket.status.changed para responder a atualizações à medida que elas acontecem."
      },
      {
        "question": "Preciso de permissões especiais para instalar um aplicativo de barra lateral de tickets de local de aplicativo Zendesk personalizado?",
        "answer": "Para carregar e instalar aplicativos privados, você precisa de acesso de administrador à sua instância do Zendesk. Para desenvolvimento e teste com ZCLI, você só precisa de uma conta Zendesk com níveis de plano apropriados (Suite Growth+ ou Support Professional+). Se você planeja publicar no Zendesk Marketplace, seu aplicativo passa por um processo de revisão."
      },
      {
        "question": "Posso criar um aplicativo de barra lateral de tickets do Zendesk que se integra a sistemas externos como plataformas de CRM ou e-commerce?",
        "answer": "Absolutamente. Este é um dos casos de uso mais comuns para aplicativos de barra lateral. Você pode fazer chamadas de API para serviços externos do iframe do seu aplicativo, exibir os dados na barra lateral e até mesmo permitir que os agentes tomem medidas nesses sistemas sem sair do Zendesk. Apenas certifique-se de lidar com a autenticação de forma segura e construir o tratamento de erros para quando as APIs externas não estiverem disponíveis."
      }
    ],
    "supportLink": null
  }
}
---

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.

![A barra lateral de tickets agrega dados do Shopify e Jira, ajudando os agentes a resolver problemas complexos sem sair do espaço de trabalho do Zendesk.](https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/c7e37104-cd48-4c25-9bd1-8f631292402e)

## 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:

```bash
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 local
• assets/iframe.html: O conteúdo HTML exibido na barra lateral
• assets/logo.png: O ícone do seu aplicativo
• translations/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 como true para comportamento responsivo ou false para 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:

1. Abra uma janela anônima ou privada do navegador (isso evita problemas de cache)
2. Faça login no Zendesk e abra qualquer ticket
3. Anexe ?zcli_apps=true ao URL
4. 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.