How to Embed the HitlChat Inbox in Your CRM or App

The embed URL

Everything is driven by one URL — the inbox page plus query parameters. This is the value you put in your iframe’s src.

A minimal embed that simply hides the HitlChat top banner looks like this:

<iframe
  src="https://portal.hitlchat.io/chat-data?hidetopbanner=true&agency=acme"
  style="width:100%;height:100%;border:0;"
  allow="microphone; camera; clipboard-write">
</iframe>

Add or remove parameters from the next section to get the exact layout you want. Throughout this guide we use a demo agency code of acme — swap in your own.

The embed parameters

Append these to the URL with ? for the first and & between the rest. The order doesn’t matter, and a parameter is only active when its value is exactly true.

Display

• hidetopbanner=true — hides the top navigation banner (the HitlChat menu bar). This is the key one for a native feel.
• hideleftmenu=true — hides the left panel. On the inbox that panel is the conversation list, so use this when your own app provides the contact navigation.
• hidecontactdetails=true — hides the right-hand contact details sidebar.

Targeting

• conversation=<value> — opens a single conversation. Accepts the customer’s WhatsApp number (international format, digits only) or the conversation’s internal id. See Use case 3.

Branding

• agency=<your-agency-code> — applies your agency logo and brand colour to the login screen. See Branding the login screen.

Use case 1 · A full embedded inbox

The most common setup: show the complete shared inbox — conversation list on the left, the live chat in the middle, and contact details on the right — but drop the HitlChat top menu so it sits seamlessly inside your product. You hide only the top banner:

Your users get a fully functional WhatsApp team inbox — switching conversations, replying, assigning, viewing contact info — that looks like part of your own application.

Team inbox mode: the full bannerless inbox embedded inside a CRM, with the conversation list and contact details still visible.

Use case 2 · Trim the panels

If your own app already provides navigation or you want a more focused view, hide the side panels too. Mix and match the three display parameters:

# Inbox with the conversation list, but no contact-details sidebar
.../chat-data?hidetopbanner=true&hidecontactdetails=true&agency=acme

# Just the chat thread — no top banner, no list, no details
.../chat-data?hidetopbanner=true&hideleftmenu=true&hidecontactdetails=true&agency=acme

Use case 3 · One contact’s conversation

This is the powerful one for CRMs. When a user opens a contact’s record in your app, build an iframe that loads only that contact’s WhatsApp conversation — no list, no menus. Hide the left panel and pass the contact’s number in the conversation parameter:

Generate the src dynamically from the contact your user clicked:

// e.g. when rendering a contact's "Messages" tab in your CRM
const number = contact.whatsappNumber; // digits only, e.g. "447700900123"
const src =
  "https://portal.hitlchat.io/chat-data" +
  "?hidetopbanner=true&hideleftmenu=true" +
  "&conversation=" + number +
  "&agency=acme";
iframe.src = src;

The conversation value accepts the customer’s WhatsApp number (international format, digits only — no + or spaces) or the conversation’s internal id. HitlChat opens that thread even if it isn’t in the most recent list, and only ever resolves conversations belonging to the signed-in account.

Contact-specific mode: clicking a contact in the CRM loads only that customer’s conversation, with the list hidden.

Branding the login screen for your agency

If an embedded user isn’t signed in yet, the iframe shows the HitlChat login screen. Add the agency parameter and that login screen is white-labelled with your agency’s logo and brand colour instead of HitlChat’s:

The agency value can be your agency code (e.g. acme) or your agency’s record id. You’ll find these in your agency settings. The same value works on the embed URL, so you only ever set it once.

After the user logs in, HitlChat sends them straight back to the bannerless inbox they were heading to — every embed parameter (including a conversation deep-link) is preserved through login, so they land exactly where you intended.

Staying logged in inside the iframe

An embedded inbox is meant to behave like a permanent panel in your app, so HitlChat treats it differently from a normal browser tab: when the inbox is loaded in embed mode (any hide parameter present), the usual 2-hour inactivity auto-logout is switched off. Your users sign in once and the panel stays connected.

The sign-in itself is long-lived, so in practice users won’t be bounced back to the login screen during normal use. They’ll only need to log in again if they explicitly log out, or if they sign in to the same account somewhere else (which ends the older session).