Dostosuj branding i motywy centrum pomocy za pomocą interfejsu API Notiondesk

Interfejs API Notiondesk umożliwia odczytywanie i zmianę identyfikacji wizualnej centrum pomocy: kolorów, czcionek, układu, nagłówka i stopki, linków, wyświetlania wyszukiwania i opinii oraz motywu. Można go używać do wdrażania tej samej identyfikacji wizualnej w kilku centrach pomocy lub do przechowywania identyfikacji wizualnej w kodzie obok reszty systemu projektowego.

Branding jest widoczny na każdej stronie publicznej, więc jego aktualizacja wymaga zakresu admin, a nie write. Tylko klucz utworzony przez właściciela lub administratora obszaru roboczego zawiera zakres admin.

Aby zmienić markę na pulpicie nawigacyjnym, zapoznaj się z sekcją Dostosowywanie kolorów i czcionek centrum pomocy .

Czego API nie zmienia

Pozostają one dostępne tylko na pulpicie. Trasa odczytu ich nie zwraca, a aktualizacja, która nadaje nazwę jednemu z nich, odpowiada 400 validation_error:

• Niestandardowy CSS i niestandardowy JavaScript. Zobacz Dostosowywanie centrum pomocy za pomocą niestandardowego CSS ;

• loga (jasne i ciemne), loga stopki (jasne i ciemne), ikona favicon, obrazy do mediów społecznościowych i obrazy nagłówka (jasne i ciemne).

Przeczytaj swoją markę

Odpowiedź zawiera dokładnie te pola, które akceptuje aktualizacja, pod tymi samymi nazwami. Skrócony przykład:

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
}

• Kolor, który nigdy nie został ustawiony, to "". colors.dark zawiera kolory trybu ciemnego i jest nieobecny, gdy centrum pomocy nie ma ciemnej palety.

• Lista, która nic nie zawiera, ma postać [].

• theme to code bieżącego motywu lub null.

Zaktualizuj swoją markę

Trasa odpowiada 204 No Content. Przeczytaj ponownie oznakowanie, aby potwierdzić zmianę.

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

• Pominięte pole zachowuje swoją wartość. Wewnątrz colors pominięty kolor również zachowuje swoją wartość.

• Lista, którą wysyłasz, zastępuje całą zapisaną listę, a [] ją opróżnia.

• Kolory to wartości szesnastkowe #rrggbb lub "". Krótkie formy, takie jak #fff, są odrzucane.

• Wyślij wartości logiczne JSON. Wartości 0 i "false" są odczytywane jako true, a null jako false.

Każda zaakceptowana aktualizacja odświeża całe centrum pomocy: Notiondesk czyści strony z pamięci podręcznej i odbudowuje każdą stronę, niezależnie od zmian wprowadzonych przez aktualizację. Wysyłaj każdą zmianę w jednym żądaniu, a nie osobno dla każdego pola.

Bezpieczne aktualizacje: przeczytaj, zmień, odeślij

Najbezpieczniejszym sposobem aktualizacji brandingu jest odesłanie odczytanych danych z zastosowanymi zmianami. Pole wysłane z aktualną wartością jest akceptowane w dowolnym planie, więc ten wzorzec nigdy nie powoduje przekroczenia limitu planu dla pól, których nie zmieniono.

Odesłane ciało nadal może zostać odrzucone w dwóch przypadkach. Popraw wartość w panelu lub pomiń to pole w ciele:

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

• zapisany kolor w skróconej formie, np. #fff;

• lista przechowywanych danych jest dłuższa niż podane poniżej limity.

Pola, które możesz zmienić

Linki to obiekty z atrybutem title i url. Grupy linków stopki to obiekty z listą title i links. Tłumaczenia to obiekty z atrybutem locale i przetłumaczonymi links, groups lub value.

Limity planu

Zmiana jednego z nich w planie bez funkcji odpowiada na kod 403 permission_denied, komunikat podaje nazwę funkcji i nic nie zostaje zapisane.

Bez zaawansowanej personalizacji kolory stopki zachowują swoją wartość bezbłędnie. Bez włączonego chatbota AI kolory ai_search_display_mode, ai_search_aside_position i ai_search_enabled: true również zachowują swoją wartość.

Limity listy

• Każda lista może pomieścić do 100 wpisów, podobnie jak każda lista links lub groups w jej obrębie.

• Wszystkie listy łącznie mogą pomieścić do 3000 wpisów, wliczając wpisy zagnieżdżone i listy przechowywane, których nie zawiera treść.

Przycisk kontaktu włącza formularz kontaktowy

Chociaż show_contact_us_button jest true w planie z zaawansowaną personalizacją, każda aktualizacja brandingu włącza formularz kontaktowy w centrum pomocy, podobnie jak zapisanie zmian w panelu. Zapoznaj się z sekcją dotyczącą formularza kontaktowego w artykule Aktualizacja ustawień centrum pomocy za pomocą interfejsu API Notiondesk .

Wybierz motyw

Lista zawsze zawiera każdy temat w jednej odpowiedzi, w kolejności wyświetlania. Aby zastosować jeden z nich, wyślij jego code jako theme:

Ustawienie motywu wymaga zaawansowanej personalizacji. Wysłanie "theme": null pozostawia motyw bez zmian.

Błędy

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

Błędy pola określają nazwę wartości, na przykład colors.primary lub footer_links[0].links. Zobacz Obsługa błędów API Notiondesk, limitów szybkości i ponownych prób .

Często zadawane pytania

Co dalej?

• Zaktualizuj ustawienia centrum pomocy za pomocą interfejsu API Notiondesk

• Zarządzaj integracjami centrum pomocy z interfejsem API Notiondesk

• Zautomatyzuj typowe zadania centrum pomocy za pomocą interfejsu API Notiondesk