Buy a number and point it at your app

Voicephone number provisioning

Search by area code or pattern, purchase, and assign the number's call and message handlers, all over REST.

numberscall-fabric

The claim

Numbers are a REST resource. Three calls take you from nothing to a number that dials your code. Search inventory by area code, region, city or digit pattern; purchase the number; set its call handler to a SWML URL. No Dashboard step, so it can run inside your own onboarding flow.

How it works

client.phone_numbers.search(areacode="415", number_type="local", max_results=5)   # GET  /api/relay/rest/phone_numbers/search
client.phone_numbers.create(number="+14155550123")                                 # POST /api/relay/rest/phone_numbers
client.phone_numbers.update(number_id, call_handler="relay_script",                # PUT  /api/relay/rest/phone_numbers/{id}
                            call_relay_script_url="https://<your-host>/ivr")

call_handler: relay_script with call_relay_script_url routes inbound calls to a SWML document, the same thing the Dashboard’s “SWML webhook” handler does. The other handlers on the same field route to a Relay topic, a cXML URL, or a Dialogflow agent; message_handler fields do the same for SMS. Lookup (carrier and CNAM) is a sibling call on the same namespace. See look-up-a-callers-carrier-and-name.

Purchasing is billable and immediate. Releasing is DELETE on the same resource.

What to change first

Point the number at the build-an-ivr-menu document, then add register-an-e911-address-for-a-number before the number takes real calls.

Where this sits

Verify a webhook signature

Answer an inbound call Send an SMS

python/app.py

"""Buy a number and point it at your app.

Three REST calls: search available numbers by area code or pattern, purchase
one, and set its call handler to your SWML URL. After the third call, dialling
the number fetches your document.

Written against signalwire-sdk 3.0.1 (RestClient.phone_numbers).

    python app.py search 415            # list candidates
    python app.py buy +14155550123 https://your-host/ivr
"""
import os
import sys

from dotenv import load_dotenv
from signalwire.rest import RestClient

# the SDK does not read .env for you
load_dotenv()

# reads SIGNALWIRE_PROJECT_ID / SIGNALWIRE_API_TOKEN / SIGNALWIRE_SPACE from the env
client = RestClient()


def find(areacode=None, contains=None, number_type="local", max_results=5):
    """Search inventory. Returns the list of candidate numbers (E.164)."""
    params = {"number_type": number_type, "max_results": max_results}
    if areacode:
        params["areacode"] = areacode
    if contains:
        params["contains"] = contains
    res = client.phone_numbers.search(**params)
    return [n.get("e164") or n.get("number") for n in res.get("data", [])]


def buy(number):
    """Purchase a number. Returns the phone number resource (id, number, ...)."""
    return client.phone_numbers.create(number=number)


def point_at(number_id, swml_url, name=None):
    """Route inbound calls on the number to a SWML document at swml_url."""
    body = {"call_handler": "relay_script", "call_relay_script_url": swml_url}
    if name:
        body["name"] = name
    return client.phone_numbers.update(number_id, **body)


def provision(areacode, swml_url, name="recipes"):
    """Search -> buy the first candidate -> point it at swml_url."""
    candidates = find(areacode=areacode)
    if not candidates:
        raise SystemExit(f"no numbers available in {areacode}")
    bought = buy(candidates[0])
    point_at(bought["id"], swml_url, name=name)
    return bought


if __name__ == "__main__":
    cmd, *rest = sys.argv[1:] or ["search", os.getenv("AREACODE", "415")]
    if cmd == "search":
        for n in find(areacode=rest[0]):
            print(n)
    elif cmd == "buy":
        number, url = rest
        bought = buy(number)
        point_at(bought["id"], url)
        print(f"{bought['number']} -> {url}")
    elif cmd == "provision":
        areacode, url = rest
        print(provision(areacode, url))

Run it

cd python
pip install -r requirements.txt
export SIGNALWIRE_SPACE=... SIGNALWIRE_PROJECT_ID=... SIGNALWIRE_API_TOKEN=...
python app.py search 415
python app.py buy +14155550123 https://<your-host>/ivr

Verify it

python verify.py          # from the recipe folder, not python/

With the HTTP layer replaced by a recorder, provision() must make exactly three requests in order:

GET search, then POST purchase, then PUT update
each checked against tools/openapi/rest.json for path, method, documented fields and required fields
the URL the number is pointed at is the one passed in

Report an issue

Buy a number and point it at your app

The claim

How it works

What to change first

Where this sits

Related

Next