HostDesk
DocumentationDashboardSign InGet Started

Acquire a phone number

This guide walks you through getting a phone number for your HostDesk voice agent so callers can reach your agent by phone, and your agent can place outbound calls.

Overview

  • Numbers are rented through the HostDesk dashboard and linked to your account (or subaccount when using multi-tenant).
  • After you purchase a number, the backend configures it so that when someone calls that number, the call is routed to your HostDesk worker (voice agent).
  • You can set one number as primary for outbound caller ID so when your agent places a call, the callee sees your number.

Step 1: Open the Numbers page

  1. Sign in to the HostDesk dashboard.
  2. In the sidebar, click Numbers.
  3. If you have not yet set up telephony (e.g. no subaccount or no numbers), you may see a Set up your phone account card. Complete that first so the system can search and rent numbers on your behalf.

Step 2: Search for available numbers

  1. On the Numbers page, use the Search section to find available numbers.
  2. Choose:
    • Country (e.g. United States).
    • Region/area code (optional) to narrow results.
    • Number type (e.g. local).
  3. Click Search (or equivalent). A list of Available numbers appears with monthly price.
  4. Review the list and pick a number you want to rent.

Step 3: Rent the number

  1. Next to the number you want, click Rent (or Purchase).
  2. Confirm the action. The backend will:
    • Reserve the number on the telephony provider.
    • Link it to your account (or subaccount).
    • Configure the voice webhook so incoming calls are sent to HostDesk and then to your voice agent (worker).
  3. After success, the number appears under Your numbers.

Step 4: Use the number

  • Inbound: When someone calls this number, the call is routed to your HostDesk voice agent (worker). No extra configuration needed once the number is rented and linked.
  • Outbound: To have your agent place calls (e.g. via the Playground “Call me” or the API/SDK), you typically need:
    • At least one number (your rented number) set as primary for caller ID.
    • Outbound SIP/trunk configured on the backend (your deployment’s telephony setup).

If your dashboard has a Primary or Set as primary action on a number, use it so that number is used as caller ID for outbound calls.

Step 5: Remove a number (optional)

If you no longer need a number:

  1. Find it under Your numbers.
  2. Click Remove (or Release).
  3. Confirm. You will stop being billed for it and the number returns to the pool. You cannot get the same number back unless you search and rent it again (it may be taken by someone else).

Troubleshooting

  • No numbers available: Try a different region or area code, or another number type.
  • Rent fails: Ensure your phone account (or subaccount) is set up and that billing is configured (e.g. payment method) so the provider can charge you.
  • Calls not reaching the agent: Confirm the number is linked to your account and that the HostDesk worker is running and registered so the backend can dispatch the agent to the call’s room.

For API-level details (e.g. listing or releasing numbers programmatically), see your deployment’s API docs or the backend routes under /api/telephony/numbers.