> For the complete documentation index, see [llms.txt](https://popin.gitbook.io/popin-developer-hub/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://popin.gitbook.io/popin-developer-hub/implementation-document-popin-agent-widget.md).

# Implementation Document — Popin Agent Widget

### 1. Purpose

This document explains how a sample page:

* Loads the Popin Agent widget
* Initializes it
* Opens it via a custom button
* Handles widget events

***

### 2. Configuration & Secrets

| Item                 | Location in Code                       | Notes                                                   |
| -------------------- | -------------------------------------- | ------------------------------------------------------- |
| Widget Script URL    | Inline `<script>` before `</body>`     | Set via `popIn.setAttribute("src", ...)`                |
| Init Identity / PIN  | `popInAgentWidgetInit("email", "pin")` | PIN is obtained from the Popin dashboard                |
| User Context on Open | `PopinAgent("open", { name, mobile })` | Replace demo PII with real user/session data per policy |

***

### 3. Implementation Details

#### 3.1 Script Injection

* A `<script>` element is dynamically created
* `src` is set to the Popin Agent script
* Script is appended to `document.body`
* Initialization runs on script load

```
<script>
  let popIn = document.createElement("script");
  popIn.setAttribute(
    "src",
    "https://widget01.popin.to/js/agent.js"
  );

  document.body.appendChild(popIn);

  popIn.onload = () => {
    popInAgentWidgetInit("anubahv.jaiswal@popin.to", "0000");
  };
</script>
```

***

#### 3.2 Launcher UI

* A `<button>` triggers the widget
* On click, `PopinAgent("open", {...})` is called

```
<script>
  window.popinAgentEvent = (event, data) => {
    console.log("popinAgentEvent");
    console.log(event, data);
  };

  document.addEventListener("DOMContentLoaded", () => {
    document
      .getElementById("popin-button")
      .addEventListener("click", () => {
        PopinAgent("open", {
          name: "Anubahv Jaiswal",
          mobile: "9876543210",
        });
      });
  });
</script>
```

***

#### 3.3 Event Callback

* `window.popinAgentEvent` receives events from the widget
* Example use case: handle `call_initiated` event
* Event data may contain a joining URL

```
window.popinAgentEvent = (event, data) => {
  if (event === "call_initiated") {
    console.log("Join URL:", data?.joining_url);
  }
};
```

***

### 4. User Flow

1. User opens the page
2. Page loads → Popin script is requested
3. Script loads → `popInAgentWidgetInit` runs → widget becomes ready
4. User clicks `#popin-button`
5. `PopinAgent("open", …)` executes → widget opens with user data
6. Widget emits events → `popinAgentEvent` handles them (currently logs to console)