Personalizza il branding e i temi del centro assistenza con l'API Notiondesk

L'API Notiondesk consente di leggere e modificare l'immagine coordinata del centro assistenza: colori, caratteri, layout, intestazione e piè di pagina, collegamenti, visualizzazione della ricerca e del feedback e tema. Utilizzala per implementare lo stesso marchio in diversi centri assistenza o per mantenere l'immagine coordinata nel codice insieme al resto del sistema di progettazione.

Il branding è visibile su ogni pagina pubblica, quindi per aggiornarlo è necessario l'ambito admin, non write. Solo una chiave creata dal proprietario di un'area di lavoro o da un amministratore detiene admin.

Per modificare il branding nella dashboard, consulta la sezione Personalizzare i colori e i caratteri del centro assistenza .

Ciò che l'API non cambia

Questi rimangono solo nella dashboard. Il percorso di lettura non li restituisce e un aggiornamento che ne nomina uno risponde 400 validation_error:

• CSS personalizzato e JavaScript personalizzato. Vedi Personalizzare il centro assistenza con CSS personalizzato ;

• loghi (chiaro e scuro), loghi a piè di pagina (chiaro e scuro), favicon, immagine per i social media e immagini di intestazione (chiaro e scuro).

Leggi il tuo marchio

La risposta contiene esattamente i campi accettati dall'aggiornamento, con gli stessi nomi. Ecco un esempio abbreviato:

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 colore che non è mai stato impostato è "". colors.dark contiene i colori della modalità scura ed è assente quando il centro assistenza non ha una tavolozza scura.

• Un elenco vuoto si legge [].

• theme è il code del tema corrente, ovvero null.

Aggiorna il tuo marchio

Il percorso risponde 204 No Content. Rileggi il branding per confermare la modifica.

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 che ometti mantiene il suo valore. All'interno di colors, anche un colore che ometti mantiene il suo valore.

• Un elenco inviato sostituisce l'intero elenco memorizzato e [] lo svuota.

• I colori sono valori esadecimali #rrggbb o "". Le forme abbreviate come #fff vengono rifiutate.

• Invia valori booleani JSON. I valori 0 e "false" vengono letti come true, e null come false.

Ogni aggiornamento accettato aggiorna l'intero centro assistenza: Notiondesk cancella le pagine memorizzate nella cache e ricostruisce ogni pagina, indipendentemente dalle modifiche apportate dall'aggiornamento. Invia ogni modifica in un'unica richiesta, non una richiesta per ogni campo.

Aggiornamenti sicuri: leggi, modifica, rimanda indietro

Il modo più sicuro per aggiornare il branding è inviare nuovamente il testo letto, con le modifiche apportate. Un campo inviato con il suo valore attuale è accettato da qualsiasi piano, quindi questo schema non supera mai i limiti del piano per i campi che non sono stati modificati.

Un corpo della risposta può comunque essere rifiutato in due casi. Correggi il valore nella dashboard oppure ometti quel campo dal corpo della risposta:

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 colore memorizzato in forma abbreviata come #fff;

• un elenco memorizzato più lungo dei limiti indicati di seguito.

Campi che è possibile modificare

I collegamenti sono oggetti con un title e un url. I gruppi di collegamenti del piè di pagina sono oggetti con un title e un elenco links. Le traduzioni sono oggetti con un locale e il links, groups o value tradotto.

Piano limite

Modificandone uno su un piano senza la funzionalità, si ottiene l'errore 403 permission_denied, il messaggio indica la funzionalità e non viene scritto nulla.

Senza personalizzazioni avanzate, i colori del piè di pagina mantengono il loro valore memorizzato senza errori. Senza un chatbot AI abilitato, anche ai_search_display_mode, ai_search_aside_position e ai_search_enabled: true mantengono il loro valore memorizzato.

Elenco delle dimensioni

• Ciascun elenco può contenere fino a 100 voci, così come ciascun elenco links o groups al suo interno.

• Tutte le liste insieme possono contenere fino a 3.000 voci, comprese le voci annidate e le liste memorizzate che il tuo corpo esclude.

Il pulsante di contatto attiva il modulo di contatto

Mentre show_contact_us_button è true su un piano con personalizzazione avanzata, ogni aggiornamento del marchio attiva il modulo di contatto del centro assistenza, come avviene con un salvataggio nella dashboard. Consulta la sezione relativa al modulo di contatto in Aggiornare le impostazioni del centro assistenza con l'API Notiondesk .

Scegli un tema

L'elenco contiene sempre tutti i temi in una risposta, nell'ordine di visualizzazione. Applicane uno inviando il suo code come theme:

L'impostazione di un tema richiede una personalizzazione avanzata. L'invio di "theme": null lascia il tema invariato.

Errori

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

Gli errori di campo specificano il valore, ad esempio colors.primary o footer_links[0].links. Vedi Gestione degli errori API, dei limiti di frequenza e dei tentativi di invio per Notiondesk .

Domande frequenti

Cosa succederà dopo?

• Aggiorna le impostazioni del centro assistenza con l'API Notiondesk

• Gestisci le integrazioni del centro assistenza con l'API Notiondesk

• Automatizza le attività comuni del centro assistenza con l'API Notiondesk