Personnalisez l'image de marque et les thèmes du centre d'aide avec l'API Notiondesk

L'API Notiondesk vous permet de lire et de modifier l'identité visuelle de votre centre d'aide : couleurs, polices, mise en page, en-tête et pied de page, liens, affichage des résultats de recherche et des commentaires, et thème. Utilisez-la pour déployer une identité visuelle uniforme sur plusieurs centres d'aide ou pour conserver votre identité visuelle dans le code, au même titre que le reste de votre système de conception.

L'identité visuelle est visible sur toutes les pages publiques ; sa mise à jour nécessite donc le droit admin, et non write. Seule une clé créée par le propriétaire de l'espace de travail ou un administrateur détient le droit admin.

Pour modifier l'image de marque dans le tableau de bord, consultez la section Personnaliser les couleurs et les polices de votre centre d'aide .

Ce que l'API ne change pas

Ces éléments restent accessibles uniquement via le tableau de bord. La méthode de lecture ne les renvoie pas, et une mise à jour qui en nomme un renvoie une erreur 400 validation_error.

• CSS et JavaScript personnalisés. Consultez la section Personnaliser votre centre d'aide avec du CSS personnalisé ;

• logos (clairs et foncés), logos de pied de page (clairs et foncés), favicon, image des médias sociaux et images d'en-tête (claires et foncées).

Lisez votre image de marque

La réponse contient exactement les champs acceptés par la mise à jour, sous les mêmes noms. Voici un exemple simplifié :

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
}

• La couleur qui n'a jamais été définie est "". colors.dark contient les couleurs du mode sombre et est absente lorsque le centre d'aide ne dispose pas de palette sombre.

• Une liste qui ne contient rien se lit [].

• theme est le code du thème actuel, ou null.

Mettez à jour votre image de marque

L'itinéraire répond à 204 No Content. Veuillez relire le marquage pour confirmer le changement.

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 champ non renseigné conserve sa valeur. Dans colors, une couleur non renseignée conserve également sa valeur.

• Une liste que vous envoyez remplace toute la liste stockée, et [] la vide.

• Les couleurs sont exprimées en valeurs hexadécimales #rrggbb ou "". Les formes abrégées telles que #fff sont rejetées.

• Envoyer des booléens JSON. Les valeurs 0 et "false" sont lues comme true, et null comme false.

Chaque mise à jour acceptée actualise l'intégralité du centre d'aide : Notiondesk efface ses pages en cache et reconstruit chaque page, quelles que soient les modifications apportées. Envoyez chaque modification en une seule requête, et non une requête par champ.

Mises à jour sécurisées : lire, modifier, renvoyer

La méthode la plus sûre pour mettre à jour votre identité visuelle consiste à renvoyer le texte reçu, après y avoir appliqué vos modifications. Un champ renvoyé avec sa valeur actuelle est accepté quel que soit votre abonnement ; ainsi, cette méthode ne risque jamais de dépasser la limite de votre abonnement pour les champs que vous n'avez pas modifiés.

Un corps de requête renvoyé peut encore être refusé dans deux cas : corrigez la valeur dans le tableau de bord ou omettez ce champ dans le corps de la requête.

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

• une couleur stockée sous une forme abrégée telle que #fff;

• une liste stockée plus longue que les limites ci-dessous.

Champs que vous pouvez modifier

Les liens sont des objets comportant un champ title et un champ url. Les groupes de liens de pied de page sont des objets comportant un champ title et une liste links. Les traductions sont des objets comportant un champ locale et la traduction correspondante : links, groups ou value.

Limites du plan

Modifier l'un d'eux sur un forfait sans la fonctionnalité répond 403 permission_denied, le message nomme la fonctionnalité et rien n'est écrit.

Sans personnalisation avancée, les couleurs du pied de page conservent leur valeur enregistrée sans erreur. Sans chatbot IA activé, les valeurs enregistrées de ai_search_display_mode, ai_search_aside_position et ai_search_enabled: true sont également conservées.

Limites de la liste

• Chaque liste peut contenir jusqu'à 100 entrées, de même que chaque liste links ou groups à l'intérieur.

• L'ensemble des listes peut contenir jusqu'à 3 000 entrées, en comptant les entrées imbriquées et les listes stockées que votre corps ne prend pas en compte.

Le bouton de contact active le formulaire de contact.

Lorsque show_contact_us_button est true sur un forfait avec personnalisation avancée, chaque mise à jour de la marque active le formulaire de contact du centre d'aide, comme le fait un enregistrement dans le tableau de bord. Consultez la section « Formulaire de contact » de la documentation « Mise à jour des paramètres du centre d'aide avec l'API Notiondesk » .

Choisissez un thème

La liste contient toujours tous les thèmes dans une seule réponse, dans l'ordre d'affichage. Appliquez-en un en envoyant son code comme theme :

La définition d'un thème nécessite une personnalisation avancée. L'envoi de "theme": null laisse le thème inchangé.

Erreurs

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

Les erreurs de champ indiquent la valeur, par exemple colors.primary ou footer_links[0].links. Voir Gestion des erreurs d'API, des limites de débit et des nouvelles tentatives Notiondesk .

Questions fréquentes

Et ensuite ?

• Mettez à jour les paramètres du centre d'aide avec l'API Notiondesk

• Gérez les intégrations du centre d'aide avec l'API Notiondesk

• Automatisez les tâches courantes du centre d'assistance grâce à l'API Notiondesk