# Calls

<br />

> Take and make voice calls from inside the CRM — browser softphone, inbound ring, click-to-call from any chat, per-call recording, and call-event cards inline in the conversation thread — without installing any other app.

> **TL;DR**
>
> * **What it is —** the agent-facing calling surface in the CRM. A call log, a softphone dialer, a click-to-call button inside every chat, and inline call-event cards in conversations. The telephony setup (phone numbers, voice menus, departments, queues, outbound dialer campaigns) is configured under Lodgestory Voice — this module is what **agents** see day-to-day.
> * **Who it's for —** any agent or team lead who takes inbound calls, makes outbound follow-ups, or reviews call history. Admins go to the Voice admin to configure trunks and voice menus.
> * **Top outcome —** a browser softphone inside the CRM so a support rep can answer, dial, and review calls without switching apps, with every call logged and attached to the right chat.

## At a glance

|                    |                                                                                                                                                                                                                                               |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Plan tier**      | All paid tiers. Requires an integrated telephony account — your telephony provider plus an agent mapping for each user. If no provider is configured, the Call button in chats shows *Calling not configured* until an admin completes setup. |
| **Who can use it** | Account Owners and Admins see all organisation calls. Users see their own calls only. Every user must be mapped to a provider-side extension to place or receive calls.                                                                       |
| **Channels**       | Voice. Call-event cards (*Call initiated*, *Call completed*, *Call missed*, *Call failed*) appear inline in WhatsApp, Email, and Web Chat conversations.                                                                                      |
| **Integrations**   | Multi-provider — works with your choice of telephony provider. Browser-native voice; no software to install.                                                                                                                                  |
| **Top limits**     | One active outbound call at a time per agent softphone. Recordings are fetched on demand to keep the list page fast.                                                                                                                          |
| **API**            | Yes — partner API for initiating calls, listing call logs, and fetching recordings.                                                                                                                                                           |

## How to find it

**Sidebar → Calls.**

**Direct URL:** `https://lodgestory.com/crm/calls`

**From a chat (click-to-call):** the chat header in [Home](home-unified-inbox.md) has a **Call** button that opens the dialer pre-filled with the guest's number.

**Softphone status indicator:** a small dot in the status area shows connection state — green *connected*, amber *registering*, red *offline*. If offline, inbound calls can't ring the browser; outbound still works via the server-side adapter.

**Admin and configuration:** **Settings → Calling**. That area is the Lodgestory Voice admin — this module cross-links to it but doesn't own it.

📸 `[SCREENSHOT: calls-nav.png — sidebar with Calls highlighted]`

## What is Calls?

### The problem it solves

A support team on WhatsApp has almost always had a shadow phone line — the one agents personally give out when chat isn't enough, the one that rings on an ancient desk phone, the one that never makes it to the CRM. Missed calls become lost leads. Recorded calls live on the provider's portal if anywhere. The relationship between a phone conversation and the rest of the guest record gets severed the moment the handset is picked up.

Calls closes that gap by putting the phone in the same browser tab as the inbox. A call can be initiated from any chat. Rings come through in the agent's browser. Every call is logged. A call-event card appears inline in the related chat — so an agent reviewing a conversation weeks later sees the full arc: WhatsApp messages, a 4-minute call at 3:12 PM, follow-up email.

### What you get

* **Browser softphone, no desk phone.** Calls ring and answer in the browser. Agents with extensions on multiple providers can register all of them simultaneously.
* **Click-to-call from any chat.** The chat header's Call button grabs the guest's number from the contact record, picks a caller-ID, and dials. Outgoing extension is per-agent.
* **Multi-provider support.** One CRM surface in front of any configured telephony provider. Different regions can use different providers.
* **Call logs with filters.** Direction (inbound / outbound), status (completed / missed / failed), agent, date range, search. Admins see the whole organisation; users see their own calls.
* **Recording playback on demand.** Recordings load when you click **Load Recording** — keeps the list page fast even with long histories.
* **Real-time updates.** Inbound rings, status changes, and hang-ups push to the CRM layout in real time — the dialer opens, the Calls list refreshes, the relevant chat thread gets the call-event card inline.
* **Call-event cards inline in chats.** When a call starts, completes, is missed, or fails, a structured card is posted to the associated chat's thread (visible in [Home](home-unified-inbox.md)) so the conversation timeline is complete.

### How it's different

* **Not a voice-first product.** Voice setup (voice menus, departments, queues, outbound campaigns) lives in the Lodgestory Voice admin; this module is the chat-adjacent view. Good news if you don't want contact-centre complexity; less good if you need one (then you'll spend time in Voice).
* **Credentials stay on the server.** Provider API keys and webhook secrets are never exposed to the browser. Agents reviewing configurations see redacted values; full credentials never leave the server.
* **Every call is linked back to a chat where possible.** Caller numbers are matched against contacts; when a contact has an active chat on a voice-capable channel, the call's event cards land in that thread automatically.

### Customer scenarios

* **Villa operator with a single India phone number.** Agents answer inbound calls that ring through to their browser. When a ring comes in, the dialer pops up with the caller's number and — if matched to a contact — their name. After hang-up, the call-event card lands in the matching WhatsApp chat; a ticket is opened if the conversation needs structured follow-up.
* **US-facing support adding India coverage.** Existing US phone number; operator adds an India number. Agents who handle both register two extensions; the dialer picks the right provider and caller-ID automatically based on destination.
* **Marketing follow-up on a campaign.** Campaign replies flag 50 interested leads; a sales agent clicks each chat's **Call** button in turn; each call is auto-attached to the chat with a recording. Sales lead reviews the call-event cards across chats at end of week.

### How it fits with the rest of Lodgestory

**Upstream:** every call logs against a contact and — when possible — a chat. The [Contacts](contacts.md) module owns the duplicate handling that lets inbound caller numbers resolve to a known guest. **Cross:** [Home](home-unified-inbox.md) surfaces the call-event cards inline. **Downstream:** all telephony setup — Lodgestory Voice admin.

📸 `[SCREENSHOT: calls-landing.png — calls list with dialer popover]`

## Core concepts

| Term                 | What it means                                                                                                                                                  |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Call log**         | The record of a single call — direction, status, from / to number, times, duration, recording, linked chat, linked contact, agent.                             |
| **Calling account**  | A telephony provider configuration on your organisation. An organisation can have many.                                                                        |
| **Agent mapping**    | Connects a user on your team to a provider-side extension. Without a mapping, an agent can't place or receive calls on that account.                           |
| **Caller-ID number** | The phone number the customer sees when you call out — either shared in the organisation pool or assigned to a specific agent.                                 |
| **Call-event card**  | A special message card in the chat thread (*Call initiated*, *Call completed*, *Call missed*, *Call failed*) posted when Lodgestory can link a call to a chat. |

## Quick Start — make your first call in 2 minutes

### Step 1 — Confirm your softphone is connected

Look at the softphone status dot. Green = connected, amber = connecting, red = offline. If red, ask your admin — you likely need an agent mapping or the account credentials need refreshing.

### Step 2 — Open a chat

Sidebar → **Home**, click any guest with a phone number.

### Step 3 — Click the **Call** button

In the chat header. The dialer opens with the guest's number pre-filled; the caller-ID selector picks an appropriate outbound number.

📸 `[SCREENSHOT: calls-qs-3-dialer.png — dialer popover]`

### Step 4 — Click **Dial**

The call connects through your telephony provider. You'll see *ringing* in the dialer.

### Step 5 — Converse, then hang up

Audio connects automatically on answer. Click **Hang up** to end the call. The call-log row updates; a *Call completed* card appears in the chat thread.

### Step 6 — Review the log

Sidebar → **Calls** — your call is at the top of the list. Click the row to open the detail; click **Load Recording** to fetch the audio.

📸 `[SCREENSHOT: calls-qs-6-detail.png — call detail sheet with recording player]`

## How it works

### Inbound call

A call rings your phone number. Lodgestory:

1. Creates a call-log record with status *Ringing*.
2. Resolves the number to an agent mapping.
3. Rings the agent's browser softphone.
4. Updates the call log as the call progresses (answered, ended).
5. If the caller matches a contact with an active chat, posts a call-event card to that chat's thread.

### Outbound click-to-call

You click the **Call** button in a chat or enter a number in the dialer. Lodgestory:

1. Loads your agent mapping and picks a caller-ID number.
2. Asks your telephony provider to place the call.
3. Creates the call-log record.
4. Tracks status through to hang-up.
5. Posts a call-event card to the linked chat.

### Real-time updates

Inbound rings, status changes, and hang-ups push to the CRM layout instantly — the dialer opens, the Calls list refreshes, the relevant chat thread gets the call-event card inline. The system is designed so an agent on a different page still sees an incoming call ring.

### Multi-provider support

Lodgestory supports multiple telephony providers through a common interface. Different regions of your organisation can use different providers for regional cost and routing. The dialer picks the right provider and caller-ID for the destination automatically; you can override in one click when needed.

## Features in depth

### Calls list

Columns: direction icon, counter-party number, guest name (if matched), agent, start time, duration, status, recording status.

Filters:

* **Direction** — inbound, outbound, all.
* **Status** — completed, missed, failed, all.
* **Agent** — admins see a picker; users see their own only.
* **Date range** — today, last 7 days, last 30 days, custom.
* **Search** — free text across counter-party number and guest name.

Admins see the whole organisation; users see only their own calls.

### Dialer (softphone popover)

* Number pad for manual dial.
* Caller-ID selector — pick which number the customer sees on the other end.
* Provider selector when you have multiple mappings.
* In-call controls: mute, hold, keypad, hang up.
* Status line — *registering, registered, calling, ringing, in call, ended, failed*.

### Click-to-call from a chat — two call modes + caller-ID picker

The **Call** button in the chat header is the primary way to dial a guest from a conversation. Clicking it opens a popover with — depending on your organisation's configuration — up to four elements:

1. **The destination phone number** (extracted from the chat).
2. **A provider selector** if your organisation has more than one telephony account.
3. **A call-mode toggle** if the selected provider supports browser softphone — two buttons: **Browser** and **Phone**.
4. **A caller-ID selector** listing the numbers assigned to you on the selected account, with *(Default)* marked where applicable.

The Call button label flips between *Call via Browser* and *Call* depending on mode.

For the simple case — one account, one caller-ID, no browser-softphone support — the popover is skipped and clicking dials directly.

#### Call modes — Browser vs Phone

* **Browser mode** — the call rings and answers in your current browser tab. Lowest-latency path; only available when your provider supports browser softphone and your registration is active. This is also the only mode that supports internal extension-to-extension calls within your organisation.
* **Phone mode** — your telephony provider rings your agent phone number first, you pick up, and the provider bridges the customer. Useful when you're away from the browser, on a train, or on a device without microphone access. The customer sees the same caller-ID either way, and the resulting call log looks identical to a Browser-mode call.

You'll sometimes hear Phone mode described as "Follow Me" because the call follows you to whatever number is on your agent extension. In the UI it's labelled **Phone**.

#### Caller-ID picker — aggregated across providers

On sign-in, Lodgestory pulls every calling account you have access to — across every configured provider — plus the per-account agent mapping and assigned caller-IDs. The popover's provider selector lists them all; switching provider re-loads that account's caller-IDs. A caller-ID marked as your default shows with a *(Default)* badge.

Lodgestory picks a sensible default (first account with caller-IDs; else first account overall), but you can override in one click when calling internationally — pick a US number for a US call, a +91 number for an India call, and so on.

#### Disabled states — three distinct reasons

The Call button is disabled with a specific tooltip in each case:

| Tooltip                         | What's missing                                                                                   | How to fix                                                                     |
| ------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
| *Calling not configured*        | No telephony account at all, or no agent mapping for you on any account                          | Admin adds a provider in **Settings → Calling** and creates your agent mapping |
| *No phone number available*     | The chat has no dialable number (for example, a Web Chat visitor whose phone isn't captured yet) | Capture the number in a bot journey prompt, or use a different chat            |
| *No caller-ID numbers assigned* | Your mapping exists but has no caller-ID numbers allocated on this account                       | Admin assigns caller-IDs in the Voice admin                                    |

Only the first tooltip means the whole organisation has nothing configured. The other two are per-chat or per-agent setup gaps.

#### Chat linkage

When you call from a chat, the chat ID goes along with the call request. The call log records the chat link, which is how the post-call event card ends up in the right thread.

#### Dialer button vs the Call button

The dedicated **Dialer** button (separate from the chat's Call button) opens a similar popover but for **manual** outbound — not tied to a chat. It adds a number pad, a free-text phone input, and (when your provider supports browser softphone) an **External / Internal** toggle with a teammate picker for internal extension-to-extension calls.

Use the chat Call button to call from a chat; use the Dialer for numbers the CRM doesn't know or for internal handoffs.

### Call detail sheet

Opens on row click. Shows all call-log fields, a **Load Recording** button (fetches the audio player on click), the matched contact (link to the contact drawer), the matched chat (link to open in Home), and timeline annotations.

### Live calls view

A top-bar indicator and an optional *Live* filter on the list show calls currently in flight — ringing, answered, or in progress. Updates in real time.

### Call-event cards inline in chats

When Lodgestory can link a call to a chat, it posts a call-event card to that chat. The card shows direction, duration, status, and a link back to the call detail.

## Roles and permissions

| Action                                  | Account Owner | Admin |                 User                 |
| --------------------------------------- | :-----------: | :---: | :----------------------------------: |
| See all organisation calls              |       ✓       |   ✓   |                   ✗                  |
| See own calls                           |       ✓       |   ✓   |                   ✓                  |
| Place an outbound call                  |       ✓       |   ✓   |             ✓ (if mapped)            |
| Receive an inbound call                 |       ✓       |   ✓   | ✓ (if mapped and caller-ID assigned) |
| Load / play recording                   |       ✓       |   ✓   |             ✓ (own calls)            |
| View live calls across the organisation |       ✓       |   ✓   |                   ✗                  |
| Manage calling accounts and numbers     |       ✓       |   ✓   |                   ✗                  |
| Manage agent mappings                   |       ✓       |   ✓   |                   ✗                  |

Admin operations live in Settings → Calling under the Lodgestory Voice admin.

## Cross-module workflows

### Inbound missed call → callback scheduled

Caller rings after hours; no agent available → call logged as *Missed*; voicemail module captures a greeting → the assigned bot journey triggers a WhatsApp message ("We'll call you back — when works?"); the journey's prompt captures the time; an outbound campaign in the Voice admin queues the callback.

**Modules involved:** Calls → Voicemail → Bot Journeys → Outbound Campaigns → Calls.

### Click-to-call from a broadcast reply

Campaign reply enters Home → agent opens the chat → clicks **Call** → dialer fires → call completes → *Call completed* card appears inline → agent creates a ticket for follow-up.

**Modules involved:** Campaigns → Home → Calls → Tickets.

## Limits a user will run into

| Limit                               | Value                              |
| ----------------------------------- | ---------------------------------- |
| Concurrent outbound calls per agent | 1                                  |
| Call-log pagination                 | 100 per page                       |
| Recording playback                  | Loads on demand                    |
| Sign-in session                     | Relies on the CRM's 10-day session |

Provider-imposed limits (rate per second, concurrent channels per line) live with each telephony provider's configuration.

## Errors & FAQ

| You see                                               | Likely reason                                     | What to do                                                  |
| ----------------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------- |
| *Failed to initiate call*                             | Missing mapping or invalid number                 | Confirm agent mapping and caller-ID allocation              |
| *Softphone not connected*                             | Registration failed or dropped                    | Reload the browser; re-auth the telephony account           |
| *No caller-ID available for this destination country* | No provider covers the destination                | Provision a caller-ID on a provider that covers the country |
| *Failed to load call logs*                            | Network or session                                | Reload                                                      |
| *Failed to load recording*                            | Recording not yet available or provider transient | Retry in a few minutes                                      |

### Frequently asked

**Why does my softphone go red for a few seconds every so often?**
Registration cycle; expected as long as it reconnects within a few seconds. Persistent red means a credentials issue or network problem — check the account status in the Voice admin.

**Why did an inbound call ring but no call-event card appeared in the chat?**
Lodgestory couldn't match the counter-party number to a contact with an active chat on a voice-capable channel. The call log still exists; only the inline card can't be created.

**Why can I see a colleague's call in the list when I expected my own only?**
You have Admin or Account Owner role; that unlocks the full organisation view.

**Why isn't the recording URL playing?**
Recordings are produced asynchronously after hang-up — sometimes several minutes later. Refresh and click **Load Recording** again. If it still fails after 30 minutes, your telephony provider may have retention limits.

**Why does my outbound call fail on an India destination but work on US?**
The caller-ID picker probably selected a non-India-routable account. Verify your provider has India termination enabled, or add a provider that does.

**Can I transfer a live call?**
Not yet in the dialer. Transfer and conference are on the Lodgestory Voice roadmap.

## Related modules & next steps

* Lodgestory Voice — phone numbers, voice menus, departments, queues, outbound dialer campaigns.
* [Home (Unified Inbox)](home-unified-inbox.md) — where call-event cards appear inline.
* [Contacts](contacts.md) — number-to-contact resolution for caller ID and chat linking.
* [Bot Journeys](../settings/bot-journeys.md) — can trigger outbound and react to missed-call events.
* [Reports](reports.md) — call-log CSV export.

<br />