Personalize a identidade visual e os temas da central de ajuda com a API Notiondesk

A API Notiondesk permite que você leia e altere a identidade visual da sua central de ajuda: cores, fontes, layout, cabeçalho e rodapé, links, exibição de pesquisa e feedback e tema. Use-a para implementar a mesma identidade visual em várias centrais de ajuda ou para manter sua identidade visual no código, integrada ao restante do seu sistema de design.

A identidade visual é visível em todas as páginas públicas, portanto, atualizá-la requer o escopo admin, e não write. Somente uma chave criada pelo proprietário do espaço de trabalho ou pelo administrador possui o escopo admin.

Para alterar a identidade visual no painel de controle, consulte Personalizar as cores e fontes da sua central de ajuda .

O que a API não altera

Esses itens permanecem apenas no painel de controle. A rota de leitura não os retorna, e uma atualização que nomeia um deles responde com o código 400 validation_error:

• CSS personalizado e JavaScript personalizado. Consulte Personalize sua central de ajuda com CSS personalizado ;

• Logotipos (claros e escuros), logotipos de rodapé (claros e escuros), favicon, imagem para redes sociais e imagens de cabeçalho (claras e escuras).

Leia a sua marca

A resposta contém exatamente os campos que a atualização aceita, com os mesmos nomes. Um exemplo resumido:

curl "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/settings/customize" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16"

{
  "colors": {
    "primary": "#2563eb",
    "text": "#111827",
    "link": "#2563eb",
    "link_hover": "#1d4ed8",
    "header": "#2563eb",
    "header_text": "#ffffff",
    "background": "#ffffff",
    "footer_background": ""
  },
  "appearance": null,
  "layout_collection": "column_2",
  "layout_article": "column_1",
  "footer_layout": "compact",
  "primary_font": "Inter",
  "header_links": [{"title": "Docs", "url": "https://example.com/docs"}],
  "footer_links": [{"title": "Product", "links": [{"title": "Pricing", "url": "https://example.com/pricing"}]}],
  "show_powered_by_badge": false,
  "theme": null
}

• Uma cor que nunca foi definida é exibida como "". colors.dark contém as cores do modo escuro e está ausente quando a central de ajuda não possui uma paleta escura.

• Uma lista que não contém nada é exibida como [].

• theme é o code do tema atual, ou null.

Atualize sua marca

A rota responde a 204 No Content. Leia a sinalização novamente para confirmar a alteração.

curl -i -X PATCH "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/settings/customize" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16" \
  -H "Content-Type: application/json" \
  -d '{"primary_font": "Inter", "colors": {"primary": "#2563eb"}, "header_links": [{"title": "Docs", "url": "https://example.com/docs"}]}'

• Um campo que você omite mantém seu valor. Dentro de colors, uma cor que você omite também mantém seu valor.

• Uma lista que você envia substitui toda a lista armazenada e [] a esvazia.

• As cores são valores hexadecimais #rrggbb, ou "". Formas abreviadas como #fff são rejeitadas.

• Enviar valores booleanos JSON. Os valores 0 e "false" são lidos como true, e null como false.

Cada atualização aceita atualiza toda a central de ajuda: Notiondesk limpa o cache de páginas e reconstrói todas as páginas, independentemente das alterações feitas na atualização. Envie todas as alterações em uma única solicitação, e não uma solicitação por campo.

Atualizações seguras: leia, altere, envie de volta

A maneira mais segura de atualizar a identidade visual é enviar de volta o que você leu, com as alterações aplicadas. Um campo enviado com seu valor atual é aceito em qualquer plano, portanto, esse padrão nunca aciona um limite do plano em campos que você não modificou.

Um corpo de resposta enviado ainda pode ser recusado em dois casos. Corrija o valor no painel de controle ou omita esse campo do corpo da resposta:

const url = "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/settings/customize";
const headers = {
  Authorization: `Bearer ${process.env.NOTIONDESK_API_KEY}`,
  "nd-version": "2026-10-16",
  "Content-Type": "application/json",
};

const branding = await (await fetch(url, { headers })).json();
branding.colors.primary = "#7c3aed";
branding.colors.link = "#7c3aed";

const response = await fetch(url, { method: "PATCH", headers, body: JSON.stringify(branding) });
console.log(response.status);

• uma cor armazenada em formato abreviado, como #fff;

• Uma lista armazenada que exceda os limites abaixo.

Campos que você pode alterar

Os links são objetos com um title e um url. Os grupos de links do rodapé são objetos com um title e uma lista links. As traduções são objetos com um locale e o links, groups ou value traduzido.

Limites do plano

Alterar uma delas em um plano sem o recurso resulta em 403 permission_denied, a mensagem nomeia o recurso e nada é escrito.

Sem personalização avançada, as cores do rodapé mantêm seus valores armazenados sem erros. Sem um chatbot de IA ativado, os campos ai_search_display_mode, ai_search_aside_position e ai_search_enabled: true também mantêm seus valores armazenados.

Lista de limites

• Cada lista comporta até 100 entradas, assim como cada lista links ou groups dentro dela.

• Todas as listas juntas podem conter até 3.000 entradas, incluindo entradas aninhadas e as listas armazenadas que seu corpo omite.

O botão de contato ativa o formulário de contato.

Embora show_contact_us_button seja true em um plano com personalização avançada, cada atualização de marca ativa o formulário de contato da central de ajuda, assim como acontece ao salvar as alterações no painel. Consulte a seção do formulário de contato em Atualizar as configurações da central de ajuda com a API Notiondesk .

Escolha um tema

A lista sempre contém todos os temas em uma única resposta, na ordem em que são exibidos. Aplique um tema enviando seu code como theme:

A configuração de um tema requer personalização avançada. O envio de "theme": null mantém o tema inalterado.

Erros

curl "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/themes" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16"

{
  "object": "list",
  "data": [
    {
      "code": "ocean",
      "name": "Ocean",
      "description": "A calm, airy theme",
      "preview_image_url": "https://example.com/ocean.png",
      "layout": "default"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

curl -i -X PATCH "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/settings/customize" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16" \
  -H "Content-Type: application/json" \
  -d '{"theme": "ocean"}'

Os erros de campo nomeiam o valor, por exemplo, colors.primary ou footer_links[0].links. Consulte Handle Notiondesk API errors, rate limits, and retries .

Perguntas frequentes

O que vem a seguir?

• Atualize as configurações da central de ajuda com a API Notiondesk

• Gerencie as integrações da central de ajuda com a API Notiondesk

• Automatize tarefas comuns da central de ajuda com a API Notiondesk