> For the complete documentation index, see [llms.txt](https://docs.agentalk.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.agentalk.io/phone-numbers/add-a-phone-number.md).
# Add a phone number
Connect a phone number to Agentalk by purchasing one through the platform or by linking an existing number.
### Before you start
You need the following before you begin:
* An active Agentalk account.
* At least one agent created. See [**Create an agent**](/ai-agents/create-an-agent.md).
Register a phone number so it becomes available in your account.
{% hint style="info" %} **Phone Number**\
Phone numbers must be added from the **Phone Numbers** page, not from an agent’s settings.
{% endhint %}
1. Go to **Phone Numbers** from the sidebar.
2. Click **Link custom number.**\
This opens the **Link Custom Phone Number** dialog.
3. Enter phone number details:
* **Phone Number:** Enter your number in full international format, starting with `+` (e.g., [`+15551234567`](tel:+15551234567)). The field validates the format in real time and shows a green checkmark when the format is correct.
* **Nickname:** Add a descriptive name. For example, \`Main Support Line\`.\
The phone number field validates the format automatically.
4. Click **+** **Link Number.**
The number appears in your Phone Numbers list.
{% hint style="info" %} **Number activation**\
Adding a number only registers it in the system.
You must assign it to an agent to start using it for calls.
{% endhint %}
{% hint style="warning" %} **Billing note**\
If your plan does not include phone numbers or you exceed your limit, adding a number may incur an additional monthly charge.
{% endhint %}
### **Configure inbound calls for external numbers**
If your phone number is managed by an external provider (such as Twilio, Telnyx, or Plivo), you must configure inbound call routing.
{% hint style="info" %}
If you purchased the number through Agentalk, no additional setup is required.
{% endhint %}
#### **How inbound routing works**
When someone calls your phone number, the call is routed through your telephony provider before reaching Agentalk.
The process works as follows:
1. A user dials your phone number.
2. Your provider receives the call.
3. The provider forwards the call via a SIP trunk.
4. The call is sent to Agentalk (`sip.agentalk.io`).
5. Your assigned AI agent answers the call.
#### **Set up inbound SIP routing**
To receive inbound calls from an external provider, you must configure your provider to forward calls to Agentalk using SIP.
This setup ensures that every incoming call to your phone number is automatically routed to your AI agent.
Follow the steps below to configure your provider correctly.
{% stepper %}
{% step %}
### **Create or verify a SIP trunk**
A SIP trunk is required to route calls from your provider to Agentalk.
In your provider’s platform:
* Create a SIP trunk (if needed)
* Assign your phone number to the trunk
{% endstep %}
{% step %}
### Set the SIP destination
Set the inbound destination URI to:
`sip:sip.agentalk.io`
This ensures all incoming calls are routed to Agentalk.
{% endstep %}
{% step %}
### Configure inbound routing
In your provider dashboard:
* Locate inbound routing settings
* Set routing type to **SIP URI / SIP Endpoint**
* Enter: `sip.agentalk.io`
{% endstep %}
{% step %}
### Configure security (recommended)
To prevent unauthorized traffic and ensure reliable call delivery:
* Use IP whitelisting (allow provider IP ranges), or
* Configure SIP authentication (if supported)
{% endstep %}
{% endstepper %}
### Troubleshooting
If calls are not working as expected, use the table below to identify common issues and their possible causes.
| Issue | Possible cause |
| --------------------------- | ------------------------------- |
| Calls not reaching Agentalk | SIP URI is missing or incorrect |
| No audio during calls | Unsupported codec (use G.711) |
| Calls are dropped | Firewall or IP restrictions |
| Incorrect routing | Number not linked to SIP trunk |
### Provider documentation
For step-by-step instructions specific to your provider, refer to their official documentation.
* [**Twilio SIP Trunking**](https://www.twilio.com/docs/sip-trunking)
* [**Plivo SIP Trunking**](https://www.plivo.com/docs/sip-trunking/)
* [**Telnyx SIP Trunking**](https://developers.telnyx.com/docs/v2/sip-trunking)
### Next steps
Here are the recommended next steps after completing this guide:
* [**Configure and test your phone number**](/phone-numbers/configure-and-test-your-phone-number.md): Assign an agent to your number and verify that calls are working correctly.
* [**Create an agent**](/ai-agents/create-an-agent.md): Set up an AI agent to handle inbound or outbound calls.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.agentalk.io/phone-numbers/add-a-phone-number.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.