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

# Bring your own number: Twilio or a SIP trunk

> Connect a phone number you already own to Hamsa, from Twilio or from any SIP provider, including the Hamsa SIP gateway settings and what to give your carrier.

Hamsa answers and places calls on numbers you already own. You can connect a Twilio number with your account credentials, or any number from a SIP provider through a SIP trunk. Once a number is added, you assign it to an agent on the [Phone numbers](https://docs.tryhamsa.com/agents/connect/phone-numbers.md) page.

## Before you start

* You need to be an Owner or Admin in the project.
* For Twilio: the number, your Twilio account SID and auth token.
* For a SIP trunk: the number, your provider's SIP address, and the trunk username and password if your provider uses them.

## Add a Twilio number

**1. Open Bring your own number**

In the sidebar, open **Telephony** > **Bring your own number** and click **Add number** > **Twilio**.

![The Add number menu with Twilio and SIP trunk](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/connect/add-number-menu-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=008cc46a6019674f73c9501fbe7dd431)

**2. Fill in the number**

| Field | What to enter |
| - | - |
| **Label** | A name you'll recognize, for example "Support line". Required. |
| **Phone number** | The Twilio number, with its country code. |
| **Twilio account SID** | Starts with `AC`, followed by 32 characters. |
| **Twilio auth token** | At least 32 characters. |

![The Twilio form filled in: Label, Phone number, Twilio account SID and Twilio auth token, with the tip to use an Ireland (IE1) auth token](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/connect/twilio-form-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=c8c802da8eba16a83cff7aaef0001646)

**3. Click Add**

Hamsa checks your credentials, checks that the number belongs to that Twilio account, and connects it.

> [!TIP]
>
> Use the auth token from your Twilio **IE1 (Ireland)** region. The Ireland edge is closest to Hamsa's voice infrastructure, so calls have less delay. A US auth token still works, with more delay.

What Hamsa changes in your Twilio account: it creates an Elastic SIP trunk that sends the number's calls to Hamsa, and moves the number onto it. If the number was handling calls somewhere else, it stops doing that. When you delete the number in Hamsa, that trunk is removed.

Errors you may see:

| Message | What to do |
| - | - |
| "SID must start with 'AC' followed by 32 characters." | Copy the account SID again from the Twilio console. |
| "Invalid phone number format. Please start your phone number with + followed by a country code." | Enter the number in international format, for example `+14155550100`. |
| "The phone number does not exist for the given account." | The number isn't in this Twilio account. Check the SID and the number. |
| "The phone number is already used in the system." | The number is already added in Hamsa, in this or another project. |

## Add a SIP trunk number

**1. Open Bring your own number**

Click **Add number** > **SIP trunk**.

**2. Enter the label and number**

Enter a **Label**. Under the number, choose **Phone number** for a regular number, or **Other** for an extension or short code your system dials, such as `1000`.

**3. Copy the inbound address**

Under **Inbound configuration**, copy the **Origination URI**. Your provider sends the number's calls to this address. If the form also asks for **Carrier IPs**, enter the IP addresses your provider sends calls from (see [The Hamsa SIP gateway](#the-hamsa-sip-gateway)).

**4. Enter the outbound details**

Under **Outbound configuration**, enter where Hamsa sends calls when your agent dials out:

| Field | What it does | Default |
| - | - | - |
| **SIP address** | Your provider's SIP host, for example `sip.example.com`. Required. | None |
| **Transport type** | How SIP messages travel: **TCP**, **UDP**, or **TLS** where offered. | **TCP** |
| **SIP trunk username** | Username for your trunk, if your provider uses one. | Empty |
| **SIP trunk password** | Password for your trunk. | Empty |
| **Custom SIP headers** | Extra headers sent on outbound calls, for routing or carrier integration. Click **Add header**. Names use letters, numbers and hyphens. | None |

![Outbound configuration filled in: SIP address, Transport type TCP, trunk username and password, Custom SIP headers, and the Advanced section collapsed](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/connect/sip-trunk-form-outbound-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=9d8fc4336861c0b44fa9820a66510fc3)

**5. Click Add**

The number is saved. Give your provider the values on its page (see below).

![The SIP trunk form for a +971 number: Label, Phone number, Inbound configuration with the gateway Origination URI and two Carrier IPs, and the start of Outbound configuration](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/connect/sip-trunk-form-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=cdf8a8f19292dafac7347a4235dab07e)

Hamsa never shows the trunk password again after you save. You can't edit a number later: to change anything, delete it and add it again.

## The Hamsa SIP gateway

On Hamsa cloud, SIP numbers in international format (a `+` and 6 to 15 digits) and short numbers (2 to 15 digits) go through the Hamsa SIP gateway. The gateway sits between your provider and your agent and gives you extra settings. The form shows the gateway fields when your number qualifies.

Extra fields for gateway numbers:

| Field | What it does | Default |
| - | - | - |
| **Carrier IPs** | The IPs your provider sends calls from: IPv4 addresses or CIDR ranges, up to 20, separated by commas. The gateway uses this list to recognize your provider's calls. Required. | None |
| **Transport type** > **TLS** | Encrypts SIP signaling. Only offered for gateway numbers. | **TCP** |
| **Advanced** > **Media encryption (SRTP)** | Encrypts call audio between the gateway and your provider. **Off (default)**, **Optional** or **Mandatory**. With **Mandatory**, calls fail if your provider doesn't encrypt. | **Off (default)** |
| **Advanced** > **Codecs** | Audio formats offered to your provider, in order: **PCMU, then PCMA (default)**, **PCMA, then PCMU**, **PCMA only**, **PCMU only**. | **PCMU, then PCMA (default)** |
| **Advanced** > **Headers to pass to the agent** | SIP headers on your provider's calls that the agent receives, separated by commas, for example `User-to-User, X-Conversation-Id`. | None |

![The Advanced section open: Media encryption (SRTP) Off (default), Codecs PCMU, then PCMA (default), and Headers to pass to the agent](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/connect/sip-trunk-form-advanced-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=6fa19b6a0053dfa1ae9f84ee14ceffdc)

The origination URI follows the transport type: `sip:sbc.tryhamsa.com:5060;transport=tcp` for TCP, `sip:sbc.tryhamsa.com:5060;transport=udp` for UDP and `sips:sbc.tryhamsa.com:5061;transport=tls` for TLS. Always copy it from the form.

After you add a gateway number, its page shows **Carrier setup** with what your provider needs:

| Value | Give it to your provider as |
| - | - |
| **Send calls to** | The address to send the number's inbound calls to. |
| **Allow calls from** | The gateway's IP, `34.243.238.8`. Use it when your provider only accepts calls from known IPs. |

![A gateway number's page: Carrier setup with Send calls to and Allow calls from, then its SIP configuration](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/connect/phone-number-carrier-setup-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=9637c13a2f33b09cae517b67b001c71a)

If the number's page has no **Carrier setup** card, the number connects directly: give your provider the **Origination URI** from **SIP configuration**. Carrier IPs, TLS, SRTP, codecs and pass-through headers don't apply to direct numbers.

### The gateway's addresses

The gateway uses one static IP for SIP signalling and call audio. Give these to your provider, or to whoever sets up its firewall:

| What | Value |
| - | - |
| SIP host | `sbc.tryhamsa.com`: port 5060 for UDP and TCP, 5061 for TLS |
| IP address (SIP and audio) | `34.243.238.8` |
| Audio (RTP) | UDP ports 16384 to 32767. SRTP is supported. |
| Codecs | G.711 (PCMU and PCMA) |
| DTMF (keypad tones) | RFC 2833 |

## Use SIP headers in your agent

Headers your provider sends on inbound calls are available to the agent as `{{sip.headers['header-name']}}`, with the header name in lowercase, whatever case your provider uses. For example, `{{sip.headers['x-conversation-id']}}`. On gateway numbers, only the headers listed in **Headers to pass to the agent** reach it. See [System variables](https://docs.tryhamsa.com/agents/variables/system-variables.md).

## Good to know

* Each number can be added to Hamsa once, across all projects.
* Twilio numbers are checked against your Twilio account when you add them. SIP numbers aren't checked: a wrong address only shows when a call fails.
* There's no connection test in the form. Place a test call after adding the number (see [Test a call from a number](https://docs.tryhamsa.com/agents/connect/phone-numbers.md#test-a-call-from-a-number)).
* If the **SIP address** or credentials are wrong, inbound calls can still work while outbound and batch calls fail when they dial.

## Related

> [card] [Phone numbers](https://docs.tryhamsa.com/agents/connect/phone-numbers.md)
>
> Assign the number to an agent and test it.

> [card] [Make an outbound call](https://docs.tryhamsa.com/agents/connect/outbound-calls.md)
>
> Have your agent call someone.

> [card] [System variables](https://docs.tryhamsa.com/agents/variables/system-variables.md)
>
> Read the caller's number and SIP headers in prompts.

> [card] [Batch calls](https://docs.tryhamsa.com/agents/connect/batch-calls.md)
>
> Call a list of people from the number.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.