Como corrigir problemas com campos personalizados do Zendesk: Guia completo de solução de problemas

Você passou horas configurando os campos personalizados perfeitos no Zendesk. Você mapeou exatamente quais dados precisa capturar, configurou os tipos de campo e definiu as permissões. Então seus agentes começam a trabalhar e... os campos não estão em lugar nenhum. Ou eles estão visíveis nos tickets, mas faltando em seus relatórios do Explore. Ou sua integração de API está retornando "undefined" para valores que você sabe que existem.

Bem-vindo ao mundo frustrante dos problemas com campos personalizados do Zendesk. Esses problemas são comuns o suficiente para gerar milhares de tickets de suporte e postagens em fóruns, mas as soluções geralmente estão espalhadas por várias páginas de documentação e tópicos da comunidade.

Este guia reúne tudo. Vamos percorrer os problemas mais comuns com campos personalizados, explicar por que eles acontecem e fornecer correções passo a passo que realmente funcionam. Também veremos como as equipes estão reduzindo sua dependência de configurações complexas de campos personalizados usando ferramentas de IA como o eesel AI que aprendem com o contexto em vez de exigir configurações de campo rígidas.

Diagnóstico rápido: Identifique seu problema com campos personalizados do Zendesk

Antes de mergulhar em soluções detalhadas, vamos combinar seus sintomas com a correção certa:

Se o seu problema não estiver nesta tabela, trabalhe nas seções abaixo sistematicamente. A maioria dos problemas com campos personalizados do Zendesk se enquadra em uma dessas quatro categorias.

Problema 1: Campos personalizados não aparecendo nos tickets

Este é o problema mais comum com campos personalizados. Você criou o campo, ele aparece como ativo no Admin Center, mas os agentes não conseguem vê-lo ao visualizar ou criar tickets.

Por que isso acontece

No Zendesk, criar um campo personalizado e torná-lo visível para os agentes são duas etapas separadas. Quando você cria um campo, ele existe em sua conta, mas não aparece automaticamente em nenhum formulário de ticket. Você deve adicioná-lo explicitamente a cada formulário onde deseja que ele seja exibido.

Isso confunde até mesmo administradores experientes porque é contraintuitivo. Outras plataformas geralmente mostram todos os campos ativos automaticamente. A abordagem do Zendesk oferece controle preciso sobre os layouts de formulário, mas cria este obstáculo comum.

Problemas pós-atualização (como os relatados após a atualização de março de 2023) geralmente ocorrem quando o Zendesk altera os comportamentos padrão do formulário ou quando as regras de campo condicionais são redefinidas.

Correção passo a passo

Passo 1: Verifique se o campo está ativo

Navegue até Admin Center > Objetos e regras > Tickets > Campos. Encontre seu campo personalizado e confirme se o status mostra "Ativo". Campos inativos não aparecerão em lugar nenhum, independentemente da configuração do formulário.

Passo 2: Verifique as permissões de visibilidade do campo

Clique nas configurações do campo e revise as opções de visibilidade. Os campos podem ser definidos como visíveis para:

• Apenas agentes
• Apenas usuários finais
• Agentes e usuários finais

Se seus agentes não conseguem ver um campo, certifique-se de que "Visível para agentes" esteja habilitado.

Passo 3: Adicione o campo ao seu formulário de ticket

Este é o passo que a maioria das pessoas perde. Vá para Admin Center > Objetos e regras > Tickets > Formulários. Selecione o formulário que seus agentes usam (geralmente o formulário padrão se você não criou formulários personalizados).

No editor de formulário, você verá os campos disponíveis à esquerda e o layout do formulário atual à direita. Arraste seu campo personalizado da lista disponível para o layout do formulário. Salve o formulário.

Passo 4: Teste com diferentes funções de agente

Se o campo ainda não aparecer, verifique as permissões do agente. Alguns campos personalizados são restritos com base nas funções do agente. Teste primeiro com uma conta de administrador para descartar problemas de permissão e, em seguida, verifique se a função de agente específica tem acesso.

Passo 5: Verifique as regras de campo condicional

Se você usar campos condicionais, seu campo ausente pode estar oculto até que outro campo receba um valor específico. Vá para Admin Center > Objetos e regras > Tickets > Formulários, clique nos três pontos ao lado do seu formulário e selecione "Condições". Revise quaisquer regras que possam estar ocultando seu campo.

Dica de prevenção

Documente quais campos pertencem a quais formulários. Uma planilha simples mapeando campos para formulários evita esse problema e torna a solução de problemas mais rápida quando surgem problemas.

Problema 2: Campos personalizados faltando nos relatórios do Explore

Você tem dados em seus campos personalizados. Você pode vê-los nos tickets. Mas quando você cria relatórios no Zendesk Explore, os campos estão faltando ou não retornando os valores esperados.

Por que isso acontece

Existem três causas comuns para este problema:

1. Atraso na sincronização de dados: Novos campos personalizados levam até uma hora para aparecer no Explore. Isso pega as pessoas desprevenidas que esperam disponibilidade imediata.

2. Conflitos de nomenclatura: Quando vários campos personalizados compartilham o mesmo nome (mesmo que alguns estejam inativos), os atributos calculados com base nos nomes dos campos falham. O Explore não consegue determinar qual campo você quer dizer.

3. Confusão no tipo de campo: Campos personalizados numéricos e decimais são armazenados como métricas, não como atributos. As pessoas os procuram no lugar errado.

Correção passo a passo

Passo 1: Permita o tempo de sincronização para novos campos

Se você criou o campo na última hora, espere. A sincronização de dados do Explore não é instantânea. As alterações nos dados históricos podem demorar ainda mais. Pegue um café e verifique novamente em uma hora.

Passo 2: Verifique se há nomes de campo duplicados

Vá para Admin Center > Objetos e regras > Tickets > Campos e examine sua lista de campos. Procure por quaisquer campos com nomes idênticos, incluindo os inativos. Se você encontrar duplicatas, renomeie-os para serem únicos.

A principal coisa a lembrar é que os atributos calculados no Explore referenciam os campos por nome, não por ID. Quando os nomes colidem, a fórmula não consegue resolver qual campo usar.

Passo 3: Verifique o local correto para campos numéricos

Se você estiver procurando por campos personalizados numéricos ou decimais, verifique em Métricas no seu relatório do Explore, não em Atributos. Esses tipos de campo armazenam valores numéricos que são calculados de forma semelhante às métricas do sistema.

Para convertê-los em atributos para diferentes necessidades de relatório, o Zendesk fornece uma receita: "Explore recipe: Converting between metrics and attributes."

Passo 4: Verifique as permissões do conjunto de dados

Certifique-se de ter acesso aos conjuntos de dados apropriados no Explore. Alguns campos só aparecem em conjuntos de dados específicos (Tickets, Atualizações de tickets, etc.). Verifique com seu administrador do Zendesk se você não tiver certeza sobre o acesso ao conjunto de dados.

Passo 5: Atualize sua conexão do Explore

Às vezes, a solução mais simples funciona. Saia do Explore e faça login novamente. Isso força uma atualização de conexão e pode resolver problemas de visibilidade de campo.

Dica de prevenção

Estabeleça convenções de nomenclatura para campos personalizados. Inclua um código de departamento ou prefixo de categoria (como "BILL_" para campos de faturamento ou "PROD_" para campos de produto) para evitar conflitos de nomenclatura e tornar os campos mais fáceis de encontrar no Explore.

Problema 3: Problemas de extração de campos personalizados da API

Você está construindo uma integração ou extraindo dados via API. Você pode ver os valores dos campos personalizados na interface do Zendesk, mas suas chamadas de API retornam "undefined" ou valores vazios.

Por que isso acontece

Os campos personalizados na API do Zendesk são retornados como uma matriz de objetos, não como propriedades diretas no objeto ticket. Muitos desenvolvedores tentam acessá-los como ticket.custom_field_12345, o que não funciona. Você precisa pesquisar na matriz o campo com o ID correspondente.

A solução

Aqui está o padrão correto para extrair valores de campos personalizados da API do Zendesk:

// Maneira errada - retorna undefined
ticket.custom_fields_6515116803345

// Maneira certa - pesquisa na matriz o ID do campo
ticket.custom_fields[ticket.custom_fields.findIndex((cf) => cf.id==6515116803345)].value

A matriz custom_fields contém objetos com propriedades id e value. Você deve encontrar o índice do objeto com o ID do campo de destino e, em seguida, acessar seu valor.

Dica de prevenção

Use IDs de campo em vez de nomes em chamadas de API. Os IDs de campo são estáveis e exclusivos. Os nomes de campo podem mudar, interrompendo sua integração. Armazene os IDs de campo como constantes em seu código com nomes de variáveis descritivos para que sua integração permaneça legível.

Problema 4: Falhas de mapeamento de campos de integração

Você está tentando sincronizar o Zendesk com outra plataforma (Jira, Power BI, Salesforce) e seus campos personalizados não estão mapeando corretamente ou aparecendo na integração.

Limitações da integração do Jira

O plugin Zendesk para Jira tem limitações conhecidas com a detecção de campos personalizados. De acordo com relatos de usuários na Comunidade Atlassian, o plugin detecta apenas campos do sistema, não todos os campos personalizados criados no Jira.

Se você precisar mapear campos personalizados do Jira para o Zendesk e o plugin padrão não os suportar, considere estas soluções alternativas:

• Use uma ferramenta de integração de terceiros como o Exalate, que lida com o mapeamento de campos personalizados de forma mais robusta
• Crie regras de fluxo de trabalho no Jira que copiem os valores dos campos personalizados para os campos do sistema que o Zendesk pode ver
• Use webhooks para sincronizar valores de campo entre sistemas

Problemas de conexão do Power BI

Ao conectar o Power BI ao Zendesk, os campos personalizados do ticket às vezes não aparecem no modelo de dados. Isso geralmente acontece porque:

• O campo foi criado recentemente e não foi sincronizado com o data warehouse
• O tipo de campo não é suportado pelo conector do Power BI
• As permissões de campo restringem o acesso aos dados

Tente atualizar a conexão no Power BI depois de esperar o período de sincronização de uma hora. Se os campos ainda não aparecerem, verifique se o conector suporta seu tipo de campo específico.

Quando usar ferramentas de terceiros

As integrações nativas funcionam para configurações básicas, mas o mapeamento de campos complexos geralmente requer plataformas de integração dedicadas. Ferramentas como Zapier, Workato ou Exalate fornecem opções de mapeamento de campo mais flexíveis do que as integrações nativas do Zendesk.

Melhores práticas para evitar problemas com campos personalizados

Depois de solucionar centenas de problemas com campos personalizados, os padrões emergem. Aqui estão as práticas que evitam a maioria dos problemas antes que eles comecem:

Convenções de nomenclatura

Estabeleça e aplique convenções de nomenclatura desde o primeiro dia. Boas convenções incluem:

• Prefixos de departamento ou categoria (BILL_, PROD_, TECH_)
• Numeração sequencial para campos relacionados (BILL_REFUND_01, BILL_REFUND_02)
• Evitar nomes genéricos como "Tipo" ou "Status" que podem entrar em conflito com campos do sistema

Estratégias de organização de campo

• Limite o número de campos em qualquer formulário para o que os agentes realmente precisam
• Use campos condicionais para mostrar campos relevantes com base no contexto, em vez de exibir tudo
• Audite regularmente os campos inativos e exclua aqueles que não são mais necessários

Fluxo de trabalho de teste

Nunca implante alterações de campos personalizados diretamente na produção. Teste com:

• Um pequeno grupo de agentes primeiro
• Diferentes funções de agente
• Visualizações de agente e usuário final (se aplicável)
• Relatórios do Explore após o período de sincronização

Considere alternativas de IA

Aqui está algo que vale a pena considerar: muitas equipes criam configurações complexas de campos personalizados para categorizar e encaminhar tickets automaticamente. Eles criam menus suspensos elaborados, campos condicionais e campos obrigatórios para garantir que os tickets cheguem à equipe certa com o contexto certo.

O eesel AI adota uma abordagem diferente. Em vez de exigir que os agentes preencham campos rígidos, nossa IA lê o conteúdo do ticket e categoriza, marca e encaminha automaticamente com base no que o cliente realmente escreveu. Isso elimina muitas das dores de cabeça do gerenciamento de campos, muitas vezes alcançando uma precisão melhor do que a seleção manual de campos.

Para equipes que lutam com a complexidade dos campos personalizados, nosso Agente de IA pode lidar com o suporte de linha de frente sem exigir as configurações de campo elaboradas que causam tantos problemas. E nosso produto AI Triage marca e encaminha automaticamente os tickets com base no conteúdo, reduzindo a dependência de campos personalizados para categorização.

Quando procurar ajuda adicional

Alguns problemas com campos personalizados exigem intervenção do suporte do Zendesk. Entre em contato com o Suporte do Zendesk se:

• Os problemas persistirem além de 24 horas após tentar as soluções acima
• Você suspeitar de problemas de integridade de dados (dados históricos ausentes, valores de campo incorretos)
• Você precisar de uma lógica de campo condicional complexa que exceda o limite de 1.500 condições por tipo de usuário
• O mapeamento de campos de integração falhar apesar de usar tipos de campo suportados

Para equipes que descobrem que o gerenciamento de campos personalizados está consumindo muito tempo de administração, pode valer a pena explorar se alternativas baseadas em IA podem simplificar seu fluxo de trabalho. Nossa integração com o Zendesk funciona em conjunto com sua configuração existente para automatizar a categorização e o encaminhamento que os campos personalizados foram originalmente projetados para lidar.