zendesk-trigger-api-create-update
eesel Team
Last edited 24 fevereiro 2026
{
"title": "Como criar e atualizar triggers do Zendesk usando a API",
"slug": "zendesk-trigger-api-create-update",
"locale": "pt",
"date": "2026-02-24",
"updated": "2026-02-24",
"template": "default",
"excerpt": "Um guia passo a passo para gerenciar triggers do Zendesk via API, desde a autenticação até padrões de atualização avançados com exemplos de código funcional.",
"categories": [
"Blog Writer AI"
],
"tags": [
"Zendesk",
"API",
"Triggers",
"Automation",
"Customer Support"
],
"readTime": 11,
"author": 16,
"reviewer": 14,
"seo": {
"title": "Como criar e atualizar triggers do Zendesk usando a API",
"description": "Um guia passo a passo para gerenciar triggers do Zendesk via API, desde a autenticação até padrões de atualização avançados com exemplos de código funcional.",
"image": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-125acb51-d3f2-41d2-98d4-379496002c2a"
},
"coverImage": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-125acb51-d3f2-41d2-98d4-379496002c2a",
"coverImageAlt": "Imagem do banner para Como criar e atualizar triggers do Zendesk usando a API",
"coverImageWidth": 1920,
"coverImageHeight": 1080,
"faqs": {
"heading": "Perguntas Frequentes",
"type": "blog",
"answerType": "html",
"faqs": [
{
"question": "Posso usar a funcionalidade de criação e atualização da API de trigger do Zendesk sem acesso de administrador?",
"answer": "Não, você precisa de permissões de administrador para gerar tokens de API e gerenciar triggers. Se você não tiver acesso de administrador, peça ao seu administrador do Zendesk para conceder a você direitos de administrador ou criar os triggers em seu nome."
},
{
"question": "Qual é a diferença entre os endpoints de criação e atualização da API de trigger do Zendesk para operações únicas versus em massa?",
"answer": "Operações únicas usam POST /api/v2/triggers para criar e PUT /api/v2/triggers/{id} para atualizar triggers individuais. Operações em massa usam PUT /api/v2/triggers/update_many para atualizar a posição, o status ativo ou a categoria de vários triggers de uma vez. As atualizações em massa são processadas de forma assíncrona e retornam um status de trabalho."
},
{
"question": "Como lidar com erros ao usar os endpoints de criação e atualização da API de trigger do Zendesk?",
"answer": "Erros comuns incluem 400 (JSON inválido), 401 (problemas de autenticação), 404 (trigger não encontrado) e 422 (erros de validação). Sempre verifique o corpo da resposta para obter mensagens de erro detalhadas. Para erros 422, verifique seus campos de condição e ação em relação à documentação de referência oficial do Zendesk."
},
{
"question": "Posso atualizar parcialmente um trigger usando a funcionalidade de criação e atualização da API de trigger do Zendesk?",
"answer": "Não, o endpoint PUT substitui toda a configuração do trigger. Para fazer atualizações parciais, primeiro busque o trigger existente, modifique os campos que você precisa alterar e, em seguida, envie o objeto completo de volta. Isso garante que você não perca condições ou ações acidentalmente."
},
{
"question": "Existe uma maneira de testar os triggers criados por meio da API de criação e atualização de trigger do Zendesk antes de torná-los ativos?",
"answer": "Crie triggers com \"active\": false para mantê-los desativados inicialmente. Teste-os em seu ambiente sandbox e, em seguida, ative-os em produção assim que forem verificados. Você também pode usar o campo de posição para colocar novos triggers no final da lista para que eles não interfiram na automação existente."
},
{
"question": "Qual é o tamanho máximo para um trigger criado através da API de criação e atualização de trigger do Zendesk?",
"answer": "Os triggers devem ser menores que 65 KB. Isso inclui todas as condições, ações e metadados. Se você estiver atingindo esse limite, considere dividir a lógica complexa em vários triggers ou usar webhooks para lidar com operações complexas externamente."
},
{
"question": "Como migrar triggers entre instâncias do Zendesk usando a API?",
"answer": "Use GET /api/v2/triggers para exportar triggers de sua instância de origem, modifique o JSON para remover IDs (que são específicos da instância) e, em seguida, POST /api/v2/triggers para criá-los na instância de destino. Você precisará mapear IDs de grupo, IDs de usuário e outras referências entre as instâncias."
}
],
"supportLink": null
}
}
---
Gerenciar triggers através da interface do usuário do Zendesk funciona bem para alterações pontuais. Mas quando você precisa implantar o mesmo trigger em vários ambientes, sincronizar configurações entre sandbox e produção ou automatizar o gerenciamento de triggers em escala, a API se torna essencial. Este guia orienta você na criação e atualização de triggers do Zendesk programaticamente, desde a autenticação até exemplos de código prontos para produção.
Se você está se vendo construindo cadeias de triggers cada vez mais complexas para lidar com cenários que exigem compreensão e julgamento, talvez queira explorar alternativas baseadas em IA. Nossa [integração com o Zendesk](https://www.eesel.ai/integrations/zendesk) lida com automação diferenciada com a qual os triggers baseados em regras têm dificuldades. Mas primeiro, vamos colocar você em funcionamento com a API.
## O que você vai precisar
Antes de fazer sua primeira chamada de API, certifique-se de ter esses conceitos básicos cobertos:
- **Conta do Zendesk com acesso de administrador.** Você precisará de permissões de administrador para criar tokens de API e gerenciar triggers.
- **Token de API.** Gerado a partir do Admin Center (abordaremos isso na etapa 1).
- **Uma ferramenta para fazer solicitações HTTP.** curl funciona muito bem para testes. Postman é útil para exploração. Qualquer linguagem de programação com recursos HTTP (Python, Node.js, Ruby) funciona para automação.
- **Conhecimento básico de JSON.** A API aceita e retorna payloads JSON.
## Entendendo a estrutura do trigger do Zendesk
Os triggers no Zendesk seguem um padrão simples: **condições** definem quando um trigger é executado e **ações** definem o que acontece quando ele é executado. Pense nisso como uma regra "se isso, então aquilo".
Aqui está a estrutura JSON básica:
```json
{
"trigger": {
"title": "Notificar o responsável na reabertura",
"conditions": {
"all": [
{"field": "status", "operator": "changed", "value": "open"}
]
},
"actions": [
{"field": "notification_user", "value": ["assignee_id", "Ticket reopened", "A customer has reopened this ticket."]}
]
}
}
O objeto conditions contém dois arrays: all (AND lógico) e any (OR lógico). Cada condição no array all deve ser verdadeira para que o trigger seja disparado. Apenas uma condição no array any precisa ser verdadeira.
Campos-chave para conhecer:
- title: O nome do trigger (obrigatório)
- conditions: Define quando o trigger é executado (obrigatório)
- actions: O que o trigger faz (obrigatório)
- active: Booleano para ativar/desativar (o padrão é true)
- category_id: Organiza os triggers em categorias (opcional)
- position: Controla a ordem de execução (números menores são executados primeiro)
Distinção importante: Quando você cria um trigger com POST, você envia o objeto trigger completo. Quando você atualiza um trigger com PUT, você deve incluir TODAS as condições e ações, não apenas as que você está alterando. A atualização substitui toda a configuração do trigger.
Etapa 1: Configurar a autenticação da API
O Zendesk usa tokens de API para autenticação. Veja como gerar um:
- Navegue até Admin Center > Apps and integrations > APIs > Zendesk API
- Clique na aba Settings e certifique-se de que "Token Access" esteja habilitado
- Clique no botão (+) Add API token
- Dê ao seu token um nome descritivo como "Trigger Management"
- Copie o token imediatamente (ele não será mostrado novamente)
Limites de token: Você pode ter até 256 tokens ativos por conta. Se você atingir esse limite, precisará excluir um token existente antes de criar um novo.
Formato de autenticação: Combine seu endereço de e-mail com o token usando /token: como separador:
jdoe@example.com/token:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv
Teste sua autenticação com uma solicitação simples:
curl https://your-subdomain.zendesk.com/api/v2/triggers.json \
-u jdoe@example.com/token:YOUR_API_TOKEN
Se você receber uma resposta JSON com seus triggers (ou um array vazio se você não tiver nenhum), você está autenticado e pronto para prosseguir.
Melhores práticas de segurança:
- Armazene tokens em variáveis de ambiente, nunca no código
- Exclua os tokens que você não está usando
- Gire os tokens periodicamente
- Use tokens separados para diferentes ambientes (dev, staging, produção)
Etapa 2: Criar seu primeiro trigger
Agora vamos criar um trigger via API. Vamos construir um trigger simples que atribui tickets contendo a palavra "urgente" a um grupo específico.
O endpoint é POST /api/v2/triggers.
curl https://your-subdomain.zendesk.com/api/v2/triggers.json \
-u jdoe@example.com/token:YOUR_API_TOKEN \
-X POST \
-H "Content-Type: application/json" \
-d '{
"trigger": {
"title": "Direcionar tickets urgentes para o Nível 2",
"conditions": {
"all": [
{"field": "comment_includes_word", "operator": "includes", "value": "urgent"},
{"field": "status", "operator": "is", "value": "new"}
]
},
"actions": [
{"field": "group_id", "value": "20455932"},
{"field": "priority", "value": "high"}
]
}
}'
Vamos detalhar o que está acontecendo:
Condições: O trigger só é disparado quando um ticket é novo (status is new) E o comentário contém a palavra "urgente" (comment_includes_word includes urgent). Ambas as condições devem ser verdadeiras porque estão no array all.
Ações: Quando as condições são atendidas, o trigger atribui o ticket ao ID do grupo 20455932 e define a prioridade como alta.
A resposta da API inclui o trigger criado com seu ID atribuído:
{
"trigger": {
"id": 360012345678,
"title": "Direcionar tickets urgentes para o Nível 2",
"active": true,
"conditions": {...},
"actions": {...},
"position": 15,
"created_at": "2026-02-24T10:30:00Z"
}
}
Salve esse ID. Você precisará dele para atualizações.
Testando seu trigger: Crie um ticket de teste com "urgente" na descrição. Verifique se ele é atribuído ao grupo correto e se a prioridade está definida como alta. Se não funcionar, verifique a posição do trigger (os triggers são executados em ordem e outro trigger pode estar interferindo).
Etapa 3: Atualizar triggers existentes
A atualização de triggers requer cuidado extra. O endpoint PUT /api/v2/triggers/{id} substitui TODA a configuração do trigger. Se você enviar apenas os campos que deseja alterar, perderá todas as outras condições e ações.
Aqui está a maneira segura de atualizar um trigger:
- Buscar o trigger existente para obter seu estado atual
- Modificar os campos que você deseja alterar
- Enviar o objeto completo de volta com PUT
curl https://your-subdomain.zendesk.com/api/v2/triggers/360012345678.json \
-u jdoe@example.com/token:YOUR_API_TOKEN
curl https://your-subdomain.zendesk.com/api/v2/triggers/360012345678.json \
-u jdoe@example.com/token:YOUR_API_TOKEN \
-X PUT \
-H "Content-Type: application/json" \
-d '{
"trigger": {
"title": "Direcionar tickets urgentes e críticos para o Nível 2",
"conditions": {
"all": [
{"field": "comment_includes_word", "operator": "includes", "value": "urgent critical"},
{"field": "status", "operator": "is", "value": "new"}
]
},
"actions": [
{"field": "group_id", "value": "20455932"},
{"field": "priority", "value": "high"},
{"field": "set_tags", "value": "urgent-routing"}
]
}
}'
Observe que adicionamos "critical" às palavras-chave e adicionamos uma ação de tag. Os arrays de condições e ações inteiros estão incluídos, não apenas as alterações.
Lidando com conflitos de atualização: Se dois processos tentarem atualizar o mesmo trigger simultaneamente, você poderá receber um erro 409 Conflict. Embora os triggers não suportem o parâmetro safe_update que os tickets usam, você pode implementar sua própria detecção de conflitos verificando o timestamp updated_at antes de fazer as alterações.
Etapa 4: Operações em massa
Ao gerenciar triggers em escala, chamadas de API individuais se tornam ineficientes. O Zendesk fornece endpoints em massa para operações comuns.
Reordenando triggers
A posição do trigger determina a ordem de execução. Para mover vários triggers:
curl https://your-subdomain.zendesk.com/api/v2/triggers/update_many.json \
-u jdoe@example.com/token:YOUR_API_TOKEN \
-X PUT \
-H "Content-Type: application/json" \
-d '{
"triggers": [
{"id": 360012345678, "position": 1},
{"id": 360012345679, "position": 2},
{"id": 360012345680, "position": 3}
]
}'
Ativando e desativando em massa
curl https://your-subdomain.zendesk.com/api/v2/triggers/update_many.json \
-u jdoe@example.com/token:YOUR_API_TOKEN \
-X PUT \
-H "Content-Type: application/json" \
-d '{
"triggers": [
{"id": 360012345678, "active": false},
{"id": 360012345679, "active": false}
]
}'
Casos de uso para operações em massa:
- Implantar configurações de trigger em vários ambientes
- Desativar temporariamente os triggers durante a manutenção
- Reordenar os triggers após adicionar novos
- Migrar triggers entre instâncias do Zendesk
Considerações de desempenho: As atualizações em massa são processadas de forma assíncrona. A API retorna um status de trabalho que você pode consultar para verificar a conclusão. Para operações grandes (mais de 100 triggers), considere dividi-las em lotes menores.
Padrões e exemplos comuns
Aqui estão quatro padrões de trigger práticos que você pode adaptar para suas necessidades.
Padrão 1: Atribuição automática com base no tipo de ticket
{
"trigger": {
"title": "Atribuir incidentes à equipe L3",
"conditions": {
"all": [
{"field": "type", "operator": "is", "value": "incident"},
{"field": "status", "operator": "is", "value": "new"}
]
},
"actions": [
{"field": "group_id", "value": "20456000"},
{"field": "assignee_id", "value": "296220096"}
]
}
}
Padrão 2: Triggers de escalonamento com alterações de prioridade
{
"trigger": {
"title": "Escalonar tickets de alta prioridade",
"conditions": {
"all": [
{"field": "priority", "operator": "is", "value": "high"},
{"field": "status", "operator": "is", "value": "open"},
{"field": "hours_since_open", "operator": "greater_than", "value": "4"}
]
},
"actions": [
{"field": "priority", "value": "urgent"},
{"field": "notification_group", "value": ["20456001", "Escalation: High priority ticket", "A high-priority ticket has been open for more than 4 hours."]}
]
}
}
Padrão 3: Triggers de notificação com mensagens personalizadas
{
"trigger": {
"title": "Notificar o gerente sobre tickets VIP",
"conditions": {
"all": [
{"field": "current_tags", "operator": "includes", "value": "vip"},
{"field": "update_type", "value": "Create"}
]
},
"actions": [
{"field": "notification_user", "value": ["296220100", "New VIP ticket: {{ticket.title}}", "A VIP customer has submitted a new ticket.\n\nTicket ID: {{ticket.id}}\nRequester: {{ticket.requester.name}}\nPriority: {{ticket.priority}}"]}
]
}
}
Padrão 4: Triggers de webhook para integrações externas
{
"trigger": {
"title": "Enviar ticket para o CRM",
"conditions": {
"all": [
{"field": "status", "operator": "changed", "value": "solved"}
]
},
"actions": [
{"field": "notification_webhook", "value": ["01G8Z5K1234567890ABCDEF", "{\"ticket_id\": \"{{ticket.id}}\", \"status\": \"{{ticket.status}}\", \"solved_at\": \"{{ticket.solved_at}}\"}"]}
]
}
}
Tratamento de erros e solução de problemas
Ao trabalhar com a API Triggers, você encontrará estes códigos de status HTTP:
| Código | Significado | O que fazer |
|---|---|---|
| 200 | OK | Solicitação bem-sucedida |
| 201 | Created | Trigger criado com sucesso |
| 400 | Bad Request | Verifique sua sintaxe JSON |
| 401 | Unauthorized | Verifique seu token de API |
| 404 | Not Found | O ID do trigger não existe |
| 422 | Unprocessable | Campo de condição ou ação inválido |
| 429 | Rate Limited | Diminua a velocidade de suas solicitações |
Problemas e correções comuns:
Erros de JSON inválido: A API é rigorosa quanto à formatação JSON. Erros comuns incluem vírgulas à direita, chaves não entre aspas e escape inadequado de caracteres especiais em strings.
Erros de validação (422): Geralmente, isso significa que um campo de condição ou ação não existe ou tem um valor inválido. Verifique novamente os nomes dos campos em relação à referência de condições e à referência de ações.
O trigger não é disparado após a criação: Lembre-se de que os triggers são executados na ordem de posição. Se outro trigger modificar o ticket primeiro, as condições do seu novo trigger podem não corresponder mais. Tente mover seu trigger para uma posição anterior.
Limitação de taxa: O Zendesk permite 700 solicitações por minuto para a maioria dos endpoints. Se você atingir o limite, recue e tente novamente com atraso exponencial.
Melhores práticas para gerenciamento de trigger de API
Depois de trabalhar com a API Triggers em vários projetos, aqui estão as práticas que economizam tempo e evitam dores de cabeça:
Controle de versão de suas configurações de trigger. Armazene o JSON do trigger no Git. Isso permite a revisão de código para alterações de trigger, rollbacks fáceis quando algo quebra e documentação do porquê de condições específicas existirem.
Teste primeiro no sandbox. Sempre valide a lógica do trigger em um ambiente sandbox antes de implantar na produção. As interações do trigger podem ser complexas e o que funciona isoladamente pode entrar em conflito com os triggers existentes.
Use convenções de nomenclatura consistentes. Prefixe os triggers por função ("ROUTE-", "NOTIFY-", "ESCALATE-") para torná-los verificáveis na interface do usuário. Inclua referências de ticket em mensagens de commit quando os triggers estiverem vinculados a problemas específicos.
Documente as dependências do trigger. Quando os triggers interagem (um trigger define uma tag que outro verifica), documente esses relacionamentos. Uma alteração em um trigger pode quebrar outros de maneiras sutis.
Monitore o desempenho do trigger. Use os sideloads de uso (?include=usage_24h) para rastrear com que frequência os triggers são disparados. Os triggers que nunca são disparados podem ter condições incorretas. Os triggers que são disparados constantemente podem estar causando carga desnecessária.
Saiba quando usar a interface do usuário vs API. Use a interface do usuário para alterações e experimentações pontuais. Use a API para implantações em vários ambientes, atualizações em massa e qualquer coisa que você queira controlar a versão.
Quando considerar o eesel AI para automação
Os triggers funcionam bem para automação direta baseada em regras. Mas eles têm limites. Eles não conseguem entender o contexto, o sentimento ou a intenção. Eles exigem correspondências exatas nas palavras-chave, em vez de entender o que um cliente realmente precisa.
Na eesel AI, abordamos a automação de forma diferente. Em vez de construir uma lógica de trigger rígida, você contrata um colega de equipe de IA que aprende seu negócio e toma decisões inteligentes.
Aqui está quando você pode querer considerar nossa integração com o Zendesk junto com ou em vez de triggers complexos:
Automação complexa que requer compreensão. Deseja escalar tickets com base no sentimento, urgência ou intenção do cliente? Nossa IA lê e entende o conteúdo do ticket, não apenas os valores dos campos.
Condições de linguagem natural. Em vez de "se a tag for igual a X", você pode dizer coisas como "se o cliente parecer frustrado com a cobrança". A IA entende o contexto e as nuances.
Resolução automática de tickets. Embora os triggers possam notificar e marcar, nosso Agente de IA pode realmente resolver tickets de forma autônoma. Ele aprende com seus tickets anteriores e central de ajuda para fornecer respostas precisas sem configuração manual.
Automação progressiva. Comece com a IA redigindo respostas para revisão do agente. À medida que se prova, deixe-o enviar respostas diretamente. Eventualmente, ele pode lidar com o suporte de linha de frente completo. Você está no controle do ritmo.
Se você está se vendo construindo cadeias de triggers cada vez mais complexas, pode ser hora de explorar uma abordagem diferente. Veja como o eesel AI funciona com o Zendesk.
Compartilhe esta postagem
Article by
