ubuntu-post-install/docs/anveo-direct-setup-guide.md

Anveo Direct + Easy Asterisk — confirmed working setup guide

This is the exact sequence that got a real Anveo Direct DID working end to end (both outbound and inbound) with asterisk.sh + pstn-trunk.sh, confirmed live on a real droplet.

Steps 1, 3 and 4 are one-time account setup — the outbound Service Trunk (step 3) and the inbound SIP Trunk (step 4) each cover every DID on the account, no matter how many you add. Only steps 2, 4.5, 6 and 7 repeat per number: order the DID, point it at the existing inbound trunk (skippable entirely if you set the account default in step 4.6), assign it in the dashboard, and test.

0. Prerequisites

• asterisk.sh already installed and running (droplet or home/LAN — the installer detects which), with at least one extension configured.
• This box's public IP address (curl -4 ifconfig.me).

1. Anveo Direct account (one-time)

1. Create an account at https://www.anveo.com/account.asp?account_type=direct — this is what makes it a Direct account (trunk/DID product), not the hosted-PBX product.
2. Fund the account balance directly (not a subscription plan). Bank transfers can take several hours to clear.
3. Known account-level caps as of this writing, both separate from anything this installer enforces:
   • Trial account limits: 2 concurrent outbound calls (CPS: 2), $2/30-day spend limit, $2 minimum balance — shown on the Outbound Trunks page under "Account Limits." A "request higher limits" link sits next to the CallerID Policies section for asking Anveo to lift these once funded.
   • Phone Numbers cap: "You can manage up to 2 phone numbers. Please contact customer support to increase the limit" — a separate cap from the concurrent-call limit above, shown on the Phone Numbers summary page. Anveo indicated (not independently confirmed) that removing this requires providing a tax ID (EIN for a business, SSN for an individual) — decide for yourself whether that trade-off is worth it before planning on more than 2 DIDs.
4. CallerID policy: USA/Canada/international destinations all require CallerID from a verified/Anveo-owned number — any DID ordered through Anveo satisfies this automatically.

2. Order a DID

1. Go to the DID ordering tool ("Phone Numbers around the World" / similar), pick a number, and select the Per Minute rate plan — not Prime.
   • Per Minute: $0.004/min incoming, 10 dedicated incoming channels bundled in, no separate trunk product needed for inbound.
   • Prime: free incoming, but requires a separately-purchased "Anveo Trunk" (a different product — flat monthly fee, $6.50–$17/mo by zone, confirmed via the "Anveo Direct Trunk Price List" page). Per Minute avoids this fee entirely, which is why it's the one to use.
2. Confirm: $0.25 one-time setup, $0.15/month recurring (billed the 15th), 3-month minimum term, pre-paid from account balance.

3. Create the Outbound Service (Call Termination) Trunk

This only needs to be done once — the same trunk carries outbound calls for every DID/extension. Skip this step for DIDs 2+.

1. Outbound Trunks → Add a new Call Termination Trunk.
2. Fill in:
   • Title: any label (e.g. asterisk-do)
   • Dialing Prefix: leave blank — confirmed not required (no red "required" asterisk on this field, unlike Authorized IP Addresses and Call Routing Method). The dialplan here dials the bare number, no prefix.
   • Authorized IP Addresses: this box's public IP, one per line. This is the IP-authentication Anveo uses instead of a SIP password.
   • Rate Cap: optional safety ceiling — e.g. Yes, $1/min filters out any route pricier than that. Domestic US termination runs far below this, so it doesn't interfere with normal calls, just blocks getting routed onto an absurdly expensive carrier by accident.
   • Concurrent Calls Limit: whatever you want as an Anveo-side cap (e.g. Yes, 6) — note the account's Trial "Outbound Channels: 2" limit (see step 1) overrides this until lifted; whichever number is lower wins.
   • Call Routing Method: leave the default Custom Least Cost Routing Model and all of its sub-fields (All Prime Routes / cost lowest-to-highest / 5 routes / cost-ordered failover / 10 sec timeout) exactly as shown — sensible defaults, nothing to tune here.
3. Save.

Finding the real outbound rate

The trunk's LCR pulls from "All Prime Routes" by default — meaning your real per-minute cost is whatever's in the Anveo Direct Prime rate card (Outbound Services/Call Termination page → "Download rates here" under the Prime column, not Value/Standard/All). Confirmed from that CSV: standard US-to-US domestic is a flat $0.00388/min, billed per-second (not rounded to the minute) — this is the generic USA. catch-all entry (prefix 1); a few specific area codes have their own slightly different override rates, and Virgin Islands is billed separately/higher (~$0.02/min) despite looking like a normal US number.

4. Create the SIP Trunk (inbound forwarding) — ONE covers every DID

Anveo has two unrelated "trunk" concepts — don't confuse them:

• The Outbound Service Trunk from step 3 handles calls out.
• A separate "SIP Trunk" object (Account Options → wherever inbound routing objects live) handles calls in — this is what actually populates a DID's "Destination SIP Trunk" dropdown.

You only need ONE of these for the whole account, no matter how many DIDs you have. The $[E164]$ placeholder in step 2 is what makes it reusable — Anveo substitutes each DID's own number at call time, so the same trunk object forwards 15551111111@IP:5060 for one DID and 15552222222@IP:5060 for another. The Asterisk side matches whatever arrives (_X. in [from-pstn-trunk]) and looks it up in pstn-personal-dids.conf to decide who rings. Creating one per DID is possible but pointless unless different DIDs need to forward to genuinely different destinations.

Create it once (steps 1–4), then per DID only step 5 applies — or set the account default in step 6 and skip even that:

1. Trunk Name: any label (e.g. asterisk-do-inbound).
2. Primary: type SIP URI, value:

   $[E164]$@<this box's public IP>:5060
   

   (port 5060 — Easy Asterisk's default SIP port, confirmed from its own vendor source DEFAULT_SIP_PORT="5060"). The $[E164]$ placeholder is replaced by Anveo with the DID's own number, digits only, country code included, no + — e.g. DID +15551234567 becomes 15551234567@IP:5060 in the actual INVITE Anveo sends.
3. Failover: leave blank.
4. Save.
5. Per DID: go to that DID's Call Options tab → set Destination SIP Trunk to this SIP Trunk object (not the Outbound Service Trunk) → Save.
6. Recommended if you have more than one or two DIDs: Account Options → Service Defaults → set Default Destination Trunk to this SIP Trunk. New DIDs then auto-route here and step 5 becomes unnecessary entirely.

5. Configure the droplet

sudo ./setup.sh pstn-trunk

• Existing install → choose update (r) if you're just changing the DID/server, or the CLI will walk fresh prompts if none exists yet.
• Provider quick-pick: 1) Anveo Direct — pre-fills sbc.anveo.com and Anveo's 4 published signaling IPs (only one of which the hostname itself resolves to at any given moment; the others are entered as "additional known source IPs" so inbound is recognized regardless of which one a call actually arrives from).
• DID: 10 digits, no leading 1 (e.g. 5551234567).
• Outbound per-minute rate: 0.00388 (see step 3's rate-lookup note) — pre-filled automatically when Anveo Direct is the selected provider.
• Concurrent-call caps, ring-group extensions, ntfy topic, spend-cap kill-switch thresholds: set to taste (all live-editable later without reinstalling).
• Who can call/be called (permission tiers, approved numbers), internal SIP messaging, and personal-number assignment are not prompted here — set them all in the Security Dashboard's PSTN Trunk tab instead (install it first if you haven't: sudo ./setup.sh security-dashboard). Every extension starts at internal (no PSTN access) until granted there.

6. Grant permissions and (optionally) a personal number

In the Security Dashboard's PSTN Trunk tab:

1. Set the tier for each extension that should get PSTN access (full or restricted — restricted also needs at least one approved number).
2. Personal numbers card: assign this DID to a specific extension if you want inbound calls to it to ring only that extension (instead of the whole shared ring-group) and its outbound Caller-ID to show this DID instead of the shared trunk DID. Enter the DID as 10 digits, no leading 1 (matches the same convention as the trunk DID above) — the dashboard's own input validates against exactly that format. You can assign the DID to a group instead of a single extension — pick Group: <name> in the owner dropdown (create the group first under Groups if it doesn't exist yet). Every current member whose own tier/approved-numbers authorize the caller rings, checked fresh on every call, so membership changes apply immediately with no reinstall. A group has no single extension to hang an outbound Caller-ID override on, so the Caller-ID-override part above only applies to single-extension assignments.

7. Test

• Outbound: from a full/restricted-tier extension in Sipnetic, dial 1 + area code + number (11 digits total — the dialplan matches the full NANP pattern, not a bare 10-digit number without the leading 1).
• Inbound: from any outside phone, dial the DID's real number. If a personal number was assigned, only that extension should ring; if not, the whole configured ring-group rings simultaneously until someone answers or 20 seconds pass.
• Watch the live console while testing either direction:

  docker exec -it easy-asterisk asterisk -rvvv
  # on a droplet set up before the two Asterisk services were merged, the
  # container is named easy-asterisk-do instead
  

8. SMS — receiving verification codes

Voice and SMS are separate features on an Anveo DID and are configured in different places. This section covers receiving only; see "What about sending?" below for why.

Pick the right kind of number first

Anveo sells two classes of US DID, and for verification codes the difference matters more than anything else in this section:

• Geographic (default) — the cheap ones this guide orders in step 2 ($0.25 setup, $0.15/month). Industry lookups classify these as VoIP.
• Mobile — a separate pool sourced from wireless carriers, available across roughly 20 major US city area codes (released on Anveo Retail first, then Direct). These are classified as mobile in the same databases that services query when they decide whether to accept your number. Priced above the geographic ones — check the DID ordering tool for the current rate.

Plenty of services (Google, WhatsApp, Microsoft, many banks) reject a number that looks like VoIP at signup, before any message is ever sent. If codes are the reason you're buying the number, order a mobile one — no amount of correct SMS routing fixes a signup form that refuses the number outright.

Short codes

Most verification codes come from short codes (262966, 32665, ...), and most VoIP providers don't deliver them at all — VoIP.ms, for instance, doesn't except for Google, and users there report a large fraction of 2FA codes never arriving. Anveo is unusual in supporting short-code SMS to its DIDs, which is the main reason it's worth using for this.

Not every number in the pool has it enabled, so confirm on your specific DID (or ask support to turn it on) rather than assuming.

Wire it up

Run the installer and follow what it prints:

sudo ./setup.sh sms-inbound

It generates a long random ntfy topic, then offers two ways for Anveo to reach it:

• Relay (recommended) — a small systemd service on the droplet receives Anveo's request and republishes to ntfy properly. Two concrete wins: a message body containing & survives intact (Anveo interpolates the text into the query string unescaped, so an unencoded & otherwise truncates the message), and your ntfy credentials never get stored in Anveo's portal.
• Direct — Anveo calls ntfy itself; nothing runs on the droplet. Simpler, but the URL you paste into Anveo carries your ntfy token, and the & case loses the tail of the message.

Then in the Anveo portal: Phone Numbers → the DID → SMS tab, set the destination to URL, and paste the string the installer printed. Keep the $[message]$ placeholder last — that's what makes the unescaped-& case recoverable.

Send a text to the number from another phone; the notification should arrive within seconds. journalctl -u sms-inbound -f shows sender, recipient and message length (never the body — these are one-time passcodes and the journal has a wider audience than the notification does).

What about sending?

Not covered, on purpose. Outbound SMS isn't available on Anveo Direct — Anveo support directs users to an Anveo Retail account for it, which is a second account to fund and manage. Any of the free texting apps covers sending without involving this box.

MMS and group texts

Don't plan on either. No VoIP provider delivers MMS over SIP, and MMS to a VoIP DID generally drops or arrives as a media link through a separate API. US group texts are MMS, so a SIM-less phone on this number will silently miss them.

The native Messages app never sees these

Android's Messages app reads the telephony SMS provider, which only the cellular radio (or whichever app holds the default-SMS-app role) writes to; iOS lets nothing write to Messages at all. Codes arrive as ntfy push notifications instead — which, for a passcode you're about to read and type, is the more useful place anyway.

Bugs hit and fixed along the way (informational — already fixed)

These were all real, confirmed-live bugs in earlier versions of this installer, not configuration mistakes — listed here for context on what "just works" now that didn't before:

• NANP dial pattern was one digit short (_1NXXNXXXXX / _NXXNXXXXX, 10/9 characters instead of the correct 11/10) — Asterisk's exact-length pattern matching never matched a real number at all.
• ${CHANNEL(peername)} isn't a valid channel-function item on this Asterisk build — broke the caller-extension lookup used for every permission check.
• ${EXTEN} corruption after Goto to a named extension — every Goto(somelabel,1) to a different extension (not a same-extension priority label) resets ${EXTEN} to that label's own name, silently breaking the approved-numbers check, the international country check, and the final Dial() itself. Fixed by capturing the real dialed number into its own variable before any such jump.
• Duplicate ring-group extensions (the same extension listed twice in RING_EXTS) generated duplicate dialplan priority labels, causing an infinite loop that never reached the ring step at all. Now deduped automatically.
• Personal-DID lookup format mismatch — DIDs are stored 10-digit, but Anveo delivers the called number as 11-digit E.164 in ${EXTEN}; the lookup now normalizes to 10 digits first.
• Easy Asterisk only regenerates pjsip.conf/extensions.conf if they don't already exist — a box that already has devices configured (the normal case) never picks up a vendor-script #include patch on a plain restart. Both the PSTN trunk and internal-messaging installers now also patch the live config files directly, not just the generator source.
• A stale/malformed .pstn-trunk.env could crash the entire installer under setup.sh's set -u on source. Now guarded and falls back to safe defaults, erroring clearly only if genuinely required fields are missing.
• The inbound [from-pstn-trunk] context never loaded at all — it used to share one #include'd file with the outbound dialplan, where the file continued [intercom] first and only declared [from-pstn-trunk] partway through. Asterisk silently failed to load the entire file (outbound patterns included) with no error anywhere, so every inbound call got "extension not found in context 'from-pstn-trunk'" and an immediate SIP rejection. Inbound now lives in its own file that starts with its context header, matching the structure of the messaging dialplan that always loaded correctly.
• Every inbound call's Caller-ID arrived as the DID itself, not the real caller — the trunk endpoint pinned a static callerid=<DID> and didn't set trust_id_inbound, so Asterisk ignored the identity Anveo actually sends and fell back to that default. Every restricted-tier allowed_numbers check was therefore unwinnable regardless of config. Fixed by dropping the static default (redundant — the outbound dialplan sets CALLERID(num) on the channel itself) and adding trust_id_inbound=yes.
• A leading + broke whitelist matching — once the fix above started surfacing real caller identity, Anveo delivers it +E.164 style (+15551234567). The normalizer only added a leading 1 to 10-digit values and never stripped the +, so a 12-character value could never match an 11-digit, digits-only allowed_numbers entry no matter how correctly the number was whitelisted. The + is now stripped in the dialplan, the group-ring script, and the dashboard's admin-input side (so pasting a number straight from a call log works too).
• Bare Hangup() on inbound denials instead of Busy(15) — three inbound denial paths didn't produce a proper "486 Busy Here", making a correct permission denial sound like a generic call failure and disguising config mismatches as dialplan bugs.

Dashboard changes may need "Commit Changes"

Confirmed live: edits made in the Security Dashboard's PSTN Trunk tab (permission tiers, groups, personal-DID owners, limits) are written to disk immediately, but AST_CONFIG() in the dialplan has been observed still returning the old value until the Asterisk container is fully restarted — a dialplan reload / module reload is not enough. This contradicts the "reads fresh on every call, no restart needed" design premise these files otherwise rely on; root cause not established.

The PSTN Trunk tab has a Commit Changes (Restart Asterisk) button for this, which appears after any save on that tab and warns if you navigate away with changes uncommitted. Existing calls are unaffected by the restart. If a change doesn't seem to be taking effect on a test call, press it before assuming the config itself is wrong.

Still open

• Nothing blocking. The two items previously listed here are both resolved: the 2-phone-number account cap no longer applies (additional DIDs have since been obtained), and the interactive CLI walkthrough was built — see _pstn_anveo_walkthrough in services/pstn-trunk.sh, reachable from the provider quick-pick when you choose Anveo Direct.