> ## Documentation Index
> Fetch the complete documentation index at: https://tinytalk.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Reference

> Programmatic control, events, and advanced usage of the Tiny Talk SDK.

## SDK methods

After the SDK loads (via [script embed](/install#script-embed-recommended) or [ES module](/install#es-module-embed)), a global `window.tinytalk` object is available for programmatic control.

| Method     | Description                                         |
| ---------- | --------------------------------------------------- |
| `toggle()` | Opens the messenger if hidden, closes it if visible |

<Info>
  More methods will be added soon.
</Info>

### toggle()

```html theme={null}
<button onclick="window.tinytalk.toggle()">
  Chat with us
</button>
```

## PostMessage events

The messenger emits events via [`postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) that you can listen to from the parent page. This lets you react to user actions — for example, tracking conversions, triggering analytics, or showing a confirmation.

### Listening for events

```js theme={null}
window.addEventListener('message', (event) => {
  if (event.origin !== 'https://dashboard.tinytalk.ai') return;

  console.log(event.data.type); // e.g. "messenger.chat.sendMessage"
});
```

<Warning>
  Always check `event.origin` before acting on postMessage events to avoid processing messages from untrusted sources.
</Warning>

### Available events

| Event                                | Description                                    |
| ------------------------------------ | ---------------------------------------------- |
| `messenger.home.newConversation`     | New conversation started from the Home tab     |
| `messenger.messages.newConversation` | New conversation started from the Messages tab |
| `messenger.chat.sendMessage`         | Message sent in the chat                       |
| `messenger.home.close`               | Messenger closed from the Home tab             |
| `messenger.messages.close`           | Messenger closed from the Messages tab         |
| `messenger.chat.close`               | Messenger closed from the Chat tab             |
| `messenger.chat.leadFormFieldFilled` | A lead form field was filled in                |
| `messenger.chat.leadFormSubmitted`   | Lead form was submitted                        |

### Example: track new conversations

```js theme={null}
window.addEventListener('message', (event) => {
  if (event.origin !== 'https://dashboard.tinytalk.ai') return;

  if (event.data.type === 'messenger.chat.leadFormSubmitted') {
    // Send to your analytics
    analytics.track('lead_captured');
  }
});
```

## Styling and Shadow DOM

The messenger widget renders inside a [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM). This means:

* **Your page's CSS cannot override the messenger's styles** — custom stylesheets, global resets, and CSS frameworks like Tailwind or Bootstrap will not affect the widget.
* **The messenger's styles won't leak into your page** — no risk of conflicts with your existing design.

This is by design. The Shadow DOM boundary ensures the messenger looks and works the same on every site, regardless of what CSS is loaded on the page.

To customize the messenger's appearance (colors, launcher icon, welcome message, etc.), use the settings under **Messenger → Appearance**.

## Live demo

See the SDK in action — script embed, iframe embed, toggle button, and postMessage events — in this interactive CodePen:

<Card title="Tiny Talk Demo" icon="codepen" href="https://codepen.io/tinytalk/pen/BaeWpZz">
  Live example with messenger widget, iframe embed, and event listeners.
</Card>