Como criar um app para Zendesk: guia passo a passo

Um app para Zendesk é, na prática, uma pequena aplicação web que roda dentro de um iframe no workspace do agente e conversa com o Zendesk por meio do Zendesk Apps Framework (ZAF). Com ele você mostra dados de outros sistemas dentro do ticket, dispara ações e automatiza tarefas repetitivas.

1. Comece pelo problema do agente

Antes de abrir o editor, responda: qual informação o agente procura fora do Zendesk, todo dia? Pedido, contrato, status de cobrança, histórico de atendimento? Essa resposta define o local do app, os dados que ele busca e as ações que oferece. Apps que tentam fazer tudo ficam pesados e acabam ignorados.

2. Instale o ZCLI e gere o esqueleto

O ZCLI é a ferramenta de linha de comando oficial do Zendesk para criar, testar e publicar apps. Você precisa do Node.js instalado.

npm install @zendesk/zcli -g
zcli login -i
zcli apps:new

O comando apps:new pergunta o nome do app e o autor e gera os arquivos iniciais. Você pode escolher o scaffold basic ou react, conforme a sua preferência de front-end.

3. Escolha onde o app aparece

O arquivo manifest.json declara onde o app vive. Para um app na barra lateral do ticket:

{
  "location": {
    "support": {
      "ticket_sidebar": "assets/start.html"
    }
  }
}

Outros locais comuns no Zendesk Support são top_bar, nav_bar, modal e background (sem interface, só lógica). Veja como cada um se encaixa no workspace na seção “Onde seu app vive”.

4. Leia o contexto do ticket e chame uma API

O app usa o cliente do ZAF para ler dados da tela (client.get), ajustar o tamanho do iframe (client.invoke) e fazer requisições (client.request).

const client = ZAFClient.init()
client.invoke('resize', { width: '100%', height: '220px' })

const data = await client.get('ticket.requester.email')
const email = data['ticket.requester.email']

const res = await client.request({
  url: `/api/v2/users/search.json?query=${encodeURIComponent(email)}`,
  type: 'GET'
})
console.log(res.users)

Chamadas para /api/v2/... usam a API do próprio Zendesk com a sessão do agente. Para sistemas externos, veja o guia de integração com ERP.

5. Teste localmente

Dentro da pasta do app, rode o servidor local e abra o seu Zendesk com o parâmetro ?zcli_apps=true no final do endereço:

zcli apps:server .

6. Instale como app privado

Com o app funcionando, instale na sua conta:

zcli apps:create .     # empacota e instala como app privado
zcli apps:update .     # envia novas versões depois

Se preferir, zcli apps:package gera o arquivo .zip para enviar pelo painel de administração. Para publicar no Marketplace, o app passa por revisão e precisa atender aos requisitos do Zendesk; consulte sempre a documentação oficial para a versão atual.

Erros comuns que vemos em projetos

• Segredo no front-end: tokens e senhas escritos no JavaScript do app ficam visíveis a qualquer pessoa com acesso. Use secure settings.
• App pesado: bibliotecas grandes demais atrasam o workspace do agente. Carregue só o necessário.
• Esquecer o redimensionamento: sem resize, o iframe fica cortado ou com barra de rolagem.
• Sem estados de erro: API fora do ar precisa mostrar mensagem clara e opção de tentar de novo, não uma tela em branco.
• Ignorar acessibilidade: o agente usa o app o dia todo; contraste e navegação por teclado importam.