Methods · TruCom Developers

Call conventions

Most action methods return promises. on, off and getState are synchronous. Unknown methods reject. Calls from the full bootstrap queue preserve command order. You can also use trucom(method, ...args) for the same public commands.

JavaScript

try {
  await TruComWidget.open();
} catch (error) {
  console.error(error.code, error.message, error.details);
}

ready()

Wait for the loader and iframe handshake. Resolves to the current public state. Times out after 30 seconds if the widget cannot connect.

JavaScript

const state = await TruComWidget.ready();

configure(options)

Validate and apply runtime options. Resolves { configured: true }. Initial-only properties reject after frame creation.

JavaScript

await TruComWidget.configure({ color: '#111111', offsetX: 32 });

open()

Open the panel. Active sessions resume; an ended latest conversation opens Home. A hidden or unavailable widget rejects.

JavaScript

await TruComWidget.open();

close()

Minimize the panel without ending its conversation. Resolves { closed: true }.

JavaScript

await TruComWidget.close();

show() / hide()

Show or hide this installation. hide minimizes an open panel first. Device-specific hide preferences still apply.

JavaScript

await TruComWidget.hide();
await TruComWidget.show();

showLauncher() / hideLauncher()

Show or hide the default launcher without ending a conversation. Your own support button can still call open(). A configured hideLauncher stays respected.

JavaScript

await TruComWidget.hideLauncher();

navigate(view, options)

Views: home, messages, help, conversation. A conversation ID must belong to this visitor. Hidden sections reject with section_hidden.

JavaScript

await TruComWidget.navigate('help');
await TruComWidget.navigate('conversation', { conversationId: 'AUTHORIZED_ID' });

startConversation(options)

Open a new conversation draft, respecting pre-chat and consent. The conversation is stored when its first message is sent. Optional draft and departmentId are supported; departments must be available and selection enabled. Resolves conversationId and preChatRequired.

JavaScript

await TruComWidget.startConversation({ draft: 'I need help with my order' });

setDraft(text)

Prefill the composer without sending. Text is limited to 10,000 characters.

JavaScript

await TruComWidget.setDraft('Could you help me with order 204?');

sendMessage(text)

Send explicitly through the current visitor session. If details or consent are needed, displays pre-chat, preserves the draft and rejects with prechat_required. Complete the form, then send again. Offline API sends reject instead of claiming a message was sent. The regular widget UI retains its offline outbox.

JavaScript

const result = await TruComWidget.sendMessage('Hello, could you help me?');

endConversation(options)

Default confirm:true opens the end confirmation and resolves { confirmationRequired:true, ended:false }. The conversation.ended event fires after the visitor confirms. confirm:false ends immediately through the server. Requires an active conversation and the workspace capability.

JavaScript

await TruComWidget.endConversation();
// For your own explicit End support conversation button:
await TruComWidget.endConversation({ confirm: false });

requestHuman()

Request the support team on an active conversation. Preserves the draft and selected files. Existing handoff requests remain idempotent.

JavaScript

await TruComWidget.requestHuman();

identify(data)

Pass name, email, phone, company, optional attributes, or a backend-issued identity_token (identityToken is an alias). Resolves identified, verified and visitorId. Signed claims remain authoritative.

JavaScript

await TruComWidget.identify({ name: 'John Doe', attributes: { plan: 'Business' } });

setAttributes(attributes)

Merge website context into the current session. null removes a key. Resolves the resulting attributes object.

JavaScript

await TruComWidget.setAttributes({ last_order_id: 'ORD-204' });

reset()

Revoke and clear the current visitor session locally. Call on logout or account switching. This is not account deletion.

JavaScript

await TruComWidget.reset();

setLanguage(code)

Update the interface language and locale formatting. See Localization for built-in translations and label overrides.

JavaScript

await TruComWidget.setLanguage('fr');

setCustomCss(css) / setLauncherCss(css)

Update the isolated panel or launcher stylesheet for this page. The saved workspace CSS is restored on a new page unless overridden again.

JavaScript

await TruComWidget.setCustomCss('[data-tc-part="header"] { border-bottom: 1px solid #ddd; }');

on(event, callback) / off(event, callback)

Subscribe synchronously. on returns an unsubscribe function. off without a callback removes all listeners for that event. The wildcard * receives all SDK events. Late ready listeners are called once with current state.

JavaScript

const stop = TruComWidget.on('open', event => console.log(event.type));
stop();

getState()

Read the latest public state synchronously. Call ready first when your logic depends on initialized values. Does not expose tokens, full profiles or message contents.

JavaScript

const state = TruComWidget.getState();

destroy()

Remove the installation, iframe, extension, timers and listeners from this page. Pending commands reject with widget_destroyed. Does not revoke the stored visitor session; reset first when signing out.

JavaScript

await TruComWidget.destroy();

receiveNativeCommand(command)

Opt-in native bridge entry point. Accept an object or JSON string with id, method and args. Sends correlated result/error envelopes to the configured app bridge. See Mobile apps.

JavaScript

await TruComWidget.receiveNativeCommand({ id: 'open-1', method: 'open', args: [] });