API Reference

Full reference for every method, option, and return type exposed by the ChWebSdk object on community pages.

DOM and lifecycle

onReady(callback)

Run a callback when the DOM is ready. If the document is already loaded (complete or interactive), the callback runs immediately; otherwise it runs on DOMContentLoaded.

ChWebSdk.onReady(() => {
  // Safe to use DOM and SDK
})

observeElement(selector, callback)

Wait until an element matching selector appears in the DOM, then run callback with that element. Uses a MutationObserver and disconnects after the element is found.

ChWebSdk.observeElement('#my-widget-root', (el) => {
  el.textContent = 'Widget loaded'
})

onEvent(selector, event, handler, options?)

Bind an event listener to the first element that matches selector (waiting for it via observeElement if needed). Returns an unsubscribe function to remove the listener.

Parameter	Type	Description
selector	string	CSS selector for the target element
event	string	DOM event name (e.g. 'click', 'submit')
handler	function	Event handler
options	boolean | AddEventListenerOptions	Optional; e.g. { once: true }

const unsubscribe = ChWebSdk.onEvent('.submit-btn', 'click', (ev) => {
  ev.preventDefault()
  // ...
})
// Later: unsubscribe() to remove the listener

loadScript(src, callback?)

Load an external script by URL. If the script is already present, calls callback when appropriate. Scripts are loaded with async: true.

ChWebSdk.loadScript('https://example.com/plugin.js', () => {
  console.log('Script loaded')
})

loadStyle(href)

Inject a stylesheet link. No-op if a link with the same href already exists.

ChWebSdk.loadStyle('https://example.com/widget.css')

---

Content API

The Content API provides typed access to community content (articles, questions, conversations, ideas, product updates), search, and actions like like, unlike, vote, and unvote.

Content types and instances

Get a content instance for a specific type. Pass an optional private topic ID when you need to perform actions (like, unlike, vote, etc.) on a specific topic.

Method	Description
Content.Article(privateId?)	Knowledge base articles
Content.Question(privateId?)	Community questions
Content.Conversation(privateId?)	Conversations / discussions
Content.Idea(privateId?)	Ideation topics
Content.ProductUpdate(privateId?)	Product updates

// Search only ideas (no privateId needed)
const ideaInstance = ChWebSdk.Content.Idea()
const ideas = await ideaInstance.search('feature request', { limit: 10 })

// Like a specific idea (privateId required)
const idea = ChWebSdk.Content.Idea(12345)
await idea.like()  // uses current logged-in user

Content instance methods

When created with a privateId, an instance supports:

Method	Description
like(likedBy?)	Like the topic. likedBy defaults to current user.
unlike(unlikedBy?)	Unlike the topic.
vote(votedBy?)	Vote (e.g. for ideas).
unvote(unvotedBy?)	Remove vote.
likeReply(replyId, likedBy?)	Like a reply.
unlikeReply(replyId, unlikedBy?)	Unlike a reply.
search(query, options?)	Search content of this type only.

All of these require a browser environment and, where applicable, a logged-in user (or an explicit user ID).

Content.search(query, options?)

Search across all content types (no content-type filter). Same options as the per-type search.

const results = await ChWebSdk.Content.search('help with login', {
  limit: 20,
  page: 0,
  fetchMetadata: true
})

Search options

Option	Type	Default	Description
query	string	—	Search query (required).
contentType	string | string[]	—	Filter by type: 'idea', 'ideation', 'article', 'question', 'discussion', 'conversation', 'event', 'productUpdate'.
limit	number	30	Max results per page.
page	number	0	Page index (0-based).
fetchMetadata	boolean	true	When true, enriches results with author, engagement, and topic metadata from the backend.
categoryName	string	—	Filter by community category name (top-level facet).
categoryIds	number[]	—	Filter by category/forum IDs.
kbCategoryName	string	—	Filter by knowledge base category name.
productAreaName	string	—	Filter by product area name.
facetFilters	string[][]	—	Raw facet filters for advanced filtering.

Search result shape

Each result includes at least: id, title, url, contentType, excerpt, and optionally views, likes, votes. When fetchMetadata: true, additional fields such as firstPost, forum, numberOfViews, numberOfReplies, numberOfLikes, hasCurrentUserLiked, ideationStatus, bugStatus, etc. are populated.

---

User API

User.search(query)

Search users by query string. Returns an array of user objects.

Browser-only. Requires a non-empty string query.

const users = await ChWebSdk.User.search('john')

User.getUsersById(ids)

Fetch users by an array of user IDs. Returns an object keyed by user ID.

Browser-only. Requires a non-empty array of IDs.

const usersMap = await ChWebSdk.User.getUsersById(['1', '2', '3'])
const user1 = usersMap['1']

User object shape

Each user includes: id, url, name, avatar, userTitle, userLevel, badges, isBanned, and optional rank (with name, color, icon, etc.).

---

Subscription API

All subscription methods are browser-only and require valid identifiers.

Topics

Method	Description
Subscription.subscribeTopic(publicId)	Subscribe to a topic by its public ID.
Subscription.unsubscribeTopic(publicId)	Unsubscribe from a topic.
Subscription.getTopicSubscriptionStatus(publicId)	Returns true if the current user is subscribed.

Categories

Method	Description
Subscription.subscribeToCategory(categoryId)	Subscribe to a category (ID as string).
Subscription.unsubscribeFromCategory(categoryId)	Unsubscribe from a category.
Subscription.getCategorySubscriptionStatus(categoryId)	Returns true if the current user is subscribed to the category.

await ChWebSdk.Subscription.subscribeTopic('topic-123')
const isSubscribed = await ChWebSdk.Subscription.getTopicSubscriptionStatus('topic-123')

await ChWebSdk.Subscription.subscribeToCategory('42')
const subscribedToCategory = await ChWebSdk.Subscription.getCategorySubscriptionStatus('42')

---

Error handling

SDK methods that call the backend or DOM throw on failure. Use try/catch and handle missing or invalid arguments.

try {
  const users = await ChWebSdk.User.search('john')
  console.log(users)
} catch (err) {
  console.error('User search failed:', err.message)
}

Common cases:

Scenario	Cause
"can only be called in a browser environment"	Method was run in Node or an environment without window.
"Search query is required" / "User IDs array is required"	Missing or invalid arguments.
"privateId is required for this operation"	Content action (like, vote, etc.) was called on an instance created without a private ID.
"User must be logged in or provide a userId"	Like/vote/unvote used without a logged-in user or explicit ID.
HTTP/network errors	Backend request failed (e.g. subscription, search, user fetch).

---