> ## Documentation Index
> Fetch the complete documentation index at: https://developers.nlpearl.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Inbound Calls
> Configure your Pearl to handle incoming calls, from recording and transcripts to the holding line and webhooks.
***
## Setting Up Inbound Calls
Once you have created a Pearl, you can enable it to receive inbound calls. Inbound settings are configured inside your Pearl, under **Inbound Settings**, giving callers a dynamic and responsive experience driven by your conversational flow.
**What are inbound calls?**
Inbound calls let your Pearl handle incoming calls, engaging with callers immediately and effectively using the conversational flow you defined.
***
## Attach a Phone Number
To receive calls, your Pearl needs a phone number. Numbers are purchased and connected from **Settings → Phone Numbers**, not from the Inbound Settings screen.
Start by clicking your **profile card** at the bottom-left corner of the sidebar, then open **Settings**.
Then select the **Phone Numbers** tab. From here you can purchase, connect, and manage all your numbers.
You have three ways to get a number for your Pearl:
NLPearl Number
NLPearl Number
Buy a number directly from NLPearl and start receiving or making calls in minutes (US numbers, billed monthly).
For more details, visit the [NLPearl Phone Numbers](/pages/nlpearl_phones) page.
Twilio
Twilio
Connect your Twilio account to use your existing numbers, with access to a wide range of countries.
Visit [Twilio Integration](/pages/twilio_integration) for details on how to import and manage your Twilio phone numbers.
Custom VoIP
Custom VoIP
Bring your own VoIP provider and connect custom numbers over SIP to your account.
To learn more about integrating your own VoIP service, check out [Custom VoIP Integration](/pages/custom_voip).
Once you have a number, attach it to your Pearl: open the Pearl's **Settings** panel and pick the number from the **Phone Number** dropdown. Your Pearl will then answer calls on that number.
***
## Inbound Settings
Configure how your Pearl answers incoming calls from the **Inbound Settings** tab of your Pearl, in the [PearlVibe](/pages/pearl_vibe) flow editor.
These settings apply to **voice** Pearls only. A Text Pearl has a different set of inbound options.
### Recording Options
Record the conversation (on/off). When enabled, the call audio is saved and available afterwards from your **call logs** for quality reviews, training, and analytics. When disabled, no audio is captured or stored.
Call recording laws vary by region and often require informing or getting consent from callers. Make sure your Pearl's flow discloses recording where required.
***
### Recording After Transfer Call
If enabled, the call keeps recording after Pearl transfers it and leaves the line, so you capture the full conversation with the human agent. Turn it off if you don't want to record the person or third party the call is transferred to.
This option only appears when **Recording Options** is enabled. See the [Transfer Call Node](/pages/transfer_call) to learn how call transfers work.
***
### Transcript Options
Choose what is kept from the call transcript. Transcripts appear in your call logs alongside the recording.
| Option | Description | When to use |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------ |
| **Full Transcript** | Keeps the entire conversation as-is. | Complete analysis, QA, and training. |
| **Sensitive Info Removed** | Automatically masks sensitive data (credit card numbers, Social Security numbers, personal identifiers) while keeping the conversation readable. | Compliance and PII protection. |
| **No Transcript** | No transcript is stored for the call. | Maximum privacy. |
With **Sensitive Info Removed**, if a customer says *"My credit card number is 1234-5678-9012-3456"*, the transcript stores it as *"My credit card number is \*\*\*\*-3456"*, so you can review interactions safely without exposing sensitive data.
***
### Hold Message
Played to callers when they are put on hold, typically when all agents are busy and the caller enters the holding line. English only, max **300 characters**.
Example: *"Thanks for calling! One moment while I connect you to our team."*
If your Pearl experiences high call volumes, callers are not turned away. They enter the holding line and hear your hold message and sound until an agent becomes available.
***
### Estimated Wait Time
When enabled (on/off), callers on hold hear their position in the queue and an estimated wait time, along with your hold message. Setting expectations this way helps reduce hang-ups during busy periods.
***
### Hold Sound
The music that loops while callers wait in the holding line. Select one of the built-in tracks or upload your own `.mp3` (up to **3 minutes**). Use the preview button to listen before saving.
***
### Call Ambience
A subtle background environment (office, call center, outdoor…) played **during the live conversation** to make the call sound more natural and human. Defaults to **None**.
Pick an ambience from the dropdown, then fine-tune its **volume** (0–100) with the slider. A preview plays automatically so you can hear the result before saving.
Don't confuse this with **Hold Sound**: Call Ambience plays quietly behind Pearl's voice during the call, while Hold Sound only plays while a caller is waiting in the holding line.
***
### Webhooks
Send call lifecycle events to an external endpoint.
* **Version**: `V1` or `V2` (default **V2**). V2 is the current payload format; keep V1 only if you have an older integration built against it.
* **Call Webhook URL**: fires at key points in the call lifecycle (when the call starts and when it ends), sending an object similar to the [Get Calls Endpoint](/api-reference/v2/call/get-call) with details like duration, outcome, and any data collected during the call.
* **Credentials**: optional authentication token attached to the requests so your endpoint can verify they come from NLPearl.
Use Webhooks only if external tools need event notifications. For actual automations, rely on **Post-Call Actions** tied to how the call ended.
Learn how to configure webhooks, authenticate requests, and handle the events NLPearl sends.
***
## Project-Level Settings
A few settings live at the **Project** level rather than in the Inbound Settings screen. Open them from the settings popover on your Pearl.
### Agents
Sets how many **simultaneous agents** handle this Pearl's incoming calls, i.e. how many calls can be answered at the same time, capped by your account's agent quota. A higher number lets your Pearl take more concurrent callers before the rest enter the holding line.
Learn how to manage the agents assigned to your inbound and outbound activities.
***
### Call Retention
Applies to **all calls**. Set how long calls are kept (a number of days, or leave empty to keep them indefinitely), then choose what is removed when they expire: delete all call data, or granularly the **Recording**, **Transcript**, **Summary**, or collected **Variables**.
***
### Monitoring and Adjusting Your Inbound Calls
While basic monitoring of call logs and reports can be done via our API, any changes to the setup, such as voice or language settings, must be handled directly on the platform.
