> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telli.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Phone Numbers

> Buy a telli number, connect your own number, or forward calls to your agent

You can buy a number from telli, forward your current business number to a telli number, or connect your own number through SIP.

## Choose your setup

<CardGroup cols={3}>
  <Card title="Buy a telli number" icon="phone" href="#buy-a-telli-number">
    The fastest setup. Use a telli-managed number for incoming and outgoing calls. Some countries require business verification.
  </Card>

  <Card title="Forward your current number" icon="arrow-right" href="#keep-your-current-business-number">
    Keep your public business number and forward incoming calls to a telli number. You configure the forwarding with your phone provider or PBX.
  </Card>

  <Card title="Connect a SIP number" icon="arrow-down-to-square" href="#connect-your-existing-number-with-sip">
    Connect an existing number and phone system for incoming and outgoing calls. You need SIP trunk access from your provider.
  </Card>
</CardGroup>

<Note>
  **Call forwarding** sends calls from your current provider to telli. [Call
  transfer](/deep-dives/call-transfer) sends an active call from the telli agent
  to a person or team.
</Note>

## Buy a telli number

### Before you start

Depending on the country and number type, you may need an approved business verification. Prepare the following information:

* Your legal business name, registration number, and registered address
* A current business registration document
* The name and contact details of an authorized representative
* The country, number type, and local area code that you need

For a German business, a commercial register extract or a business registration document is usually accepted. The company name, registration number, and address must match the data that you enter in telli.

<Warning>
  A local number can require an address in the area covered by its prefix. Do
  not use a PO box. Requirements differ by country and number type; the
  verification form shows the required documents for your selection.
</Warning>

### Complete business verification

<Steps>
  <Step title="Open Verifications">
    Go to **Phone numbers**, select **Verifications**, and stay on the **Regulatory Compliance** tab.
  </Step>

  <Step title="Start a verification">
    Select **Add Verification**, then choose the country and number type. Enter a clear internal name, such as `DE Local - Berlin office`.
  </Step>

  <Step title="Enter the business details">
    Enter the legal business data and the authorized representative exactly as shown in the registration document.
  </Step>

  <Step title="Upload and submit the documents">
    Upload the documents requested in the form. Submit the verification and track its status on the **Regulatory Compliance** tab.
  </Step>
</Steps>

The form takes about five minutes when your documents are ready. Approval often takes one or two business days, but it can take longer if the provider needs more information.

<Frame caption="Start a business verification for a local German number">
  <div className="relative w-full aspect-[2/1] overflow-hidden">
    <img src="https://mintcdn.com/telli/A0X3y2sLBnwqjNEI/images/phone-numbers-verification-light.png?fit=max&auto=format&n=A0X3y2sLBnwqjNEI&q=85&s=5425296fad4fcaa761d7f070b58a6607" width="1536" height="768" alt="Business verification dialog with Germany, Local, and Verification Name fields" className="absolute inset-0 h-full w-full object-contain block dark:hidden" data-path="images/phone-numbers-verification-light.png" />

    <img src="https://mintcdn.com/telli/A0X3y2sLBnwqjNEI/images/phone-numbers-verification-dark.png?fit=max&auto=format&n=A0X3y2sLBnwqjNEI&q=85&s=3039b3c6fe8d982264c04c013330846b" width="1536" height="768" alt="Business verification dialog with Germany, Local, and Verification Name fields" className="absolute inset-0 h-full w-full object-contain hidden dark:block" data-path="images/phone-numbers-verification-dark.png" />
  </div>
</Frame>

### Purchase the number

<Steps>
  <Step title="Start the purchase">
    Go to **Phone numbers** and select **New Number**.
  </Step>

  <Step title="Choose the number">
    Select the country and number type. Local numbers support voice. Available mobile numbers can also support SMS.
  </Step>

  <Step title="Select the verification and prefix">
    If required, select an approved business verification. For a German local number, enter the area code without the leading `0`, for example `30` for Berlin.
  </Step>

  <Step title="Confirm the purchase">
    Select **Continue**, choose an available number, review the details, and confirm the purchase.
  </Step>

  <Step title="Assign how the number is used">
    Open the new number. Assign the agent that answers incoming calls. For outgoing calls, use the global pool, reserve the number for one agent, or turn outbound use off.
  </Step>
</Steps>

<Frame caption="Search for a local German phone number">
  <div className="relative w-full aspect-[192/91] overflow-hidden">
    <img src="https://mintcdn.com/telli/A0X3y2sLBnwqjNEI/images/phone-numbers-purchase-light.png?fit=max&auto=format&n=A0X3y2sLBnwqjNEI&q=85&s=5cc886b5a080331d2505c14cc0a7bf3e" width="1536" height="728" alt="New phone number dialog with Germany, Local Voice, business verification, and Berlin prefix selected" className="absolute inset-0 h-full w-full object-contain block dark:hidden" data-path="images/phone-numbers-purchase-light.png" />

    <img src="https://mintcdn.com/telli/A0X3y2sLBnwqjNEI/images/phone-numbers-purchase-dark.png?fit=max&auto=format&n=A0X3y2sLBnwqjNEI&q=85&s=6fcf6809d3280dd93141791ec090556f" width="1536" height="728" alt="New phone number dialog with Germany, Local Voice, business verification, and Berlin prefix selected" className="absolute inset-0 h-full w-full object-contain hidden dark:block" data-path="images/phone-numbers-purchase-dark.png" />
  </div>
</Frame>

<Note>
  Number availability and capabilities depend on the country and number type.
  Check the **Voice** and **SMS** badges in the phone number list.
</Note>

To show your verified business name on outbound calls from a telli-managed number, set up [Branded Calling](./branded-calling).

## Keep your current business number

A common setup is to keep your existing public number and forward incoming calls to a telli number. Your existing number stays with your current provider. Outgoing calls from your existing phone system are not changed.

Choose when telli should answer:

| Forwarding rule            | Result                                                   |
| -------------------------- | -------------------------------------------------------- |
| **Always**                 | Every incoming call goes directly to the telli agent.    |
| **No answer**              | The telli agent answers when your team does not answer.  |
| **Busy**                   | The telli agent answers when the line is busy.           |
| **Outside business hours** | A schedule in your provider or PBX sends calls to telli. |

### Common mobile forwarding codes

Many mobile networks support the following GSM MMI codes. Replace `<destination>` with the full telli number, including the `+` and country code. Enter the code in the phone app and press the call button.

| Forwarding rule | Activate              | Deactivate or delete |
| --------------- | --------------------- | -------------------- |
| **Always**      | `**21*<destination>#` | `##21#`              |
| **No answer**   | `**61*<destination>#` | `##61#`              |
| **Unreachable** | `**62*<destination>#` | `##62#`              |
| **Busy**        | `**67*<destination>#` | `##67#`              |

<Warning>
  Codes and their effects can differ by provider, plan, and device. Fixed-line
  services and PBXs often use different codes. Some codes can also overwrite
  or remove existing voicemail forwarding. Check your provider's instructions
  before using them.
</Warning>

For provider examples, see the [Telekom mobile codes](https://www.telekom.de/hilfe/mobilfunk/telefonie-nachrichten/steuercodes) and [Vodafone mobile help](https://www.vodafone.de/hilfe/mobiles-telefonieren-surfen.html).

### Configure forwarding outside telli

<Steps>
  <Step title="Prepare the telli destination">
    Buy a telli number and assign an inbound agent. Copy the full number in [E.164 format](/phone-number-format), including the leading `+` and country code.
  </Step>

  <Step title="Configure your provider or phone system">
    Create the forwarding rule in your provider portal, router, or PBX. For example, a FRITZ!Box usually places this under **Telephony > Call Handling > Call Diversion**. Menu names can differ by version.
  </Step>

  <Step title="Preserve the original caller ID">
    Ask your provider or PBX administrator to pass the original caller number. This setting can be called **CLIP no screening**, **original caller ID**, or **P-Asserted-Identity**.
  </Step>

  <Step title="Test the complete path">
    Call your existing number from another phone. For a no-answer rule, do not answer the original line. Confirm that the correct telli agent answers and that the call appears in **Conversations**.
  </Step>
</Steps>

<Warning>
  Call forwarding is configured outside telli. Your provider can charge for the
  forwarded call leg. Check the price, supported forwarding rules, caller ID
  behavior, and maximum ring time with the provider.
</Warning>

### Provider checklist

Before you go live, confirm these items with your phone provider or PBX administrator:

* Which forwarding rules are supported: always, no answer, busy, and time based
* Whether the original caller ID reaches telli
* Whether voicemail or an IVR answers before the forwarding rule starts
* Whether forwarded calls have additional costs or concurrency limits
* How to disable the rule quickly and how to prevent forwarding loops

If no call appears in **Conversations**, the call did not reach telli. Check the forwarding rule with your provider. If the call appears but the wrong agent answers, check the inbound assignment on the telli number.

## Connect your existing number with SIP

Forwarding changes incoming calls only. A custom SIP trunk connects your existing number and provider to telli for incoming and outgoing calls.

<Note>
  Custom SIP trunks work alongside telli-provided numbers. You can use either
  option or both.
</Note>

### Configure both sides of the connection

To import a SIP number, configure both sides:

* In telli, add the phone number, provider termination URI, SIP credentials,
  and transport protocol. These settings let telli place outgoing calls through
  your provider.
* In your SIP provider, route incoming calls for that number to telli. Provider
  field names differ, but the destination is always:

```text theme={null}
sip:axg8odfh9dw.sip.livekit.cloud
```

You need the following information in telli:

| Field                  | Description                                                                                                                                                                              | Example             |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| **Phone Number**       | Your phone number in [E.164 format](/phone-number-format)                                                                                                                                | `+14155551234`      |
| **Termination URI**    | Provider hostname for outgoing calls                                                                                                                                                     | `pstn.provider.com` |
| **Auth Username**      | SIP authentication username                                                                                                                                                              | `user123`           |
| **Auth Password**      | SIP authentication password                                                                                                                                                              | `securepass456`     |
| **Transport Protocol** | SIP transport protocol. Supported values are `TCP`, `UDP`, and `TLS`. The default is `TCP`.                                                                                              | `TCP`               |
| **From User**          | Optional. What outgoing calls send as the SIP From user: `Phone number` or `Auth username`. Some providers, for example CallOne, reject calls unless the From user is the auth username. | `Phone number`      |
| **From Host**          | Optional. Host of the SIP From header for outgoing calls. Leave empty for the telli default. Required when the From user is the auth username.                                           | `sip.provider.com`  |

<Warning>
  Do not include the `sip:` prefix in the Termination URI. Enter only the
  hostname or IP address. The incoming destination in your SIP provider does
  use the `sip:` prefix.
</Warning>

Choose the transport protocol that matches your provider's trunk settings. If your provider does not specify one, keep the default `TCP`.

<Note>
  If outgoing calls fail with `403 Forbidden - Invalid Domain`, set **From Host**
  to the domain your provider expects, usually the termination host. If they fail
  with `403 Username in From Field required`, set **From User** to `Auth username`.
  Both fields are under **Optional Settings**.
</Note>

<Note>
  [Cold transfers](/cookbooks/call-transfers/overview) also need your provider to
  permit SIP REFER on the trunk. Most providers disable this by default, and some
  split it across more than one setting. Warm transfers place a separate outgoing
  call and work without it.
</Note>

### Add a custom SIP trunk

<Steps>
  <Step title="Open Phone Numbers">
    Open **Phone Numbers** in your telli dashboard.
  </Step>

  <Step title="Start the import">
    Select **Import Number**.
  </Step>

  <Step title="Enter the configuration">
    Enter your phone number, SIP credentials, and transport protocol.

    <img src="https://mintcdn.com/telli/tmEpRbh4w9F1c_Yq/images/custom_sip_trunk-light.png?fit=max&auto=format&n=tmEpRbh4w9F1c_Yq&q=85&s=01fc8e37e23ea0c4a22d322c4b9d35a5" className="block dark:hidden" alt="Import Number dialog with phone number, SIP credentials, and transport protocol fields" width="1024" height="1116" data-path="images/custom_sip_trunk-light.png" />

    <img src="https://mintcdn.com/telli/tmEpRbh4w9F1c_Yq/images/custom_sip_trunk-dark.png?fit=max&auto=format&n=tmEpRbh4w9F1c_Yq&q=85&s=dc8f1ac6c194f7cb4b152e720a1613d5" className="hidden dark:block" alt="Import Number dialog with phone number, SIP credentials, and transport protocol fields" width="1024" height="1116" data-path="images/custom_sip_trunk-dark.png" />
  </Step>

  <Step title="Save and test">
    Select **Import Number**, then test incoming and outgoing calls.
  </Step>
</Steps>

### Provider examples

Use these examples to map provider settings to the telli fields. Each setup includes incoming routing to telli and the outgoing termination settings that you enter in telli.

#### Twilio Elastic SIP Trunking

<Steps>
  <Step title="Create or open an Elastic SIP Trunk">
    In the Twilio Console, create an Elastic SIP Trunk or open the trunk used by your imported number.
  </Step>

  <Step title="Route incoming calls to telli">
    Open **Origination** and add `sip:axg8odfh9dw.sip.livekit.cloud` as the Origination URI.
  </Step>

  <Step title="Configure outgoing calls">
    Open **Termination** and note the Termination URI, for example `your-trunk.pstn.twilio.com` or `your-trunk.pstn.frankfurt.twilio.com`. Under **Authentication > Credentials**, create a username and password.
  </Step>

  <Step title="Assign the phone number">
    Make sure that your phone number is assigned to this trunk.
  </Step>

  <Step title="Allow call transfers">
    For cold transfers, open **General settings** and enable **Call Transfer (SIP REFER)** and the optional **Call Transfers to the PSTN via your Trunk**. Twilio disables both by default.
  </Step>

  <Step title="Add the number to telli">
    In telli, enter your phone number, the Twilio Termination URI without `sip:`, the Twilio credentials, and the transport protocol configured for your trunk.
  </Step>
</Steps>

#### Telnyx

<Steps>
  <Step title="Create an FQDN SIP connection">
    In Telnyx, create a SIP connection and select the **FQDN** connection type.
  </Step>

  <Step title="Route incoming calls to telli">
    Under **Authentication and Routing**, add `axg8odfh9dw.sip.livekit.cloud` as an FQDN and set **DNS Record Type** to **SRV**. Do not include the `sip:` prefix in this field.
  </Step>

  <Step title="Set the number format">
    Set both **Destination Number Format** and **Origination Number Format** to **+E.164**.
  </Step>

  <Step title="Configure outgoing credentials">
    Configure credential-based authentication with a username and password.
  </Step>

  <Step title="Assign the phone number">
    Make sure that your phone number uses this Telnyx SIP connection.
  </Step>

  <Step title="Add the number to telli">
    In telli, enter your phone number, `sip.telnyx.com` as the Termination URI without `sip:`, the Telnyx credentials, and the transport protocol configured for your SIP connection.
  </Step>
</Steps>

Telnyx permits cold transfers by default. There is no call transfer setting to enable on the SIP connection.

#### CallOne

CallOne authenticates outgoing calls on the SIP From user and rejects INVITEs that carry the phone number there. The From host must be your CallOne SIP domain.

<Steps>
  <Step title="Route incoming calls to telli">
    In the CallOne portal, route incoming calls for your number to `sip:axg8odfh9dw.sip.livekit.cloud`.
  </Step>

  <Step title="Add the number to telli">
    In telli, enter your phone number, your CallOne SIP domain as the Termination URI, for example `1234.voip.callone.de`, the SIP account username and password, and the transport protocol configured for your account.
  </Step>

  <Step title="Set the From identity">
    Under **Optional Settings**, set **From User** to `Auth username` and **From Host** to the same domain as the Termination URI.
  </Step>
</Steps>

For country-specific regulatory requirements, see the [Twilio phone number guidelines](https://www.twilio.com/en-us/guidelines/regulatory).


## Related topics

- [Replace Phone Number](/v1/endpoint/replace-phone-number.md)
- [List Phone Numbers](/v1/endpoint/list-phone-numbers.md)
- [Import Phone Number](/v1/endpoint/import-phone-number.md)