A maioria das equipes de suporte eventualmente atinge um limite. Elas cobrem tickets, usuários e organizações, mas e quanto aos equipamentos que os clientes usam? Os planos de assinatura que eles compraram? Os pedidos sobre os quais eles estão perguntando?
Os Objetos Personalizados do Zendesk resolvem esse problema. Eles permitem que você estenda o modelo de dados do Zendesk para armazenar o que for importante para o seu negócio e, em seguida, conectar esses dados diretamente aos tickets de suporte.
Este guia cobre tudo o que você precisa saber sobre a API de objetos personalizados do Zendesk. Seja você um desenvolvedor criando integrações, um administrador do Zendesk estendendo sua instância ou um consultor técnico implementando soluções, você encontrará exemplos práticos e padrões do mundo real que pode usar imediatamente. Para equipes que buscam aprimorar ainda mais sua configuração do Zendesk, a integração do eesel AI com o Zendesk pode ajudar a automatizar os fluxos de trabalho de suporte usando seus dados personalizados.
O que são objetos personalizados do Zendesk?
O Zendesk oferece objetos padrão prontos para uso: tickets, usuários, organizações e artigos. Eles funcionam muito bem para cenários de suporte básicos. Mas os negócios são mais complexos do que isso.
Os objetos personalizados permitem que você crie suas próprias estruturas de dados dentro do Zendesk. Pense neles como tabelas de banco de dados que você define. Você cria o objeto (a tabela), define seus campos (as colunas) e, em seguida, adiciona registros (as linhas).
Para trabalhar efetivamente com objetos personalizados, você precisa entender quatro conceitos principais:
- Objetos personalizados - O contêiner ou modelo para seus dados. Isso define que tipo de coisa você está rastreando.
- Campos de objetos personalizados - O esquema que define quais propriedades cada objeto possui. Sem campos, seu objeto é apenas uma casca vazia.
- Campos de relacionamento de pesquisa - Campos especiais que criam conexões entre seus objetos personalizados e objetos padrão do Zendesk (ou outros objetos personalizados).
- Registros de objetos personalizados - Instâncias individuais de seus dados personalizados. Se seu objeto for "Software", cada registro é um software específico.
Os casos de uso comuns incluem rastreamento de ativos de hardware (laptops, impressoras), gerenciamento de licenças de software, vinculação de pedidos de e-commerce a tickets de suporte ou armazenamento de dados de assinatura. Qualquer cenário em que você precise referenciar dados específicos da empresa durante as interações de suporte é um candidato para objetos personalizados. A documentação do desenvolvedor do Zendesk fornece tutoriais detalhados sobre a implementação desses casos de uso.
Nova API vs API Legada: O que você precisa saber
Aqui está algo crítico que confunde muitos desenvolvedores: o Zendesk tem duas APIs de Objetos Personalizados completamente separadas. Elas não são compatíveis. Os dados criados com uma não podem ser acessados pela outra.
A Nova API de Objetos Personalizados
A API moderna usa o endpoint /api/v2/custom_objects e é profundamente integrada ao Espaço de Trabalho do Agente do Zendesk. Os registros aparecem nativamente na interface, os campos de pesquisa funcionam em formulários de ticket e toda a experiência parece um recurso nativo do Zendesk. Você pode aprender mais sobre como começar com objetos personalizados na documentação oficial.
Esta é a API que você deve usar para todos os novos projetos.
A API de Objetos Personalizados Legada
A API mais antiga usa /api/sunshine/ e foi a primeira tentativa do Zendesk de dados personalizados. Ela funciona, mas parece adicionada em vez de integrada. A documentação da API de Objetos Personalizados Legada se refere a isso como a "API de Objetos Personalizados Legada" e é mantida principalmente para implementações existentes.
Se você estiver mantendo uma integração mais antiga, pode precisar desta API. Caso contrário, use a nova.
Qual você deve usar?
A menos que você tenha um motivo específico para usar a API Legada (como manter o código existente), sempre escolha a Nova API de Objetos Personalizados. Ela é melhor documentada, melhor integrada e onde o Zendesk está investindo em esforços de desenvolvimento futuros.
Começando: Pré-requisitos e configuração
Antes de começar a fazer chamadas de API, você precisará de algumas coisas no lugar.
Plano do Zendesk necessário
Os objetos personalizados não estão disponíveis em todos os planos. De acordo com a documentação do plano do Zendesk, você precisa de um dos seguintes:
- Support Enterprise
- Qualquer plano do Zendesk Suite (Team, Growth, Professional, Enterprise ou Enterprise Plus)
O nível do plano afeta quantos objetos personalizados você pode criar, então verifique a seção de limites mais adiante neste guia.
Habilitar objetos personalizados no Centro de Administração
Um administrador precisa ativar o recurso antes que você possa usá-lo.
- Vá para o Centro de Administração
- Clique em Objetos e regras na barra lateral
- Selecione Objetos personalizados > Objetos
- Clique em Começar
Se sua conta usou anteriormente objetos personalizados legados, você verá um banner oferecendo para experimentar a nova experiência. Clique em Experimentar para habilitar a API moderna.
Criar um token de API
Todas as solicitações de API usam Autenticação Básica com um token de API. A documentação da API do Zendesk explica como criar um:
- No Centro de Administração, vá para Aplicativos e integrações > APIs > API do Zendesk
- Clique na aba Configurações
- Habilite o Acesso ao Token se ainda não estiver ativado
- Clique no botão + para adicionar um novo token
- Dê a ele um nome descritivo como "Integração de Objetos Personalizados"
- Copie o token imediatamente (o Zendesk não o mostrará novamente)
Formato de autenticação
Cada solicitação de API precisa de um cabeçalho de Autorização com seu e-mail e token:
Authorization: Basic {base64({email_address}/token:{api_token})}
Por exemplo, se seu e-mail for admin@company.com e seu token for abc123xyz, você codificaria em Base64 admin@company.com/token:abc123xyz e incluiria isso no cabeçalho.
Trabalhando com a API de Objetos Personalizados
Agora vamos percorrer as operações principais que você usará com mais frequência.
Criando objetos personalizados
Para criar um objeto personalizado, envie uma solicitação POST para /api/v2/custom_objects com três campos obrigatórios:
- key - Um identificador exclusivo para o objeto (não pode ser alterado posteriormente)
- title - O nome de exibição singular (por exemplo, "Software")
- title_pluralized - O nome de exibição plural (por exemplo, "Softwares")
Aqui está um exemplo de cURL:
curl --request POST https://{subdomain}.zendesk.com/api/v2/custom_objects \
--header "Content-Type: application/json" \
-u {email_address}/token:{api_token} \
--data-raw '{
"custom_object": {
"key": "software",
"title": "Software",
"title_pluralized": "Software"
}
}'
Os campos opcionais incluem:
- description - O que este objeto representa
- allows_attachments - Se os registros podem ter anexos de arquivo
- include_in_list_view - Se os agentes veem este objeto na página de registros de Objetos Personalizados
Definindo campos de objetos personalizados
Um objeto sem campos é apenas um contêiner vazio. Você define o esquema usando a API de Campos de Objetos Personalizados. A documentação oficial sobre a criação de objetos personalizados fornece orientação adicional sobre a configuração de campos:
curl --request POST https://{subdomain}.zendesk.com/api/v2/custom_objects/software/fields \
--header "Content-Type: application/json" \
-u {email_address}/token:{api_token} \
--data-raw '{
"custom_object_field": {
"key": "version",
"title": "Version",
"type": "text"
}
}'
Os tipos de campo disponíveis incluem texto, textarea, checkbox, data, inteiro, decimal, regexp, dropdown, multiselect e lookup. Consulte a referência da API de Campos de Objetos Personalizados para obter detalhes completos sobre cada tipo de campo.
Os campos de pesquisa são particularmente poderosos. Eles criam relacionamentos entre objetos. Para vincular seu objeto Software a tickets, crie um campo de pesquisa em tickets que aponte para Software:
curl https://{subdomain}.zendesk.com/api/v2/ticket_fields.json \
-H "Content-Type: application/json" -X POST \
-u {email_address}/token:{api_token} \
--data-raw '{
"ticket_field": {
"type": "lookup",
"title": "Affected Software",
"relationship_target_type": "zen:custom_object:software"
}
}'
Gerenciando registros de objetos personalizados
Depois que seu objeto e campos estiverem configurados, você pode criar registros.
import requests
from requests.auth import HTTPBasicAuth
url = "https://{subdomain}.zendesk.com/api/v2/custom_objects/software/records"
payload = {
"custom_object_record": {
"name": "Zendesk Support",
"custom_object_fields": {
"version": "2024.1",
"license_type": "Enterprise"
}
}
}
headers = {"Content-Type": "application/json"}
auth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request("POST", url, auth=auth, headers=headers, json=payload)
A API suporta paginação baseada em cursor para listar registros, o que é mais eficiente do que a paginação de deslocamento para grandes conjuntos de dados. Use os parâmetros page[after] e page[size] para navegar pelos resultados. Consulte a referência da API de Registros de Objetos Personalizados para obter detalhes completos sobre a paginação.
Limites do plano e práticas recomendadas
Entender os limites ajuda você a projetar dentro das restrições desde o início.
Limites de objetos personalizados por plano
| Plano | Limite de Objetos Personalizados | Campos de Pesquisa por Objeto |
|---|---|---|
| Suite Team | 3 | 5 |
| Suite Growth | 5 | 5 |
| Support Enterprise | 30 | 10 |
| Suite Professional | 30 | 10 |
| Suite Enterprise | 50 | 10 |
| Suite Enterprise Plus | 50 | 10 |
Outros limites importantes
- 100 campos no máximo por objeto personalizado (os campos padrão não contam)
- 32 KB no máximo por registro
- 50 milhões de registros no máximo por conta
- 100 registros por página ao listar via API
Práticas recomendadas para modelagem de dados
Planeje seus relacionamentos de objeto antes de começar a construir. Alterar chaves ou estruturas fundamentais posteriormente requer recriar objetos e migrar dados.
Use o campo external_id para registros ao sincronizar com sistemas externos. Isso permite que você referencie registros por seus próprios identificadores em vez dos IDs internos do Zendesk.
Para desempenho, use paginação baseada em cursor ao iterar através de grandes conjuntos de registros. A paginação de deslocamento fica mais lenta à medida que você pagina mais profundamente nos resultados. Revise a documentação de paginação da API do Zendesk para obter dicas de otimização adicionais.
Integrando objetos personalizados em seu fluxo de trabalho
O verdadeiro poder dos objetos personalizados vem de como eles se integram com o resto do Zendesk.
Formulários de ticket e Espaço de Trabalho do Agente
Quando você adiciona campos de pesquisa aos formulários de ticket, os agentes podem pesquisar e selecionar registros de objetos personalizados diretamente enquanto visualizam os tickets. Os dados do registro selecionado aparecem na barra lateral do ticket, dando aos agentes contexto completo sem alternar contextos. Confira o guia do Zendesk sobre como começar com objetos personalizados para obter instruções de configuração.
Zendesk Apps Framework
Você pode criar aplicativos de barra lateral que exibem dados de objetos personalizados no Espaço de Trabalho do Agente. Isso é útil quando você precisa mostrar dados computados, registros relacionados de sistemas externos ou visualizações personalizadas que vão além do que os campos de pesquisa fornecem.
Gatilhos e automação
Os objetos personalizados funcionam com gatilhos do Zendesk, permitindo que você automatize com base em dados personalizados. Por exemplo, você pode rotear automaticamente tickets sobre licenças expiradas para uma equipe de renovações ou escalar problemas que afetam clientes VIP com base em dados em um objeto personalizado.
Integração de sistema externo
A API permite a sincronização bidirecional com sistemas externos. Você pode sincronizar dados do catálogo de produtos de sua plataforma de e-commerce, extrair informações de ativos de seu sistema de gerenciamento de ativos de TI ou enviar insights de suporte de volta para seu CRM.
Usando o eesel AI com dados personalizados do Zendesk
Depois de ter objetos personalizados armazenando seus dados de negócios, você pode colocar essas informações para trabalhar em suas operações de suporte. Na eesel AI, construímos nossa plataforma para funcionar perfeitamente com dados do Zendesk, incluindo objetos personalizados.
Nossos agentes de IA podem referenciar registros de objetos personalizados ao responder a tickets. Se um cliente perguntar sobre sua licença de software, a IA pode procurar o registro da licença, verificar as datas de validade e fornecer informações precisas sem intervenção humana.
Também usamos relacionamentos de objetos personalizados para personalizar as interações. Quando a IA sabe quais produtos um cliente usa (de seus objetos personalizados), ela pode adaptar as respostas com contexto relevante e sugerir soluções apropriadas.
Se você está investindo em objetos personalizados para modelar seus dados de negócios, considere como a IA pode alavancar esse investimento. A combinação de dados personalizados estruturados e automação inteligente cria experiências de suporte que parecem genuinamente úteis em vez de genéricas. Você pode experimentar o eesel AI gratuitamente e ver como ele funciona com sua configuração do Zendesk.
Comece a construir com objetos personalizados do Zendesk hoje
A API de objetos personalizados do Zendesk oferece as ferramentas para modelar seus dados de negócios exclusivos e integrá-los diretamente ao seu fluxo de trabalho de suporte. Você aprendeu os conceitos principais, a diferença entre as versões da API, como autenticar e as operações principais para criar objetos, definir campos e gerenciar registros.
Suas próximas etapas dependem de seus objetivos. Se você estiver construindo uma integração, comece com uma pequena prova de conceito, talvez um objeto personalizado com alguns campos. Teste as operações CRUD e, em seguida, expanda para relacionamentos e conexões de sistema externo.
Se você é um administrador do Zendesk, trabalhe com sua equipe para identificar quais dados de negócios melhorariam mais as interações de suporte. As melhores implementações de objetos personalizados resolvem problemas reais que os agentes enfrentam diariamente.
E se você está procurando obter mais valor do seu investimento no Zendesk, explore como a IA pode alavancar seus dados personalizados para um suporte mais inteligente e personalizado. A combinação de dados estruturados e automação inteligente é para onde o suporte moderno está indo. Agende uma demonstração para ver como o eesel AI funciona com seus objetos personalizados do Zendesk.
Perguntas Frequentes
Compartilhe esta postagem
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.
