Developers — AwnCare

Install

Add one script tag with your workspace id. The widget mounts itself in an isolated Shadow DOM, so it never clashes with your page styles.

Script tag

The simplest install — paste this before the closing body tag.

html

<script
  src="https://awn.care/widget/awncare.js"
  data-workspace-id="YOUR_WORKSPACE_ID"
  async>
</script>

Async command queue

Define a small stub before the SDK loads so calls made early are buffered and replayed once the widget mounts.

html

<script>
  window.AwnCare = window.AwnCare || function () {
    (AwnCare.q = AwnCare.q || []).push(arguments);
  };
</script>
<script
  src="https://awn.care/widget/awncare.js"
  data-workspace-id="YOUR_WORKSPACE_ID"
  async>
</script>

<script>
  // Safe to call immediately — queued until the widget mounts.
  AwnCare("identify", { email: "[email protected]", name: "Sara" });
  AwnCare("on", "ready", function () {
    console.log("AwnCare widget ready");
  });
</script>

Prefer window.awncareSettings or data-* attributes for configuration — an explicit setting always wins over the matching data attribute.

Configuration

Set window.awncareSettings before the SDK loads to configure the boot. These override the script tag's data-* attributes.

Field	Type	Description
`workspaceId`	`string`	Your workspace id. Required unless supplied via data-workspace-id.
`locale`	`"ar" \| "en"`	Initial UI language of the widget.
`position`	`"bottom-right" \| "bottom-left"`	Which corner the launcher sits in.
`color`	`string`	Launcher and accent color (any CSS color).
`zIndex`	`number`	Stacking order of the widget host. Defaults to the maximum.
`hideLauncher`	`boolean`	Start with the launcher hidden; reveal it later with AwnCare.show().
`baseUrl`	`string`	Override the API origin the widget talks to.

html

<script>
  window.awncareSettings = {
    workspaceId: "YOUR_WORKSPACE_ID",
    locale: "ar",              // "ar" | "en"
    position: "bottom-left",   // "bottom-right" | "bottom-left"
    color: "#0F766E",          // launcher / accent color
    zIndex: 2147483000,
    hideLauncher: false,       // start hidden, reveal later with AwnCare.show()
    baseUrl: "https://awn.care"
  };
</script>
<script src="https://awn.care/widget/awncare.js" async></script>

API reference

Every method available on window.AwnCare. Methods called before the widget finishes mounting are queued and replayed automatically.

`version: string`

The SDK semantic version string, e.g. "1.0.0".

console.log(AwnCare.version); // "1.0.0"

`open(): void`

Open the chat window.

AwnCare.open();

`close(): void`

Close the chat window.

AwnCare.close();

`toggle(): void`

Toggle the chat window open or closed.

AwnCare.toggle();

`isOpen(): boolean`

Returns true when the chat window is currently open.

if (!AwnCare.isOpen()) {
  AwnCare.open();
}

`sendMessage(text: string): void`

Send a message from the visitor into the active conversation.

// Sends a message from the visitor into the active conversation.
AwnCare.sendMessage("مرحبًا، أحتاج مساعدة في طلبي");

`setUser(data): void`

Set lightweight session attributes (name, email, and any extra keys) for the current visitor.

// Lightweight attributes for the current session (name/email + extras).
AwnCare.setUser({
  name: "Sara Al-Otaibi",
  email: "[email protected]",
  plan: "pro"
});

`identify(data: IdentifyData): void`

Persist contact traits to the server visitor record so agents see who they are talking to.

// Persist contact traits to the server visitor record.
AwnCare.identify({
  externalId: "usr_10294",
  name: "Sara Al-Otaibi",
  email: "[email protected]",
  phone: "+966500000000",
  company: "Acme",
  metadata: { plan: "pro", mrr: 199 }
});

`on(event, callback): void`

Subscribe to a widget event with a callback.

function onAgentReply(payload) {
  console.log("Agent said:", payload.text);
}
AwnCare.on("message:received", onAgentReply);

`off(event, callback?): void`

Remove a specific listener, or every listener for an event when no callback is passed.

// Remove one listener…
AwnCare.off("message:received", onAgentReply);
// …or every listener for an event:
AwnCare.off("message:received");

`setLocale(locale: "ar" | "en"): void`

Switch the widget UI language at runtime.

AwnCare.setLocale("en"); // switch the widget UI to English at runtime

`getUnreadCount(): number`

Return the current unread message badge count.

const badge = AwnCare.getUnreadCount(); // e.g. 3

`hide(): void`

Remove the widget from view entirely (host element hidden).

AwnCare.hide(); // remove the widget from view entirely

`show(): void`

Restore the widget after hide(); also reveals a launcher started with hideLauncher.

AwnCare.show(); // restore it (also reveals a hidden launcher)

`destroy(): void`

Unmount the widget and remove it from the DOM.

AwnCare.destroy(); // unmount and remove the widget from the DOM

`logout(): void`

Clear the current visitor identity — use on sign-out to start a fresh session.

// Clear the current visitor identity (e.g. on app sign-out).
AwnCare.logout();

`trackEvent(name, data?): void`

Record a custom visitor event with optional data for context and automations.

// Record a custom visitor event for context / automations.
AwnCare.trackEvent("checkout_started", { cart: 2, total: 349 });

identify() data

The traits accepted by AwnCare.identify(). All fields are optional; provide what you know.

Field	Type	Description
`name`	`string`	The contact's display name.
`email`	`string`	The contact's email address.
`phone`	`string`	The contact's phone number.
`externalId`	`string`	A stable id from your own system to link this contact.
`company`	`string`	The contact's company name.
`metadata`	`Record<string, unknown>`	Any additional custom traits, merged into the visitor record.

Events

Subscribe with AwnCare.on(name, callback). Handlers receive the payload shown below.

Event	Payload	Description
`ready`	`—`	Fires once the widget has mounted and is ready to use.
`open`	`—`	Fires when the chat window opens.
`close`	`—`	Fires when the chat window closes.
`message`	`Message`	Legacy alias — fires for every agent or bot message, with the full message object.
`message:received`	`{ text, sender: "agent" \| "bot" }`	Fires when an agent or bot message arrives.
`message:sent`	`{ text }`	Fires when the visitor sends a message.
`conversation:started`	`{ conversationId }`	Fires when a new conversation is created.
`unread`	`number`	Fires when the unread badge count changes.

`ready`

AwnCare.on("ready", function () {
  console.log("Widget mounted and ready");
});

`open`

AwnCare.on("open", function () {
  console.log("Chat window opened");
});

`close`

AwnCare.on("close", function () {
  console.log("Chat window closed");
});

`message`

// Legacy alias — fires for every agent/bot message (full message object).
AwnCare.on("message", function (message) {
  console.log(message.body, message.sender);
});

`message:received`

AwnCare.on("message:received", function (payload) {
  // payload: { text: string, sender: "agent" | "bot" }
  console.log(payload.sender, "→", payload.text);
});

`message:sent`

AwnCare.on("message:sent", function (payload) {
  // payload: { text: string }
  console.log("Visitor sent:", payload.text);
});

`conversation:started`

AwnCare.on("conversation:started", function (payload) {
  // payload: { conversationId: string }
  console.log("New conversation:", payload.conversationId);
});

`unread`

AwnCare.on("unread", function (count) {
  // count: number — the current unread badge value
  document.title = count > 0 ? "(" + count + ") Support" : "Support";
});