Como criar e atualizar triggers do Zendesk usando a API
Stevia Putri
Última edição February 24, 2026
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 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:
{
"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.
Perguntas Frequentes
Share this article
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.
