Huddle help and setup guide

How Huddle works, step by step. Sections 2 to 6 are for clients and their staff. Sections 7 and 8 are for the Huddle company. Section 9 answers common questions. Section 10 covers email and WhatsApp.

1. How Huddle works

There are four levels. Each level controls the one below it.

  HUDDLE OWNER  (the Huddle company)
  Owner dashboard at /owner
  Sees every client, their plan and payments.
  Can extend, change or cancel plans.
        |
        |  sells monthly plans to
        v
  CLIENT WORKSPACE  (one per client business)
  Has one plan, a widget key and inboxes.
  The client's admin pays on the Billing page.
        |
        |  invites
        v
  CLIENT STAFF  (admin, manager, agent, viewer)
  Sign in to the Huddle inbox and answer chats.
        ^
        |  chats appear live in the inbox,
        |  replies appear live in the widget
        v
  WEBSITE VISITORS  (the client's customers)
  Click the chat icon on the client's website.
  Start a new chat or open a previous one.

1. The Huddle company runs one Huddle server.
2. Each client gets their own workspace on that server. Workspaces are fully separate. One client never sees another client's data.
3. The client's admin invites staff into the workspace.
4. The client pastes one line of code on their website. That adds a chat icon.
5. Visitors chat through the icon. Staff answer in the Huddle inbox.
6. The workspace works only while its plan is active. Payments keep it active.

2. Sign up, plans and billing

2.1 Sign up

1. Open your Huddle address (for example https://chat.yourcompany.com).
2. Click Create a workspace.
3. Enter your company name, your name, your email and a password (at least 8 characters).
4. Click to create. You are signed in as the workspace admin.

Your workspace starts on a free trial: 14 days (unless the Huddle owner set another length), 3 seats (people, counting pending invites), 2 inboxes. No card needed.

You can also buy a workspace straight away from the pricing page (/buy.html, linked from the sign-in page): see 2.8.

If you already have a Huddle account, do not sign up again. Sign in and add a workspace: buy one, or start a free trial from Your workspaces or your menu. Each email gets one free trial; a further workspace needs a plan. Switch between workspaces with the workspace switcher.

2.2 Plans

Every plan is billed one month at a time.

These are the demo plans. The Huddle owner can create new plans, change prices, and stop selling a plan, so your pricing page may show others.

A seat is one person in the workspace: every admin, manager, agent and viewer, and every pending invite. An inbox is a team queue, such as "General" or "Billing". Plan details (plan name, price, renewal date, seats, extras, payments and billing notices) are only for the plan owner (who bought the plan) and the managers they allow. Other admins, agents and viewers do not see them anywhere, not even in what the server sends to their browser; they only see whether the workspace is open or locked. The plan owner gives a manager See the plan and billing (read only) or Buy and change the plan (includes seeing it) in Team > Permissions. Many plans let you add extra seats (and sometimes extra storage or websites) without changing plan: see 2.12.

2.3 Buy a plan

1. Open Plan and billing in the app.
2. Pick a plan.
3. Choose how you want to pay:
   • Auto-renew on (the default). You are charged again each month until you cancel.
   • Auto-renew off (one month only). You pay for exactly one month. Access stops when that month ends. Nothing is charged again.
4. Click to pay. You are sent to the payment page.
5. Pay. When the payment provider confirms the payment, your plan becomes active for one calendar month. The Billing page updates by itself.

A month is a calendar month. If you pay on 31 January, the month ends on the last day of February.

2.4 What the Billing page shows

• Your current plan and its status (trial, active, renewing, past due, canceled or expired).
• Whether auto-renew is on.
• The date your access renews or ends.
• Seats used and seats included (for example "4 of 10").
• Your inbox limit.
• What you pay each month in all (plan plus extras), and the next charge.
• A yellow note when your price is about to change, or when your plan is no longer sold and you move to another plan at your next renewal.
• Your extras, with their renewal dates (see 2.12).
• Your payment history: date, plan or extra, amount, and whether each payment succeeded, failed, or was a credit added by Huddle.
• Billing notices: the latest purchases, renewals, failed payments and plan or price changes. They are also emailed to the plan's admins.

2.5 Change plan (upgrade or downgrade)

1. Open Plan and billing.
2. Click Switch to … on the new plan and choose when it starts: Now or When your plan renews.

• Now: the new plan and a new billing month start today. The unused days of your current plan are credited (monthly price × days left ÷ days in the billing month) and come off today's payment. A credit bigger than the new price stays as account credit for your next renewals; nothing is refunded.
• When your plan renews: nothing changes or is charged today; the renewal on your billing date is for the new plan. You can switch now instead, or cancel the change, from the Billing page. Only for plans that renew automatically.
• Buying the same plan again while it is still active adds one month after your current end date. You lose no days.

Fewer inboxes on the new plan: you pick the team inboxes to keep active. The others are paused: nothing is deleted and their chats stay readable, but no new chats arrive there, and their open chats move to the first inbox you keep. Swap them in Settings › Inboxes. A plan with more inboxes turns them back on. Escalation inboxes never count and are never paused.

2.6 Cancel

1. Open Plan and billing.
2. Click Turn off auto-renew.

You keep full access until the end of the month you already paid for. After that the plan expires. No refund is made for the rest of the month. A free trial cannot be cancelled; it simply ends when its days run out.

2.7 Resume

If you cancelled but your month has not ended yet:

1. Open Plan and billing.
2. Click Turn on auto-renew.

Resume works only while the plan is still active (active, renewing or past due), and only for plans bought with automatic renewal. A plan bought for one month only has no saved payment method, so buy another month instead. If the plan has already expired, buy a plan.

2.8 Buy a new workspace

Every purchase from the pricing page makes exactly one new workspace. You can buy as many as you need, for example one per brand or country.

1. Open /buy.html. Signed in, you also find it in the workspace switcher (Buy another workspace) and on Your workspaces.
2. Pick a plan and name the workspace.
3. Leave Renew automatically every month on, or turn it off to buy one month only.
4. Not signed in? Enter your name, email and a password to make your Huddle account. An email that already has an account must sign in first (one account per email).
5. Click Continue to payment and pay.
6. Back on Your workspaces, the page shows "<name> is ready" with an Open button as soon as the payment is confirmed. An email that names the workspace links to it too.

You are the new workspace's plan owner. It has its own address, /w/<workspace id>, that you can bookmark. If the payment fails, no workspace is made and nothing is charged. The workspace is made once, even if the payment provider sends its confirmation more than once.

2.9 One account, several workspaces: the switcher

One email is one Huddle account, with one password and one two-step setting. It can own workspaces and belong to others you were invited to.

• The open workspace is always shown: its initials are in the top-left tile. The plan owner (who bought it) also sees a bar at the top with its name, their role and its plan; admins, managers, agents and viewers do not see the plan there. The browser tab title and desktop notifications include its name.
• Switch by clicking the tile (or the bar, for the plan owner). Each workspace shows your role, its plan (for workspaces you own), a Locked label if its plan ended, and how many open chats are assigned to you there. Ctrl-click (Cmd-click) opens one in a new tab; tabs on different workspaces work side by side.
• Your workspaces (/workspaces.html) lists every workspace and purchase.
• Roles apply per workspace only. You can be an admin in one and an agent or viewer in another. Inbox access, permissions, away mode, availability and email settings are separate too.
• Joining another workspace: an invite to an email that already has an account asks for its existing password (or nothing, if you are signed in) and adds the workspace to your account. Your password is not changed.
• Emails name their workspace and link straight to it.

2.10 Billing is per workspace

Each workspace has its own plan, payments and renewal date. If its plan ends (cancelled and the month ran out, or a renewal failed past the grace period), only that workspace is locked: it is read-only, its website chat is hidden, and a red bar names it with Choose a plan and Export all data. Its data is kept and can always be exported (the JSON export and the CSV downloads on Reports both keep working while locked).

2.11 Security of workspace addresses

The id in a workspace's address is random and long, but it is not a key. The server checks every request against your memberships. A workspace you do not belong to answers "Not found", exactly like one that does not exist.

2.12 Extras: seats, storage and websites

On a paid plan you can add extras on the Plan and billing page, under Extras. Which extras are offered, and their price, depend on your plan.

Your plan has one billing date: the day of the month you bought it (bought on the 10th, it renews on the 10th of every month). Extras follow that date.

How extras are charged:

1. Adding an extra mid-month: you pay only for the days left until your billing date, charged at once. The days are counted with the real length of your billing month (28 to 31 days): price × days left ÷ days in the month. Before you confirm, the page shows the exact amount.
2. From the billing date on, the extra renews with your plan: one charge on your billing date covers the plan and every extra, at the full monthly price.
3. If the part-month comes to less than $1, it is not charged on its own: the extra works at once and the amount is added to your next bill.
4. Cancel stops the extra at your billing date. It keeps working until then. Nothing is refunded. Keep it undoes a cancel before the date.
5. To cancel an extra seat, first make room: remove a member or revoke an invite so everyone fits in the seats you will have.
6. If the payment for a new extra fails, it is not added. If your renewal fails, the plan and its extras keep working during the grace period; if the renewal is never paid, they end together.
7. Without a saved card (a plan bought for one month only), adding an extra sends you to the payment page for the days left. It ends with the plan.

Buy for everyone. Each plan you can buy has For everyone: all N members and invites ticked. The purchase is the plan plus just enough extra seats for every member and pending invite, worked out again when you click Buy. The card shows the sum, for example "5 seats for 5 people: 3 included + 2 extra ($20.00) · $49.00 a month". Extra seats you already pay for count only if they keep renewing. A plan without extra seats and with fewer seats than your team cannot be bought this way.

To choose the number yourself, untick For everyone and type the extra seats under the plan. They are paid for the full month with the plan.

Example. Northwind is on Starter ($29, 3 seats). They bought it on 10 October, so it renews on the 10th. On 25 October they add one extra seat ($10 a month). Their billing month (10 Oct to 10 Nov) has 31 days and 16 are left, so they pay $10 × 16 ÷ 31 = $5.16 on 25 October. On 10 November they pay $39 ($29 + $10), and $39 every month after that.

2.13 Price changes and plans that stop being sold

• If the Huddle owner raises a plan's price, current clients **keep their

price** unless the owner decides to move them. If they do, you are told by email and on the Billing page first, and the new price starts at a renewal at least the notice period away (30 days by default).

• If a plan is suspended (no longer sold), its clients are moved to another

plan chosen by the owner, usually at their next renewal. You are told first and the Billing page shows the new plan and date.

• If a plan is archived, it is no longer sold, but you keep it and it

keeps renewing at your price.

3. Invite staff and set their access

3.1 Roles

• Admin: everything, including billing, widget settings, inboxes, escalation inboxes and other people's permissions.
• Plan owner: the admin who created the workspace and buys its plan, marked "Plan owner" on the Team page. Always has every permission, and nobody can change or remove them. Only the plan owner can make someone an admin.
• Manager: manages agents and viewers and sees reports. Cannot add, change or remove admins or other managers. Sees the plan and billing only when the plan owner allows it. Cannot manage settings or inboxes unless given them.
• Agent: answers and manages conversations.
• Viewer: can read conversations in the inboxes they are given. Cannot reply.

3.2 Permissions table

The role sets the defaults. Rows marked * can be turned on or off for one person by an admin (below). Rows marked ** belong to the plan owner, who can give them to a manager and to nobody else. The Website chat page only appears for people who have one of them.

Who can invite whom:

• The plan owner can invite any role, including admins.
• Other admins can invite managers, agents and viewers.
• Managers can invite agents and viewers, but only after an admin turns on Invite teammates for them. It is off for managers by default.
• Agents and viewers cannot invite anyone. An admin can also turn Invite teammates off for another admin.
• Nobody can change or remove themselves, and nobody can change the plan owner.

3.2.1 Change one person's permissions

Admins only.

1. Open Team.
2. In the Permissions column, click the person's entry ("Role defaults", or for example "2 changes").
3. Tick what they may do and untick what they may not. "Default: on/off" shows what their role gets on its own.
4. Under Escalation inboxes, tick the escalation inboxes they may open.
5. Click Save. Reset to role defaults removes every change for them.

The change applies at once. Huddle checks every permission on the server, so hiding a button is never the only protection. Every change is written to the activity log, for example "Changed Chen Wei's permissions: allowed View reports and stats; restricted Delete macros".

3.3 Inbox access

Each person (except admins) has inbox access: all inboxes, or a list of inboxes you choose. A person sees conversations in the inboxes they can access, plus any conversation in a regular inbox that is assigned to them directly. Admins always see every inbox.

Escalation inboxes (5.2.1) are different: "All inboxes" never includes them. An admin gives each person each escalation inbox by name (Team > Permissions). Being assigned a chat is not enough to open it there.

Access only controls who can read and reply. Anyone allowed to move or escalate chats can send a chat to any inbox, including one they cannot open.

Example: give a part-time agent access to the "Sales" inbox only. They will not see chats in "General" unless one is assigned to them.

3.4 Invite a staff member

You need the Invite teammates permission (the plan owner and admins have it; managers get it from an admin), and your plan must be active.

1. Open Team.
2. Enter the person's email.
3. Pick a role.
4. Pick their inbox access (all inboxes, or a list).
5. Click Send invite.

What happens next:

1. If your Huddle server can send email, the person gets an email with a link. If not, the page shows the link. Copy it and send it to them yourself.
2. They open the link, enter their name and choose a password. If their email already has a Huddle account, they enter their existing password instead and your workspace is added to their account.
3. They are signed in and appear on the Team page for everyone straight away.

Invite links expire after 7 days and work once. You can revoke a pending invite from the Team page. Revoking frees the seat.

3.5 Seat limits

Seats used = every active member (admins, managers, agents and viewers) + pending invites. Seats included = the plan's seats + any extra seats you bought.

• If all seats are used, a new invite is refused with a message such as "Your plan includes 3 seats and all are in use."
• To make room: revoke a pending invite, remove a member, add an extra seat (Plan and billing > Extras), or upgrade your plan.
• Expired invites stop counting automatically.

3.6 Change someone's role or access

1. Open Team.
2. Find the person.
3. Change their role or their inbox access.

The change takes effect straight away. Their inbox refreshes to show only what they may now see.

3.7 Remove a staff member

1. Open Team.
2. Find the person and click Remove.

• They are signed out at once and cannot sign in to this workspace again.
• Their open conversations become unassigned, so the team can pick them up.
• Their past messages stay in the conversation history.
• Their seat is freed.

4. Install the chat widget on your website

4.1 Get your code

1. Sign in to Huddle.
2. Open Website chat.
3. Click Copy code. It looks like this:

<script src="https://YOUR-HUDDLE-HOST/widget.js" data-key="wk_..." async></script>

data-key is your workspace's widget key. It links the chat icon to your workspace. Do not change it.

4.2 Where to paste it

Paste the code just before the closing </body> tag on every page where you want the chat icon. Usually you add it once to a shared template or footer so it appears on every page. It works on any domain.

4.3 Website builders (general steps)

1. Sign in to your website's admin area.
2. Look for a setting such as Custom code, Code injection, Header and footer scripts, Tracking code or Theme code.
3. Choose the option that adds code to every page, at the end of the body (sometimes called "footer" or "before </body>").
4. Paste the Huddle code.
5. Save and publish.

• WordPress: a "header and footer scripts" plugin (paste in the footer box), or your theme's footer.php just before </body>.
• Shopify: Online Store, Themes, Edit code, open theme.liquid, paste just before </body>.
• Wix, Squarespace and similar builders: site settings, custom code or code injection, choose "body end" or "footer", apply to all pages.
• Hand-coded sites: paste before </body> in each page or shared layout.

If you only see a "head" option, that also works. The script waits until the page has loaded.

4.4 Optional settings

Put the chat icon on the left instead of the right:

<script src="https://YOUR-HUDDLE-HOST/widget.js" data-key="wk_..." data-position="left" async></script>

Brand color, company name and greeting are set in Huddle on the Website chat page (admins only). Changes reach open widgets right away.

4.5 Tell Huddle who the visitor is (optional)

If your customers log in on your website, pass who they are so your staff see it in the chat's Lead data (5.12). Add this after the widget code, on pages where the customer is logged in:

<script>
  window.addEventListener('load', function () {
    if (window.Huddle) {
      Huddle.identify({
        name: 'Jane Doe',
        email: 'jane@example.com',
        company: 'Example Ltd',   // optional
        userId: 'cust-1042'       // optional: your own id for this customer
      });
    }
  });
</script>

Fill in the real values from your website's login. Every field is optional.

• email and userId also link visits: chats from the same email or user id, in your workspace, all show under Recent conversations, even from another browser or device.
• Use an id that is safe to show, such as a customer number. It runs in the visitor's browser, so it is not proof of who they are and must never be a password, token or other secret.

The widget also sends the visitor's timezone and browser language by itself, Huddle's server also looks up the visitor's city, region and country from their IP address, so the team sees where the visitor really is. The IP address itself is not saved or shown to anyone; only the place is kept. IP location is city level and approximate (a VPN or company network shows where that network is). Without a lookup, Huddle falls back to the browser's time zone.

You can also open or close the chat window from your own buttons or links:

<button onclick="Huddle.open()">Chat with us</button>
<button onclick="Huddle.close()">Close chat</button>

4.6 Test it

1. Open your website in a normal browser window.
2. Check that a round chat icon appears in the bottom-right (or bottom-left) corner.
3. Click it and send a test message.
4. In Huddle, open Unassigned or Website chats. Your message should be there within a second.
5. Reply from Huddle. The reply appears in the widget straight away.

Before you change your real website, you can try the widget on the sample page linked from the Website chat page.

4.7 What your visitors see

1. A round chat icon in the corner of your website. A red badge shows unread replies while the window is closed.
2. Clicking the icon opens a chat window with your company name, greeting and the first names of a few team members.
3. "The team is online" when someone is online and not away, or "We usually reply within a few hours" otherwise.
4. Once a teammate picks the chat, only that person: for example "Ana is online", or "Ana is away right now".
5. A Send us a message button to start a new chat.
6. A list of their previous chats, newest first, each marked Open or Resolved. They can open any of them and read the whole history.
7. Live replies from your team, with a typing indicator.
8. An option to leave their name and email.

Visitors never see internal notes. A visitor cannot write into a closed chat: the chat window says it is closed and offers a button to start a new chat. Your team can still reopen it. On phones, the chat window fills the screen.

How visitors are remembered. No login is needed. The widget stores a random token in the visitor's browser. When they come back on the same browser and device, they see their previous chats. A different browser, a different device, a private window, or cleared browser data counts as a new visitor.

5. Daily use of the inbox

5.1 Inbox views

The left side of the inbox has these views. Each shows how many open conversations it has.

• Your inbox: conversations assigned to you.
• Mentions: conversations where someone @mentioned you.
• Created by you: internal conversations you started.
• All: everything you can see (except spam).
• Unassigned: conversations nobody owns yet. New website chats land here.
• Website chats: all chats from the website widget.
• Spam: conversations marked as spam.

Below the views there is an inbox for each teammate. At the top of the list you can filter by Open, Closed or All, and sort by Newest or Priority first (5.18).

Each row shows who owns the chat as a small avatar icon next to the time (hover it for the name). A dashed empty circle means nobody owns it yet. A chat with a priority also shows the priority bars.

5.2 Team inboxes

Your workspace starts with one inbox, "General". Admins can add more (for example "Billing" or "Sales"), up to the plan's inbox limit. Website chats go to the inbox chosen for the widget (General by default). Staff with the right permission can move a conversation to another inbox.

5.2.1 Escalate a chat

Escalation inboxes are for chats that need a specific team, for example Billing, Technical or Management. An admin adds them on the Website chat page under Routing > Escalation inboxes (up to 10; they do not count toward the plan's inbox limit) and gives each one to the right people (Team > Permissions).

1. Open the conversation.
2. Click ⚑ Escalate above the message box (or pick an escalation inbox in the Team Inbox menu of the Details panel).
3. Pick the inbox and, if you like, write a note for the team that takes it. The note is internal.
4. Click Escalate.

• The chat moves to that inbox, with a line "Ana Ortiz escalated this chat to Billing" and your note as an internal note.
• If the person it was assigned to cannot open that inbox, it becomes unassigned (auto-assign then picks someone with access, when it is on).
• People with access to the inbox, and admins, see and answer it as usual. It is also in the Escalated view.
• Everyone else who could see the chat before sees it as restricted: "This chat is escalated to Billing. You don't have access to it." No messages, no visitor details and no reply box, in the list, when opened, and in notifications. The server never sends them its content.
• If the same visitor opens a new chat while their escalated chat is still open, the new chat goes straight to the same escalation inbox. Others get "New chat escalated to Billing. You don't have access to it."
• To end an escalation, someone with access moves the chat back to a regular inbox. Deleting an escalation inbox sends its chats back to where they came from.

Every escalation is in the activity log ("Escalated from General to Billing with a note"). The note's text is not copied into the log.

5.2.2 Many inboxes or teammates

With more than six inboxes or teammates, a Find box appears above each sidebar list and the lists scroll. The conversation list shows one screenful at a time and adds more as you scroll (or click Show more). Search results are paged the same way. The Team page gets a Find a teammate box once there are more than eight members.

5.3 Assign a conversation

1. Open the conversation.
2. Click the Assign to me icon (a person with a plus, highlighted) at the top (shown while nobody owns it), or pick a person in the Assignee menu of the Details panel (5.12). To give it back to the team, click Move to unassigned under the Assignee menu (or pick "Unassigned").

The conversation moves to that person's inbox. Everyone sees the change live. Without the Assign chats to other people permission you can only assign chats to yourself. In an escalation inbox, only people with access to it can be picked. Before you pick up an unassigned chat, check who is already viewing it (5.11).

First reply assigns. When nobody owns a website chat and you send the first reply to the visitor, the chat is assigned to you ("Ana Ortiz was assigned this chat by replying first."). Only the first reply does this; later replies never change the owner. Internal notes do not count.

5.4 Replies and notes

Website chats have a Reply / Note switch above the message box.

• Reply: sent to the visitor. They see it in the widget.
• Note: seen only by your staff. Use it for internal comments.

Internal conversations (started with + in the inbox) are staff-only. Every message in them is internal. Close a conversation when it is done, reopen it if needed, and mark junk as spam. Closed one by mistake? Click Undo in the notice at the bottom within 5 seconds and the chat is open again exactly as it was.

The buttons at the top of a chat are icons. Hover one to see its name:

Everything that happens to a chat is written in it as a short grey line, in order with the messages (5.17).

5.5 Mentions

1. Type @ in the message box.
2. Pick a teammate from the list (it fills in their handle, usually their first name in lowercase).
3. Send.

The mentioned person sees the conversation in their Mentions view and gets a browser notification if they allowed notifications.

5.6 Away mode

1. Open your menu (your avatar).
2. Turn on Away.
3. Optional: type a reason, for example "Lunch, back at 2pm".
4. Choose whether to reassign replies (on by default).

• You receive no new auto-assigned chats while away.
• With reassign replies on, your open conversations go back to the team straight away. If auto-assign is on, each goes to another available teammate. Otherwise it becomes unassigned.
• Also with reassign on: if a visitor replies to a chat still assigned to you, that chat goes back to the team.
• A short system note is added, for example "Ana Ortiz is away (Lunch). Reassigned to Ben Carter."
• With reassign replies off, your conversations stay with you.

Turn away mode off when you are back.

5.7 Availability

Availability says which inboxes you take auto-assigned chats from: all inboxes, or only some of the inboxes you have access to. It does not change what you can see.

5.8 Auto-assign

Auto-assign is a workspace setting. Only an admin can turn it on or off. When it is on, each new website chat goes to one teammate who:

1. is online (has Huddle open),
2. is not away,
3. can reply (admin, manager or agent),
4. has access to the chat's inbox,
5. is available for that inbox,

and who has the fewest open conversations at that moment. If nobody matches, the chat stays in Unassigned.

5.9 Macros (saved replies)

A macro is a saved reply with a short name, such as refund-policy. Anyone who can reply uses them. Creating, editing and deleting are three separate permissions, on for admins and managers by default, on the Macros page (the lightning icon in the left bar, or Macros in your avatar menu). An admin can give any of them to an agent, or take them away from a manager.

To use one in a reply or note:

1. Type / at the start of the box or after a space. A list of macros opens.
2. Keep typing part of the name, for example /ref. The list filters as you type, best matches first.
3. Use the Up and Down arrow keys to pick one.
4. Press Enter (or Tab) to insert it in place of /ref. You can still edit it before sending.
5. Press Escape to close the list and keep what you typed.

When nothing matches, Enter does nothing, so a half-typed macro is never sent by accident. A / inside a word or link does not open the list.

Placeholders filled in when you insert: {first_name} and {name} (the customer, or "there" if unknown), {email}, {my_first_name} and {my_name} (you).

5.9.1 Macros with actions

A macro can also do things to the chat when it is sent, for example close it or escalate it to the Billing inbox. On the Macros page, under the text, use + Add action:

Up to 10 actions. Actions that undo each other (Close and Re-open, Snooze and Close...) cannot go together. They always run in this order: tags, priority, move or escalate, assign, snooze, spam, and close last. A macro can have only actions and no text.

When you pick such a macro in the reply box, its actions show as chips above the box (for example ⚡ /close-thanks on send: ✓ Close ×). Nothing happens yet. When you press Send, the reply goes out first, then the actions run. Click × on a chip to leave that action out this time. A macro without text runs its actions when you press Send on an empty box.

Actions run as the person who sends the macro, with that person's permissions. If someone is not allowed to escalate, a macro that escalates does not escalate when they send it: the reply and the other actions still go through, and a notice says which action did not run and why. Viewers cannot use macros. Each action leaves its own line in the chat.

Changing the trigger key (for developers): set TRIGGER at the top of public/macros-core.js (default /) and reload the app.

5.10 Delete a message or note

Use this for a message sent by mistake, a note in the wrong chat, or a visitor message with something that should not stay in the chat (abuse, a password).

1. Open the conversation.
2. Point at the message. A Delete link appears next to the name and time (on a phone or tablet it is always shown).
3. Click Delete and confirm.

• Your team still sees the message in its place, replaced by "Message deleted by Ana Ortiz · 2:14 PM" (or "Note deleted ..."). The text itself is gone. Everyone can tell something was removed, and by whom.
• The visitor no longer sees the message in the chat widget. It disappears straight away and does not come back after a reload. Visitors are not told that something was deleted.
• Internal notes were never shown to the visitor, so deleting one only changes what your team sees.
• The Huddle owner's activity log records that a message or note was deleted: who deleted it, whose it was, in which chat, and when (7.5). It does not keep the deleted text.

Who can delete: admins and managers can delete any message or note, including a visitor's. Agents can delete only their own. Viewers cannot delete anything. An admin can change this per person with Delete their own messages, Delete their own internal notes and Also delete teammates' and visitors' messages and notes. System notes cannot be deleted. When the plan has ended the inbox is read-only, so nothing can be deleted. Deleting cannot be undone.

5.11 See who is viewing a chat

When a teammate has a conversation open, their avatar appears at the top of that conversation, next to its name, with an eye icon. It updates live as people open and leave the chat. You never see yourself there.

• Unassigned chat (yellow): "Ben is viewing". Ben may be about to pick it up, so check with him before you answer, to avoid two people replying.
• Your chat: "Cara is viewing your chat" means someone else is reading a chat assigned to you, for example a manager checking in, or a teammate about to help.
• Someone else's chat: "Ana (assignee) and Cara are viewing" shows the owner and anyone else looking at it.

The conversation list shows the same small avatars next to the time on each row, so you can see which chats are being looked at without opening them.

Hover over an avatar (at the top of the chat or on a row) to see the teammate's full name and what they are doing: "Ben Carter · viewing", "Ben Carter · replying" or "Ben Carter · writing a note". While a teammate writes, their avatar gets a soft blue ring, the label at the top says "Ben is replying", and the row in the list says "Ben is replying…" instead of the last message. This works in every list, including Unassigned, so two people do not answer the same visitor.

A teammate counts as viewing while the chat is open in Huddle, also when another tab or window is in front of it, so two people working side by side see each other. Opening another chat or closing Huddle removes them straight away; a chat left in the background for 5 minutes stops counting. Several tabs on the same chat count once. You only see viewers on conversations you can see yourself. Visitors never see who is viewing.

5.12 The Details panel

The panel on the right of an open conversation shows everything about it. Hide or show it with the panel button at the top right of the conversation; on a phone or small screen it opens over the chat. Each section can be folded by clicking its title.

• Assignee and Team Inbox: change who owns the conversation and which inbox it is in (needs the reply permission; viewers see them read-only).
• Links:
  • Tracker ticket and Back-office tickets: click +, paste a link (for example your bug tracker or order system) and an optional title. Links open in a new tab. Click × to remove one. Up to 20 links per chat.
  • Side conversations (website chats only): click + to start an internal thread with your team about this chat. The visitor never sees it. It is listed here, and the side conversation links back to the chat.
• Conversation attributes: id, type, status, when it started, last activity, time to first reply and who sent it, when and by whom it was closed, and how many messages and notes it has.
• Lead data (website chats): name, email, company, type, location and user id. Type is "User" when your website passed a user id, otherwise "Lead". Location shows the visitor's city, region and country from their IP address, with their local time. Without an IP location it shows the browser's time zone, marked "time zone only". See all adds language, browser, current page, first seen, last seen and the visitor id. A dash means the visitor or your website has not given that detail.
• Recent conversations (website chats): every earlier chat with the same person, newest first. "The same person" means the same browser, or the same email or user id from 4.5. Click one to open it. Only your workspace's chats are listed, and only those in inboxes you can see; if others exist, a line says how many.

5.13 Search, files, tags, snooze and ratings

• Search: type in the box above the chat list. It searches subjects, messages, visitor names and emails in every chat you can see. Type #tag to find tagged chats.
• Files: click the paper clip, paste an image, or drag a file onto the reply box (images and files up to 10 MB, videos up to 25 MB: images, MP4/MOV/WebM videos, PDF, Office files, text, CSV, zip). Visitors can send files too.
• Tags: add them in the Details panel. They show in the list and under Tags in the sidebar.
• Snooze: hides a chat until the time you pick, or until the visitor writes again. Find them under Snoozed. A snooze is yours only: teammates still see the chat as normal, and the line about it in the chat is marked Only you see this. Closing the chat or a visitor reply ends everyone's snoozes.
• Ratings: when an agent closes a website chat, the visitor is asked to rate it from 1 to 5, shown as emoji: 😡 Terrible, 😞 Bad, 😐 Ok, 🙂 Great, 😍 Amazing, and can add a comment. The rating (emoji and word, never a number) and comment show at the end of the chat, in the chat header and in the list. Until the visitor rates, the card there has Don't ask for a rating (or Ask for a rating). Older 👍 / 👎 ratings count as 🙂 Great / 😞 Bad. The CSAT score and every rating with its comment are in Reports (5.23).
• No lost messages: if your connection drops, a message shows Sending… and goes out when you are back. You can retry or discard it.
• Notifications: a sound and a count in the tab title. A new website chat sounds for everyone online who can answer it; a new message in a chat someone picked sounds only for that person, once per message. Click anywhere in Huddle once after opening it, so the browser allows sound. Notices (such as Chat closed. Undo) show at the top left. Choose your offline emails under Your settings.
• Export: admins and managers download conversations, messages and contacts as CSV from Reports.

5.14 Your settings: profile, account and security

Every seat has its own settings: open your menu (your photo at the bottom left) and choose Your settings.

• Profile photo: Upload photo (PNG, JPEG or WebP, cropped to a square). Your team and your visitors see it. Remove photo goes back to initials.
• Alias: the name visitors see, for example "Ana from Support". Your team still sees your full name. Empty = your first name.
• Translate messages into: the default language for Translate (5.20).
• Job title: shown to visitors next to your alias ("Ana from Support · Billing specialist").
• Email signature: added to follow-up emails that carry your replies to a visitor who left.
• Use this photo, alias and job title in all my workspaces copies them to your other seats.
• Inbox preferences (saved with your seat, on every device): the view Huddle opens on, Enter or Ctrl/⌘+Enter to send, text size, and a compact conversation list.
• Coming later for your seat lists ideas that are not built yet.

On the same page you can change your password, turn on two-step sign-in (codes from an authenticator app, plus backup codes), choose email alerts, or sign out on every device. On the sign-in page, Forgot password? emails a reset link. Admins can make a reset link for a teammate on the Team page. After 5 wrong passwords an email is locked for 15 minutes.

5.15 Office hours, allowed websites, verified identity and languages

• Widget language: English, Spanish, French, German, Portuguese, Italian, Dutch or Hindi, or match the visitor's browser.
• Office hours: outside them the chat says you are away and asks for an email. Tick Open 24/7 to be open every day, all day. Replies sent while the visitor is gone are emailed to them.
• Allowed websites: the chat only works on these domains and their subdomains. Add your website here, or the chat stays off on it; copying the code to another website does not work. Your plan sets how many websites you can list (1 on the trial and Starter, 3 on Growth, 10 on Scale).
• Verified identity: your server signs the user id (or email) with your secret key and passes it as userHash in Huddle.identify. Signed emails show Verified. Example in Node: crypto.createHmac('sha256', SECRET).update(userId).digest('hex').

5.16 Activity log for admins

Admins see Activity log in the left bar: sign-ins, password changes, team changes, macro edits, settings, billing and deleted messages in their own workspace.

5.17 Chat history: who did what

Every action on a chat is written in the chat itself, as a short grey line between the messages, with who did it and when. For example: Ana Ortiz assigned this chat to Ben Carter, Ben Carter unassigned themselves, Huddle auto-assigned this chat to Ben Carter, Ana Ortiz closed this chat, marked this chat as spam, added tag #vip, set the priority to High, moved this chat from General to Sales, Chen Wei escalated this chat to Billing, Ana Ortiz used the macro close-thanks.

A snooze line (Ana Ortiz snoozed this chat until…) is shown only to the person who snoozed, because a snooze is private. These lines are for your team only: visitors never see them, and they do not count as messages in reports. Actions made before this update were only written to the activity log, so older chats have no lines for them.

5.18 Priority

The levels are No priority, Low, Medium, High and Urgent, shown as signal bars (more bars for higher, red for Urgent). Click the bars icon at the top of a chat, or use the Priority row in the Details panel. The bars show on the chat's row in the list, and Priority first above the list puts the highest at the top. It needs the same permission as closing or tagging; viewers see it but cannot change it.

5.19 Select several chats (bulk actions)

1. Hover a chat in the list. Its avatar turns into a checkbox. Click it (on a phone, tap the avatar).
2. Select more: click other rows, Shift-click for a range, or Ctrl/Cmd-click. With the keyboard, use the arrow keys and press x. The checkbox at the top selects every chat in the list.
3. Use the buttons at the top of the list: ⋯ More (Re-open, Move to unassigned, Mark as spam, Not spam, Add tag, Move to team inbox, Escalate), Assign, Edit selection (pencil: add several actions, then Update), Priority, Snooze and Close.
4. Press Escape or Clear to unselect.

Each chat goes through the same checks as a change by hand, so you only change what your permissions allow. Chats that could not be changed stay selected and a notice says why; the others are changed. Each change leaves its own line in every chat. Up to 500 chats at a time.

5.20 Translate or copy selected text

Select text in a message with the mouse (or long-press on a phone). A small menu appears:

• Translate opens a small window: pick a language you read and click Translate. The translation shows there and under the message, labelled only your team sees this. The visitor never sees it and nothing is added to the chat.
• Copy copies the selected text.

By default translation uses the free MyMemory service (no key, daily limit). The Huddle owner can switch to Google, DeepL or LibreTranslate in the server settings.

5.21 Keyboard shortcuts

Press ? anywhere in the app (or choose Keyboard shortcuts in your menu) for the full list. Single keys work when you are not typing in a box; press Esc to leave the reply box first.

Enter or Ctrl+Enter to send: at the bottom of the shortcut list each person picks Enter sends (default) or Ctrl+Enter sends (Enter adds a new line). Ctrl+Enter always sends. Saved in that browser. Shortcuts follow your permissions.

5.22 Rewrite or translate what you are writing

Select text you typed in the reply box. An AI ▾ button appears above the box; click it (or press Alt+A) for Expand, Rephrase, More friendly, More formal, More concise, Fix grammar & spelling and Translate to… (type to find a language).

The result replaces the selected text. Nothing is sent until you press Send; Undo in the notice (or Ctrl+Z) puts your text back. Viewers cannot use it.

Rewrites use an AI model the Huddle owner picks: Google Gemini (GEMINI_API_KEY), ChatGPT by OpenAI (OPENAI_API_KEY) or Claude by Anthropic (ANTHROPIC_API_KEY), set on the server and chosen in the owner dashboard under Settings > AI writing assistant. The owner can also turn them off. Without a key Huddle runs an offline demo with fixed rules, not AI, and says so in the menu and on every result. Translate uses the same service as 5.20.

5.23 Reports: CSAT score and the conversation report

Who sees them: the plan owner, admins, managers, and anyone given View reports and stats (Team > Permissions), the same permission as the rest of Reports. Everyone sees only ratings for chats they can open.

• Overview: the CSAT score (share of ratings that are 🙂 Great or 😍 Amazing, "7 out of 9", and the change from the period before), a bar split into the five ratings, and a CSAT column per teammate.
• Conversation report (second tab): every rated chat, newest first, 25 to a page: rating, teammate rated, comment, visitor, inbox, when, and a link to the conversation. Filter by period, rating, teammate, inbox, with or without a comment, and search comments, names, emails and subjects. Download CSV needs Download CSV exports.

5.24 Delivery ticks and online status

Website chats show ticks like a phone chat, on both sides. On your replies, next to the time:

• Clock: still sending (your connection dropped; Huddle resends it).
• One grey tick: sent. Huddle has it, but the visitor's browser does not yet, usually because they left your website.
• Two grey ticks: delivered. The visitor's browser has it, but the chat window is closed or the page is in the background.
• Two blue ticks: seen. The chat window was open on this chat and the page was on screen.

Your newest reply also has the word (Sent, Delivered or Seen), and the list shows the ticks in front of the last line when your team wrote last. Every teammate's replies show ticks. Internal notes never have ticks. Visitors see the same ticks under their own messages: one tick when Huddle has the message, two grey when a teammate who can open that chat has Huddle open, two blue when one of them has the chat on screen.

Online status. A green dot on a visitor's avatar means they have your website open right now; at the top of the chat it says Online now, or Last seen 5 min ago when they left. For teammates a green dot means Huddle is open, amber means away, no dot means offline. In the chat window the visitor sees a green dot on the avatar of the person handling their chat while that person is online.

5.25 Close a chat from the list

Hover a chat in any list (Unassigned, Your inbox, All, a team inbox...) and a round ✓ button appears at the end of the row. Click it to close the chat without opening it. A notice with Undo stays for 5 seconds. Closing this way does the same as the Close button in the chat: the visitor is asked for a rating and the history shows who closed it. On a phone or tablet the button is always shown. Viewers and anyone without Manage conversations do not see it.

5.26 Block and unblock visitors

In a website chat, open Details and click ⋯ next to the visitor's email, then Block the visitor (a reason for your team is optional). Their open chats close without a rating card, and the history shows who blocked them. They still see past messages, but the chat window says they can no longer send messages: no new chats, messages, files or ratings. Another browser that gives the same email or user id is blocked too (only signed ones when your workspace requires verified identity). People who can block see a red Blocked badge, and Lead data shows who blocked them, when and why. Everyone else sees nothing about the block: no badge, no Blocked row, no block lines in the chat (a chat the block closed just shows that it was closed), no block entries in the Activity log or exports, and no Blocked visitors page.

Blocked visitors (⊘ on the left) lists everyone blocked with who blocked them, when, the reason, a link to their last chat and an Unblock button. The plan owner, admins and managers can block and unblock by default; agents and viewers only when an admin turns on Block and unblock visitors in Team > Permissions. Each block and unblock is in the Activity log.

6. When a plan ends or a payment fails

6.1 Plan statuses

6.2 Trial end

On day 14 the trial ends and the workspace becomes expired. Nothing is charged. Buy a plan to continue.

6.3 Failed renewal and the grace period

1. Your month ends. If auto-renew is on, the status becomes renewing and the renewal is charged.
2. If the charge fails, the status becomes past due.
3. Huddle tries the charge again once a day.
4. Everything keeps working during a 3-day grace period, counted from the end of your paid month.
5. If a retry succeeds, the plan becomes active again. The new month starts where the old month ended, so you lose no days.
6. If no payment succeeds within the grace period, the plan expires.

To fix a failed payment quickly, update your card with the payment provider or buy the plan again on the Billing page.

6.4 What happens when a plan expires

• The chat widget stops on your website. Visitors can no longer start or continue chats. Open visitor chats are disconnected.
• The staff inbox becomes read-only. Staff can still sign in and read conversations. They cannot reply, write notes, assign, close, or start new conversations.
• New invites are blocked.
• Your data is kept. Conversations, contacts, staff and settings are not deleted.
• Your data can be exported while locked: Export all data in the red bar, or the downloads on Reports.
• Only this workspace is affected. Your other workspaces keep their own plans. The plan owner gets an email naming the workspace when a renewal fails.

6.5 How to restore

1. Sign in as the workspace admin.
2. Open Plan and billing.
3. Buy any plan.

As soon as the payment is confirmed, the workspace is active again. The widget works again on your website without any change to your code.

7. For the Huddle owner: the owner dashboard

This section is for the Huddle company, not for clients.

7.1 Sign in

1. Set two environment variables on the Huddle server before you start it:
   • OWNER_EMAIL, for example owner@yourcompany.com
   • OWNER_PASSWORD, a long, strong password
2. Start (or restart) the server. The owner login is created or updated from these values on every start.
3. Open https://YOUR-HUDDLE-HOST/owner and sign in. (The old address /owner.html still works and moves you to /owner.)

The owner login is separate from client logins. An owner session lasts 12 hours.

In the demo (npm run demo) the owner login is owner@huddle.test / owner1234 unless you set the variables.

7.2 How the dashboard is arranged

The dashboard has a menu on the left (a bar across the top on a phone) and one page at a time. Every page has its own address, so you can bookmark it, share it with a colleague who also has the owner login, or use the browser's back button. Filters and page numbers are part of the address too, for example /owner/clients?status=trialing&sort=renews&page=2. The menu shows counts: clients, plans on sale, clients past due (red) and unread notifications.

Run renewals now and Sign out are at the bottom of the menu. Results of every action appear in a small message at the bottom of the screen.

7.3 Owner actions

The owner can do every action for every client, whatever its plan or status.

Limits stay inside safe ranges: websites 0 to 100, storage up to 1 TB, images and other files 1 to 50 MB, videos 1 to 100 MB (files are held in memory while they are checked, so they cannot be bigger). The numbers on the dashboard are the ones the server uses to accept or refuse uploads and websites. If a change would put a client under what it already uses (more websites listed, or more files stored), the dashboard lists who is affected and asks before saving. Nothing is deleted: only the first websites on the list keep working, and new files are refused until the client is under the limit.

Every change (plan, trial length for one client or for new workspaces, extend, cancel, charge, limits, exports) is recorded in the activity log.

With the built-in test provider there is also a switch that makes a client's "card" fail, so you can test failed renewals. It does nothing with a real provider.

7.4 How automatic renewals work

1. A billing job runs every minute on the server (and once at start-up).
2. For each workspace whose paid month has ended with auto-renew on, the job asks the payment provider for one renewal charge for that period.
3. The job does not move the plan forward by itself.
4. The plan moves only when the provider's signed webhook arrives at POST /api/webhooks/payments:
   • payment.succeeded makes the plan active for the next month.
   • payment.failed makes the plan past due.
5. While past due and auto-renew is on, the job retries the charge once a day until the 3-day grace period ends.
6. Workspaces whose access has ended are marked expired by the same job.

Webhooks are idempotent. Each event has an id. If the provider sends the same event twice, the second one is ignored. A webhook with a bad signature is rejected with status 400.

So the payment provider is the single source of truth for money. Huddle never grants a paid month without a confirmed payment, except when you use Extend.

Related environment variables:

7.5 Activity log

The activity log lists the important things that happen in every client workspace. The Huddle owner sees every client's log here. Each client's admins see only their own workspace's log, on the Activity log page of the staff app (5.16). Managers, agents and viewers cannot open it. The Security category lists sign-ins, failed sign-ins, password resets and two-step changes.

The owner can turn on two-step sign-in with the Security button at the top of the dashboard, and download clients and payments as CSV.

Find it on the owner dashboard under Activity log, or open a client and click View full activity log to see only that client.

Each entry is one line:

• When it happened.
• Client: which workspace.
• Who did it: a staff member, a visitor, the Huddle owner, the payment

provider, or Huddle itself (for automatic steps such as auto-assign or a plan ending).

• What happened, in plain words, with a colored label for the type.
• Chat: the visitor's name and the chat subject, when the entry is about a

conversation.

What is logged:

Filter by client and by type. Entries are shown newest first, 25 per page; use Newer and Older to move between pages. The line under the buttons shows the page number and the total number of entries.

How long entries are kept. 180 days by default. Older entries are removed automatically (checked every minute and whenever the log is opened). Change it with the LOG_RETENTION_DAYS setting when starting the server. As a safety limit, the server keeps at most the newest 100,000 entries in total.

Deleted text is not kept. The log records only that a message or note was deleted, by whom, in which chat and when. Once deleted, the text is gone everywhere, so a password or card number a visitor pasted does not survive in the log.

For developers: the log is read with GET /api/owner/logs (owner session cookie required) and takes page, pageSize (1 to 100, default 25), workspaceId and category (messages, conversations, team, billing, workspace). The answer includes logs, page, pages and total.

7.6 Plans: create, edit, suspend and archive

Plans are data, not code: you can add, change and retire them from the dashboard without a new release.

• New plan. Fill in the plan form and click Create plan. It is on sale

at once (untick Show on the pricing page to sell it only when you move a client to it).

• Edit. Change anything. Seats, websites, storage and file sizes apply to

current clients at once; if that puts a client over a limit, the dashboard lists them and asks first. Nobody is removed and nothing is deleted.

• Change the price. New buyers pay the new price. For current clients you

choose: keep their price (the default; you can move them later), or move them at their renewal after a notice of N days (30 by default, set in Settings). Moved clients are told by email and on their Billing page now. The plan's price history keeps every old price.

• Raise kept prices later. On the plan page, Move them moves every

client still on an older price, after notice. On a client's page you can do it for one client.

• Suspend. The plan stops being sold, and you must choose where its clients

go: one plan for all, and a different one for some clients if you like; at their next renewal (charged the new plan's price then) or now (dates kept, new price from the next renewal). Clients are told. Resume puts it back on sale and cancels the moves that have not happened yet.

• Archive. The plan stops being sold, but its clients keep it and keep

renewing at their price. Unarchive puts it back on sale.

• At least one plan must stay on sale.

Charging per seat later, without code changes. Every member is already a seat, and each plan has its own seats included, most seats and extra seat price. To sell purely per seat, create a plan with 1 seat included, a price of one seat (or 0), and extra seats on at the per-seat price. A seat added mid-month is charged for the days left until the client's billing date, then every seat renews with the plan on that date. Hide or suspend the old plans when you are ready.

7.7 Notifications

Every purchase, renewal, extra added or ended, failed payment, auto-renew change, plan move and price change makes a notification:

• for the client: on its Billing page, and by email to its plan owner and

billing admins (failed payments use the existing failed-payment email);

• for you: on the Notifications page and on the Overview, live as they happen,

and by email when Email me billing events is on in Settings.

7.8 Settings: AI writing assistant and translation

AI keys are set only in the server's environment (your hosting provider's environment settings), never in the code, a chat or this dashboard. Restart the server after adding or changing one.

• Settings > AI writing assistant: pick Google Gemini, OpenAI ChatGPT, Anthropic Claude, the offline demo, Off, or Follow the server settings, then Save. It applies at once for every client. A service without its key is greyed out; each line shows Key set: yes/no (never the key) and its model.
• Test connection sends one short sentence and shows what came back, or exactly why it failed (key not accepted, model not offered to this key, no credit or quota, busy, or the server cannot reach the service). It does not change the service in use.
• Models: type a model name to use instead of the server setting, for example when a provider retires a model. Empty = the server setting or the default.
• Translation works the same way, with a Test button per service: MyMemory (free, 5,000 characters a day, 50,000 with MYMEMORY_EMAIL), Microsoft Azure Translator (AZURE_TRANSLATOR_KEY and AZURE_TRANSLATOR_REGION, e.g. eastasia), Gemini, ChatGPT, Claude, Google Cloud Translation, DeepL, LibreTranslate or off. A Gemini key does not work for Google Cloud Translation.

Every change is in the activity log. Only the Huddle owner can change these. If agents see "The writing assistant could not be reached", the message now says why, and the same reason is in the server log (never the key). Huddle removes stray spaces, line breaks and quotes around a key.

7.9 Client satisfaction (CSAT)

The Clients list has a CSAT column (share of visitor ratings that are 🙂 Great or 😍 Amazing, with how many ratings), sortable. A client's page shows it for all time and the last 30 days under Facts. Only counts, never chats or comments.

8. For the Huddle owner: connect a real payment provider

Huddle comes with four payment providers. You choose one with the PAYMENT_PROVIDER environment variable:

Also set PUBLIC_URL, used for the return addresses after payment. Keys go only in the server's environment, never in code, the dashboard or chat. The Settings page shows which keys are set (never their values). If a key is missing, the provider refuses with a message naming it.

8.1 What each adapter does

Every adapter turns the provider's messages into the same normalized event (8.2). Events it does not use are answered 200 and ignored, so the provider does not keep retrying them. The same event twice is ignored.

Monthly dates: each client has one subscription at the provider, created the day the plan is bought, so the provider charges on that day every month. Its amount is the plan plus the client's extras; Huddle updates it two days before a billing date when that total changes. An extra added mid-month is a separate one-time charge for the days left.

8.2 The normalized event

{
  id,                    // the provider's unique event id (used to ignore duplicates)
  type,                  // 'payment.succeeded' | 'payment.failed' | 'subscription.canceled'
  reason,                // 'checkout' | 'renewal' | 'purchase' | 'extra' (part-month for an extra) | 'auto'
  workspaceId,           // the Huddle workspace (null for 'purchase')
  purchaseId,            // for 'purchase': the id Huddle gave createCheckout
  extraId,               // for extras
  planId, amountCents, currency, autoRenew, extraSeats,
  providerPaymentId, providerSubscriptionId,
  failureMessage         // on failures, a short human message
}

reason: 'auto' means the provider cannot tell a first payment from a renewal (PayPal); Huddle works it out from the subscription id it already knows. Huddle's ids travel in the provider's metadata in a short form (w:<workspace>|x:<extra>|p:<plan>|r:<reason>|n:<seats>).

8.3 Set up a provider

1. In the provider's dashboard, create API keys (use test mode or the sandbox first).
2. Set the webhook URL to https://YOUR-HUDDLE-HOST/api/webhooks/payments and copy its signing secret (Stripe, Razorpay) or webhook id (PayPal). Stripe: send checkout.session.completed, invoice.paid, invoice.payment_failed and customer.subscription.deleted. Razorpay: subscription.charged, payment_link.paid, payment.failed, subscription.cancelled. PayPal: PAYMENT.SALE.COMPLETED, PAYMENT.CAPTURE.COMPLETED, BILLING.SUBSCRIPTION.PAYMENT.FAILED, BILLING.SUBSCRIPTION.CANCELLED.
3. Set PAYMENT_PROVIDER and the keys in the server's environment, and PUBLIC_URL. Restart.
4. Open Settings in the owner dashboard and check that every key shows set.
5. Test: buy a plan, add an extra seat, run a renewal, fail a renewal, cancel.

8.4 Write another adapter

Copy billing/providers/stripe.js, keep the same methods and the normalized event, and add it to billing/providers/index.js. The tests in test/providers.test.js show how to test one with a fake fetch.

8.5 Go-live checklist

1. HTTPS on your Huddle address. The widget then connects with wss://.
2. PUBLIC_URL set to that address, for example https://chat.yourcompany.com. It is used in invite links and in the widget code clients copy.
3. COOKIE_SECURE=1, so login cookies are only sent over HTTPS.
4. SMTP_URL (and MAIL_FROM) set, so invite emails are sent.
5. OWNER_EMAIL and a strong OWNER_PASSWORD set.
6. PAYMENT_PROVIDER set to stripe, razorpay or paypal, with its keys, tested in test mode, with its webhook URL registered.
7. Database. The default store is one JSON file (DATA_FILE). For real clients, move the store to Postgres or SQLite (see README, "Going to production").
8. Backups. Back up the data file or database every day, and test a restore.
9. If you run more than one server process, add a shared message channel (for example Redis) so live updates reach every process. Run the billing job in only one process.
10. Monitor the server logs for "billing tick failed" and for rejected webhooks.

8.6 Still placeholders in this build

These are clearly marked stand-ins until the real services are chosen:

• Payment provider keys: the Stripe, Razorpay and PayPal adapters are

built and tested against recorded messages, but no real keys are set, so the default is still the mock provider. Set the keys (8.3) and test in each provider's test mode before charging real money.

• Database: one JSON file (DATA_FILE) with hourly backups. Accounts,

memberships, purchases and sessions live there too.

• Email (SMTP): without SMTP_URL, emails (invites, resets, notifications,

"workspace ready", "payment failed") are printed to the server log, and invite and reset links are shown to copy.

9. FAQ and troubleshooting

I belong to several workspaces. How do I switch?

Click the workspace name in the bar at the top of the app (or the top-left tile) and pick another. Each workspace also has its own address, /w/<id>. See 2.9.

A link to a workspace says "not found".

You are not a member of it, or it does not exist. Ask one of its admins to invite your email. Huddle shows the same message in both cases on purpose.

I bought a workspace but it has not appeared.

It is made when the payment is confirmed. Your workspaces shows the purchase as waiting, failed or done. If it failed, nothing was charged; buy again.

The chat icon does not show on my website.

Most often the website is not on the allowed websites list (Website chat > Allowed websites). With an empty list the chat shows on no outside website, and your site's browser console says "Huddle chat is hidden: <your site> is not on this widget's allowed websites". Add the exact host (for example yourapp.onrender.com) and reload. On a test server that wipes its data on restart (Render's free tier), set DEMO_ALLOWED_SITES so the list is filled again automatically.

1. Check that the code is on the page: view the page source and search for widget.js.
2. Check that the data-key matches the one on your Website chat page.
3. Check that your plan is active. The widget stops when the plan expires.
4. Check the address in src. It must be your Huddle host and reachable from the internet (not localhost).
5. If your site is on HTTPS, the Huddle host must also be on HTTPS.
6. If your site uses a Content Security Policy, allow your Huddle host for scripts, frames and WebSocket connections.
7. Clear your website builder's cache and your browser cache, then reload.

An invite email did not arrive.

1. Ask the person to check their spam folder.
2. Check that the email address is correct. Revoke and invite again if not.
3. If the server has no SMTP_URL, no email is sent. Copy the link shown on the Team page and send it yourself.
4. The link expires after 7 days and works once. Send a new invite if needed.

"All seats are in use" when I invite someone.

Pending invites count as seats. Revoke invites that are no longer needed, remove people who have left, or upgrade your plan.

A visitor says their previous chats are missing.

The widget remembers visitors by a token in their browser. History is missing if they use a private or incognito window, a different browser or device, or cleared their browser data. Some browsers also block storage in embedded frames. The chats are still in your Huddle inbox. Huddle.identify adds their name and email (or a user id), and then Recent conversations in the Details panel lists their older chats from every device. It does not bring the history back into the widget on a new device.

Two of us answered the same chat.

Look at the top of the conversation before replying: if a teammate's avatar is there with "is viewing", they may be about to pick it up (5.11). Click Assign to me first so everyone sees who owns it.

I cannot reply. The message box does not work.

Your plan may have expired (the inbox becomes read-only), or your role is viewer. Ask your workspace admin.

I do not see a conversation my colleague mentioned.

You may not have access to that inbox. Ask an admin or manager to give you access, or to assign the conversation to you.

A message was deleted by mistake. Can I get it back?

No. Deleting removes the text from the conversation for everyone. Huddle does not keep a copy. The Huddle owner's activity log shows who deleted it, in which chat and when, but not what it said.

Can our admin see the activity log?

No. The activity log is only for the Huddle owner, on the owner dashboard. Inside a conversation your team can still see that a message was deleted and by whom.

Can I use one login for several businesses?

Yes. Sign in, open your menu and add a workspace. Each workspace has its own plan, staff and widget key.

10. Email and WhatsApp

Customers' emails and WhatsApp messages arrive in the same inbox as website chats, and your replies go back the same way: an email reply goes out as an email, a WhatsApp reply goes to the customer's WhatsApp.

10.1 What your plan includes

You can add more in Billing > Extras: an extra email address is $5 a month, an extra WhatsApp number $15 a month (the owner can change these prices). If an extra is cancelled, the newest connection over the limit is paused; on its card, Use this one swaps which one stays on.

Only the plan owner can connect or change email and WhatsApp (the permission "Email and WhatsApp setup"). Everyone else sees the conversations.

10.2 Connect your support email address

Email runs on Huddle's own mail service, included for every client; you pay only if you buy extra addresses. If the page says email is not switched on yet, the Huddle owner has not added the Mailgun keys to the server's .env file. Ask them; once they do (or switch on Test mode), the page updates by itself. WhatsApp does not depend on this.

No passwords or keys are needed. You keep your mailbox; you only turn on forwarding.

1. Open Email and WhatsApp (the envelope icon in the left rail).
2. Press Add email address, type the address customers write to (for example support@yourshop.com) and pick the team inbox for new emails.
3. Huddle shows a forwarding address. Press Copy.
4. Follow the steps on the card for your provider:
   • Gmail: Settings > See all settings > Forwarding and POP/IMAP > Add a forwarding address. Gmail sends a confirmation code; it appears on the Huddle card within seconds. Paste it in Gmail, then choose "Forward a copy of incoming mail to" the Huddle address.
   • Outlook: Settings > Mail > Forwarding, paste the address, keep a copy.
   • Anything else (Google Workspace, Microsoft 365, Zoho, cPanel…): forward a copy of every incoming email to the Huddle address.
5. Press Send a test email. When the forwarded copy comes back, the card turns green: Connected.

On the card you can also set the name customers see, the inbox for new emails, whether the teammate's name goes under each reply, and whether people in Cc stay on replies.

10.3 Connect a WhatsApp number

WhatsApp uses your own Meta account: you pay Meta directly for WhatsApp messages. You need a WhatsApp Business number on Meta's Cloud API and an app in Meta for Developers. Press Add WhatsApp number; a short guide asks for the values one at a time, and checks each one before moving on, saying exactly what is wrong:

1. Access token: Meta Business Settings > Users > System users > add a system user (Admin), give it your WhatsApp account, Generate new token with whatsapp_business_messaging and whatsapp_business_management, expiry Never. Huddle refuses tokens that expire.
2. Phone number ID: WhatsApp Manager > Phone numbers, or the app's WhatsApp > API setup page. A long number, not the phone number itself.
3. WhatsApp Business Account ID: on the same API setup page.
4. Your Meta app: Meta for Developers > your app > App settings > Basic. Copy the App ID, press Show next to App secret and copy it.

Last step, on the card: in Meta for Developers > your app > WhatsApp > Configuration > Webhook > Edit, paste the Callback URL and Verify token from the card (each has Copy), press Verify and save, then subscribe to messages. Huddle only accepts messages signed with your app secret, for your own number.

Then press Connect. The token and app secret are stored encrypted and never shown again (the card shows only their last 4 characters). On the card: Test connection, Sync approved messages, Blue ticks (show customers when the team has read their message), sign replies with the teammate's first name, Replace access token and Disconnect.

When Meta approves Huddle as a Tech Provider, this becomes a single "Continue with Facebook" button.

10.4 Working on email and WhatsApp conversations

• The inbox has Email and WhatsApp views; each conversation shows a small ✉ or ☏ badge.
• Send delay: an email reply waits 60 seconds (Settings > Email and WhatsApp > How replies leave; 0 to 120 s). While it waits, the message shows "Sending in 52 s · Undo · Edit". Undo removes it, Edit puts it back in the reply box. WhatsApp sends at once unless you set a delay.
• Ticks: one grey tick sent, two grey ticks delivered, two blue ticks read (WhatsApp, and email when opened). A failed reply shows the reason and Retry.
• WhatsApp 24-hour window: you can reply freely for 24 hours after the customer's last message; the bar above the reply box shows the time left. After that WhatsApp only allows approved messages (templates made in Meta's WhatsApp Manager). Press Approved messages, pick one, fill in the blanks and send.
• Whoever replied last: when a customer writes again, the conversation goes back to the teammate who replied last (on by default for email and WhatsApp). If they are away or left the team, normal routing picks someone.
• A closed conversation stays closed: a new message from the customer starts a new conversation.
• Ratings: closing an email conversation sends a one-click rating email; closing a WhatsApp conversation sends a list with the five faces.
• Out of hours reply (optional): sent once per conversation outside your office hours.

10.5 Start a conversation

Press + at the top of the inbox and pick Email or WhatsApp.

• Email: choose the From address, type the customer's address, a subject and the message.
• WhatsApp: choose the number, type the customer's number with the country code, pick an approved message and fill its blanks, and tick "This customer agreed to get WhatsApp messages from us" (WhatsApp requires it).

Everyone who can reply may start these by default ("Start email and WhatsApp conversations" in Team > permissions). A team can start up to 200 a day.

10.6 Macros and customer name fields

Macros are one library for every channel. Fields fill in when a macro is inserted, and when you type them yourself:

{customer_name}, {customer_first_name}, {customer_email}, {customer_phone}, {my_name}, {my_first_name}, {workspace_name}.

An unknown name becomes "there" (change it under How replies leave). A macro can have an Email version (a longer text used in email conversations) and a Use in setting (all, chat and WhatsApp only, email only). A misspelt field such as {customr_name} makes Send ask first.

10.7 Quick questions (WhatsApp)

A menu of up to 9 common questions with ready answers, plus "Talk to a person". When it is on, a new WhatsApp chat gets the menu and waits in Unassigned (view "In quick questions"), out of everyone's way, until the customer picks "Talk to a person"; then it is assigned like any chat. Answered chats close by themselves after 24 hours. Set the greeting, the list button, the questions (title up to 24 characters, description up to 72) and what happens when the customer types instead of choosing. The website chat gets the same menu in a later update.

10.8 When the plan is not active, and blocked senders

While a plan is not active, new emails and WhatsApp messages are not stored; Huddle only counts them and shows "N messages were not delivered" on the Email and WhatsApp page. WhatsApp shows the customer two grey ticks; no auto-reply is sent. Messages from blocked customers are dropped the same way.

10.9 For the Huddle owner

• Email keys live in .env only. Email runs on Huddle's own Mailgun account, shared by every client. Put MAILGUN_API_KEY, MAILGUN_SIGNING_KEY, MAILGUN_DOMAIN (optionally INBOUND_DOMAIN, MAILGUN_API_BASE for the EU region) in the server's .env file (copy .env.example) or the host's environment settings, then restart. npm start reads .env by itself. Also set CHANNELS_SECRET_KEY (a long random value) before clients connect WhatsApp: it encrypts their tokens and app secrets.
• Settings > Email and WhatsApp in the owner dashboard is read-only: each key shows as set or not set with only its last 4 characters, plus Test Mailgun, example .env lines and the two Mailgun webhook addresses. It never takes or shows a key.
• WhatsApp needs nothing from the owner: each client connects their own Meta account and app (10.3).
• Test mode (owner Settings > Email and WhatsApp, at the top): switches email and WhatsApp on for every client without real keys. A stand-in inside Huddle plays Mailgun and Meta: clients connect any address or number, Pretend a customer writes on each card puts a message in the inbox, and replies get delivered and read ticks. Nothing is really sent. Email uses the real Mailgun keys once they are in .env; switch test mode off before going live so WhatsApp uses each client's real Meta account. npm run demo starts with test mode on.
• Email & WhatsApp page: every client's connections with tiles (connected, errors, setup not finished, paused), filters, messages this month, last message in, ignored messages and bounces. Errors are listed first and counted in the menu.
• Plans: "Email addresses included" and "WhatsApp numbers included", and the two extras with their prices. A plan with 0 websites has no website chat.
• Client page: an Email & WhatsApp card with usage and each connection.

Back to top