Personaliza la imagen de marca y los temas del centro de ayuda con la API Notiondesk

La API Notiondesk te permite leer y modificar la identidad visual de tu centro de ayuda: colores, fuentes, diseño, encabezado y pie de página, enlaces, visualización de búsqueda y comentarios, y tema. Úsala para implementar la misma identidad visual en varios centros de ayuda o para mantenerla integrada en el código junto con el resto de tu sistema de diseño.

La marca es visible en todas las páginas públicas, por lo que para actualizarla se necesita el ámbito admin, no write. Solo una clave creada por el propietario o administrador del espacio de trabajo tiene el ámbito admin.

Para cambiar la imagen de marca en el panel de control, consulte Personalizar los colores y las fuentes del centro de ayuda .

Lo que la API no cambia

Estos permanecen solo en el panel de control. La ruta de lectura no los devuelve, y una actualización que nombra uno responde 400 validation_error:

• CSS personalizado y JavaScript personalizado. Consulte Personalizar su centro de ayuda con CSS personalizado ;

• Logotipos (claros y oscuros), logotipos de pie de página (claros y oscuros), favicon, imagen de redes sociales e imágenes de encabezado (claras y oscuras).

Lee tu marca

La respuesta contiene exactamente los campos que acepta la actualización, con los mismos nombres. Un ejemplo abreviado:

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
}

• Un color que nunca se configuró se lee "". colors.dark contiene los colores del modo oscuro y está ausente cuando el centro de ayuda no tiene una paleta oscura.

• Una lista que no contiene nada se lee [].

• theme es el code del tema actual, o null.

Actualiza tu marca

La ruta responde 204 No Content. Lea la información de marca nuevamente para confirmar el cambio.

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"}]}'

• Un campo que omitas conserva su valor. Dentro de colors, un color que omitas también conserva su valor.

• Una lista que envíes reemplaza toda la lista almacenada, y [] la vacía.

• Los colores son valores hexadecimales #rrggbb o "". Se rechazan las formas abreviadas como #fff.

• Envía valores booleanos JSON. Los valores 0 y "false" se leen como true, y null como false.

Cada actualización aceptada actualiza todo el centro de ayuda: Notiondesk borra sus páginas en caché y reconstruye cada página, independientemente de los cambios introducidos por la actualización. Envía cada cambio en una sola solicitud, no una solicitud por campo.

Actualizaciones seguras: leer, modificar, devolver.

La forma más segura de actualizar la marca es enviar de vuelta lo que leíste, con los cambios aplicados. Un campo enviado con su valor actual se acepta en cualquier plan, por lo que este método nunca activa el límite del plan para campos que no modificaste.

Un cuerpo devuelto aún puede ser rechazado en dos casos. Corrija el valor en el panel de control o elimine ese campo del cuerpo:

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);

• un color almacenado en formato abreviado como #fff;

• una lista almacenada más larga que los límites que se indican a continuación.

Campos que puedes cambiar

Los enlaces son objetos con un title y un url. Los grupos de enlaces del pie de página son objetos con un title y una lista links. Las traducciones son objetos con un locale y la traducción links, groups o value.

Límites del plan

Cambiar uno de ellos en un plan sin la función responde 403 permission_denied, el mensaje nombra la función y no se escribe nada.

Sin personalización avanzada, los colores del pie de página conservan su valor almacenado sin errores. Sin un chatbot de IA habilitado, ai_search_display_mode, ai_search_aside_position y ai_search_enabled: true también conservan su valor almacenado.

Límites de la lista

• Cada lista admite hasta 100 entradas, al igual que cada lista links o groups que se encuentre dentro de ella.

• Todas las listas juntas pueden contener hasta 3000 entradas, incluyendo las entradas anidadas y las listas almacenadas que tu cuerpo omite.

El botón de contacto activa el formulario de contacto.

Mientras que show_contact_us_button es true en un plan con personalización avanzada, cada actualización de marca activa el formulario de contacto del centro de ayuda, como lo hace un guardado en el panel. Consulte la sección del formulario de contacto de Actualizar la configuración del centro de ayuda con la API Notiondesk .

Elige un tema

La lista siempre contiene todos los temas en una sola respuesta, en el orden en que se muestran. Aplique uno enviando su code como theme:

Configurar un tema requiere una personalización avanzada. Enviar "theme": null deja el tema sin cambios.

Errores

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"}'

Los errores de campo nombran el valor, por ejemplo colors.primary o footer_links[0].links. Consulte Manejo de errores de API, límites de velocidad y reintentos de Notiondesk .

Preguntas frecuentes

¿Qué sigue?

• Actualiza la configuración del centro de ayuda con la API Notiondesk

• Gestiona las integraciones del centro de ayuda con la API Notiondesk

• Automatice las tareas comunes del centro de ayuda con la API Notiondesk.