Developers7 min readUpdated May 5, 2026

Widget JavaScript API

Reference for loading the widget and passing visitor identity or metadata from the host website.

The widget works with only the script tag. Advanced websites can pass visitor identity and metadata so conversations connect to real customers instead of anonymous contacts.

html

<script
  src="https://staging-widget.tinfiz.com/widget.js"
  data-org-id="YOUR_ORGANIZATION_ID"
  async
></script>

html

<script>
  window.TinfizAI = window.TinfizAI || [];
  window.TinfizAI.push(["identify", {
    externalId: "customer_123",
    name: "Ava Brooks",
    email: "ava@example.com",
    metadata: { plan: "pro", accountStatus: "active" }
  }]);
</script>

Metadata rules

Do not send passwords, secrets, private tokens, payment card data, or sensitive regulated data.
Send stable customer IDs when available so contacts merge correctly.
Keep metadata small and useful for support context.

Future API keys

A public/private key system can later expose server APIs for contacts, conversations, events, webhooks, and action callbacks. Keep widget public identifiers separate from server-side private keys.

Analytics and reporting

Security and production checklist