Como configurar redirecionamentos no Zendesk Guide: Guia completo de 2026

Quando você exclui ou move artigos no Zendesk Guide, você fica com links quebrados. Qualquer pessoa que clicar nessas URLs antigas encontra uma página de erro 404. Isso é ruim para a experiência do usuário e pior para SEO. Mecanismos de busca não gostam de links mortos, e nem seus clientes.

A boa notícia? O Zendesk agora oferece duas maneiras de lidar com isso. Você pode usar a API de Regras de Redirecionamento (a abordagem correta do lado do servidor) ou recorrer a redirecionamentos JavaScript se precisar de uma correção rápida. Este guia explica os dois métodos para que você possa escolher o que funciona para sua situação.

Se você está achando as limitações de redirecionamento do Zendesk frustrantes, pode valer a pena explorar alternativas. Nós construímos o eesel AI para lidar com o gerenciamento de conhecimento sem esse tipo de solução alternativa. Nosso colega de equipe de IA aprende com sua documentação existente e lida com redirecionamentos automaticamente quando o conteúdo muda. Mas vamos nos concentrar em fazer o Zendesk funcionar para você primeiro.

O que você vai precisar

Antes de começar a configurar redirecionamentos, certifique-se de que você tem:

• Permissões de administrador do Guide você precisa de acesso para personalizar o tema do seu help center ou usar a API
• Para o método da API: Um token de API configurado na sua conta Zendesk (Admin Center → Apps and integrations → APIs → Zendesk API)
• Para o método JavaScript: Acesso para editar o código do seu tema (Knowledge admin → Customize design)
• Entendimento básico da sua estrutura de URL URLs do Zendesk seguem o padrão /hc/{locale}/articles/{id}-{slug}

Vamos detalhar as duas abordagens.

Método 1: Usando a API de Regras de Redirecionamento

O Zendesk introduziu a API de Regras de Redirecionamento em outubro de 2024. Esta é a abordagem recomendada para lidar com redirecionamentos porque usa códigos de status HTTP adequados que os mecanismos de busca entendem.

Visão geral da API de Regras de Redirecionamento

A API oferece redirecionamentos do lado do servidor com códigos de status HTTP adequados (301, 302, 303, 307 ou 308). Isso importa porque os mecanismos de busca tratam redirecionamentos do lado do servidor de forma diferente dos redirecionamentos JavaScript. Um redirecionamento 301 diz ao Google "esta página foi movida permanentemente", o que preserva seu valor de SEO.

Coisas importantes para saber:

• Você pode criar até 50.000 regras de redirecionamento por marca
• Disponível em todos os planos do Guide, exceto o plano legado Guide Lite
• Requer permissões de administrador do Guide
• Funciona para artigos, seções, categorias e posts da comunidade

Passo 1: Criar uma regra de redirecionamento via API

Para criar um redirecionamento, envie uma requisição POST para /api/v2/guide/redirect_rules. Aqui está a estrutura JSON que você precisa:

{
  "redirect_rule": {
    "redirect_from": "/hc/en-us/articles/123456",
    "redirect_status": 301,
    "redirect_to": "https://yoursubdomain.zendesk.com/hc/en-us/articles/789012"
  }
}

Notas importantes sobre os campos:

• redirect_from: O caminho para redirecionar, começando com /. Omita o slug (o texto após o ID do artigo) use apenas o ID
• redirect_status: Use 301 para redirecionamentos permanentes (melhor para SEO), 302 para temporários
• redirect_to: A URL completa ou caminho para redirecionar, começando com https://, http:// ou /

Aqui está um exemplo de curl:

curl https://yoursubdomain.zendesk.com/api/v2/guide/redirect_rules \
  -X POST \
  -d '{ "redirect_rule": { "redirect_from": "/hc/en-us/articles/123456", "redirect_to": "https://yoursubdomain.zendesk.com/hc/en-us/articles/789012", "redirect_status": 301 } }' \
  -H "Content-Type: application/json" \
  -v -u your_email@company.com/token:your_api_token

Passo 2: Teste seu redirecionamento

Após criar um redirecionamento, teste-o imediatamente:

1. Abra uma janela do navegador em modo anônimo
2. Navegue para a URL antiga
3. Verifique se ele redireciona para a nova URL
4. Verifique as ferramentas de desenvolvedor do navegador (aba Network) para confirmar o código de status 301

Se o redirecionamento não funcionar, verifique novamente se o artigo de origem foi realmente excluído. O redirecionamento só é acionado para URLs que retornam um erro 404.

Passo 3: Gerenciando redirecionamentos existentes

Para ver todos os seus redirecionamentos, use o endpoint de listagem:

curl https://yoursubdomain.zendesk.com/api/v2/guide/redirect_rules \
  -v -u your_email@company.com/token:your_api_token

A API usa paginação com cursor. Se você tiver muitos redirecionamentos, você receberá um after_cursor na resposta. Use-o para buscar a próxima página:

curl "https://yoursubdomain.zendesk.com/api/v2/guide/redirect_rules?page[after_cursor]=Y3Vyc29yIHR3bw==" \
  -v -u your_email@company.com/token:your_api_token

Para atualizar um redirecionamento, simplesmente envie um POST novamente com o mesmo caminho redirect_from. O novo redirect_to e redirect_status substituirão a regra existente.

Para excluir um redirecionamento, você precisará do seu ID. Primeiro encontre-o na lista, então:

curl https://yoursubdomain.zendesk.com/api/v2/guide/redirect_rules/01GFXGBX7YZ9ASWTCVMASTK8ZS \
  -X DELETE \
  -v -u your_email@company.com/token:your_api_token

Método 2: Solução alternativa de redirecionamento JavaScript

Se você não tem acesso à API ou precisa de uma correção rápida para apenas alguns artigos, redirecionamentos JavaScript são uma opção. Apenas conheça as desvantagens de antemão.

Quando usar redirecionamentos JavaScript

Esta abordagem funciona melhor quando:

• Você precisa redirecionar um pequeno número de artigos (menos de 20)
• Você não tem recursos de desenvolvedor para implementar a API
• Você está fazendo mudanças temporárias e planeja usar a API mais tarde

A pegadinha? Redirecionamentos JavaScript acontecem após a página carregar. Mecanismos de busca podem não segui-los tão confiavelmente quanto redirecionamentos do lado do servidor. O Zendesk observa explicitamente que estes "podem afetar o ranking de busca do Google" e "não são adequados para implantação de longo prazo ou em larga escala."

Passo 1: Acesse o código do seu tema

1. Vá para Knowledge admin no seu painel de administrador do Zendesk
2. Clique em Customize design (o ícone de pincel)
3. Clique em Customize no seu tema ativo
4. Clique em Edit code
5. Encontre e clique em script.js na lista de arquivos

Passo 2: Adicione o código de redirecionamento

Adicione este código perto do topo do seu arquivo script.js, antes de qualquer outra função:

// Map old article IDs to new article IDs
var oldIds = ["217352077", "216552968"];
var newIds = ["216553098", "216552958"];

for (var i = 0; i < oldIds.length; i++){
  if (window.location.href.indexOf(oldIds[i]) > -1) {
    window.location.href = 'https://yoursubdomain.zendesk.com/hc/en-us/articles/' + newIds[i];
  }
}

Substitua os IDs nos arrays oldIds e newIds com seus IDs de artigo reais. Mantenha-os entre aspas e certifique-se de que as posições correspondam (o primeiro ID antigo redireciona para o primeiro ID novo, e assim por diante).

Para redirecionamentos de fallback de idioma (enviando usuários para seu idioma padrão quando uma tradução não existe):

var notDefaultLanguage = window.location.href.indexOf('/en-us/') == -1;
var isArticle = window.location.href.indexOf('/articles/') > -1;
var isErrorPage = document.getElementsByClassName("error-page").length > 0;

if ( isArticle && notDefaultLanguage && isErrorPage ) {
    var newURL = window.location.href.replace(/(.*\/hc\/)([\w-]+)(\/.*)/, "$1en-us$3");
    window.location.href = newURL;
}

Substitua en-us com seu código de idioma padrão se for diferente.

Passo 3: Publique e teste

1. Clique em Publish para salvar suas mudanças
2. Teste em uma janela anônima em vários navegadores
3. Verifique o comportamento em dispositivos móveis redirecionamentos devem funcionar da mesma forma em dispositivos móveis
4. Limpe o cache do seu navegador se os redirecionamentos não aparecerem imediatamente

Cenários comuns de redirecionamento

Redirecionando artigos excluídos para equivalentes novos

O caso de uso mais comum: você excluiu um artigo antigo e escreveu um novo cobrindo o mesmo tópico. Use o método da API com um redirecionamento 301 para preservar o valor de SEO.

Para redirecionamentos em massa (como após uma grande reorganização de conteúdo), crie um script para as chamadas da API. Aqui está um exemplo em Python:

import requests

redirects = [
    ("/hc/en-us/articles/111", "/hc/en-us/articles/222"),
    ("/hc/en-us/articles/333", "/hc/en-us/articles/444"),
]

for old_path, new_path in redirects:
    payload = {
        "redirect_rule": {
            "redirect_from": old_path,
            "redirect_status": 301,
            "redirect_to": f"https://yoursubdomain.zendesk.com{new_path}"
        }
    }
    response = requests.post(
        "https://yoursubdomain.zendesk.com/api/v2/guide/redirect_rules",
        json=payload,
        auth=("your_email@company.com/token", "your_api_token")
    )
    print(f"Redirected {old_path}: {response.status_code}")

Lidando com conteúdo não traduzido

Se você suporta vários idiomas, mas não traduz todos os artigos, configure redirecionamentos de fallback. Quando um usuário tenta acessar um artigo em francês que só existe em inglês, redirecione-o para a versão em inglês em vez de mostrar um 404.

O exemplo JavaScript no Passo 2 acima lida com isso. Para uma solução do lado do servidor usando a API, você precisaria criar redirecionamentos individuais para cada artigo não traduzido.

Redirecionamentos de migração

Mudando de outra plataforma para o Zendesk? Você provavelmente terá padrões de URL diferentes. Por exemplo:

• Antigo: /support/solutions/articles/1234
• Novo: /hc/en-us/articles/5678

Crie redirecionamentos para cada URL antiga apontando para seu novo equivalente no Zendesk. Note que URLs começando com /knowledge/ (como as URLs da base de conhecimento do HubSpot) não funcionarão como fontes de redirecionamento no Zendesk esse caminho é reservado.

Solução de problemas comuns

Redirecionamentos não funcionando de jeito nenhum

Verifique se o artigo de origem foi realmente excluído. O redirecionamento só é acionado para erros 404. Artigos arquivados ou não publicados não acionarão redirecionamentos.

Parâmetros de consulta quebrando redirecionamentos

Se suas URLs incluem parâmetros de rastreamento (como ?utm_source=email), o redirecionamento pode não corresponder. A API corresponde apenas ao caminho, então os parâmetros não devem importar, mas teste para confirmar.

Complicações do proxy Cloudflare

Se você usa o Cloudflare com o mapeamento de host do Zendesk, você pode encontrar problemas. Quando você "orange cloud" (proxy) seu registro CNAME apontando para o Zendesk, o Cloudflare for SaaS entra em ação e roteia o tráfego diretamente para o Zendesk, ignorando suas regras de redirecionamento. As soluções incluem usar Origin Rules ou um nome de host proxy separado.

Conflitos de mapeamento de host

Se você mapeou um domínio personalizado para seu help center, certifique-se de que seus redirecionamentos usam o domínio correto. Redirecionamentos funcionam tanto para subdomínios do Zendesk quanto para domínios mapeados por host.

Problemas de cache

Após publicar mudanças de tema para redirecionamentos JavaScript, limpe o cache do seu navegador. Para redirecionamentos da API, as mudanças são imediatas, mas o cache da CDN pode atrasar a visibilidade.

Melhores práticas de SEO para redirecionamentos do Zendesk Guide

Quando usar redirecionamentos 301 vs 302

Use 301 (Movido Permanentemente) quando:

• Um artigo é permanentemente excluído e substituído
• Você está migrando conteúdo de outra plataforma
• A URL antiga nunca mais será usada

Use 302 (Encontrado) quando:

• O redirecionamento é temporário
• Você está fazendo testes A/B de diferentes versões de artigos
• O conteúdo original pode retornar

Evitando cadeias de redirecionamento

Não crie cadeias como: Artigo A → Artigo B → Artigo C. O Google pode parar de seguir após alguns saltos. Sempre redirecione para o destino final.

Atualizando links internos vs confiando em redirecionamentos

Redirecionamentos são uma rede de segurança, não uma estratégia. Atualize seus links internos para apontar diretamente para novas URLs. Isso reduz a carga do servidor e garante que os usuários obtenham a experiência mais rápida.

Monitorando erros 404

Configure o Google Search Console para seu help center. Verifique o relatório de Cobertura regularmente para erros 404. Cada um é um redirecionamento potencial que você precisa criar.

Alternativa: Considere o eesel AI para gerenciamento do help center

Se você está gastando um tempo significativo gerenciando redirecionamentos do Zendesk, lutando com o código do tema ou contornando as limitações da plataforma, há uma maneira melhor.

Nós construímos o eesel AI como um colega de equipe de IA para atendimento ao cliente. Ao contrário dos help centers tradicionais que exigem gerenciamento manual de redirecionamento, o eesel aprende com sua documentação existente (Confluence, Google Docs, Notion, tickets passados) e lida com mudanças de conteúdo automaticamente.

Quando você atualiza ou move conteúdo, a IA do eesel entende os relacionamentos e exibe as informações corretas sem configuração manual de redirecionamento. Você define regras de escalonamento em português claro ("Se o pedido de reembolso for superior a 30 dias, recuse educadamente"), e o eesel cuida do resto.

Nossos clientes normalmente veem taxas de resolução autônoma de até 81% para suporte de linha de frente. Se as limitações de redirecionamento do Zendesk fazem parte de uma frustração mais ampla com a plataforma, experimente o eesel gratuitamente e veja como uma abordagem nativa de IA difere.

Comece a gerenciar seus redirecionamentos do Zendesk Guide de forma eficaz

Você agora tem duas opções sólidas para lidar com redirecionamentos no Zendesk Guide. Para uso em produção, a API de Regras de Redirecionamento é a clara vencedora. Ela oferece redirecionamentos 301 adequados que preservam o valor de SEO e escalam para 50.000 regras por marca.

Para correções rápidas ou necessidades de pequena escala, redirecionamentos JavaScript funcionam em um aperto. Apenas lembre-se das desvantagens de SEO e do aviso do Zendesk de que eles não são adequados para uso a longo prazo.

Se o gerenciamento de redirecionamento é apenas um item em uma lista crescente de limitações do Zendesk, pode ser hora de considerar se a plataforma ainda se encaixa nas suas necessidades. Alternativas modernas de IA como o eesel AI lidam com esses problemas automaticamente, permitindo que você se concentre em oferecer ótimas experiências ao cliente em vez de manter regras de redirecionamento.