Bring your own carrier
Bring your own carrier (BYOC) lets you send and receive calls through a carrier you already have a contract with, instead of PressOne's own routes to the phone network. You keep your carrier, its rates and its numbers. Signals carries the calls between that carrier and your trunks or voice applications, applies the limits you set, and records every call.
You connect a carrier with a carrier connection. Its ID starts with byo_, for example
byo_01a19b7e-deee-779d-953d-a3f8be2d1617. In the console, carrier connections are under
Carriers.
How a connection works
A connection brings together these parts:
| Part | What it controls | Field or endpoint |
|---|---|---|
| Direction | Whether the connection carries calls from your carrier, to it, or both. | direction: inbound, outbound or both |
| Hostname | The address your carrier sends calls to. Signals derives it from the name. | signaling_fqdn |
| Authentication | How Signals recognises calls that come from your carrier. | ingress_sources, generate_password, then /byoc/connections/{connection_id}/ingress-credentials |
| Inbound destination | The trunk that rings when a call arrives for one of the connection's numbers. | inbound_trunk_id |
| Peers | Where Signals sends outbound calls: the SIP addresses of your carrier. | peers on create, then /byoc/connections/{connection_id}/peers |
| Numbers | The numbers your carrier holds for you, which this connection carries. | POST /numbers/hosted |
| Limits | How many calls run at once, how fast new calls start, and how long a call may last. | ceilings |
| Media | Which audio codecs the connection offers and whether audio is encrypted. | g729, media_security |
A connection that takes inbound calls (inbound or both) needs an inbound destination and at least
one authentication method. A connection that sends outbound calls (outbound or both) needs at
least one peer. The API refuses an enabled connection that is missing either.
Create a connection
In the console, open Carriers and choose Connect a carrier. The steps are Basics, Peers, Authentication, Inbound destination, Numbers and Review. With the API, send everything in one request:
Code
The API answers 201 Created with the connection under connection, and password set when you
asked for one with "generate_password": true. The password is shown once. Store it before you
leave the page or discard the response.
- The name is lowercase letters, digits and hyphens, and starts and ends with a letter or digit.
Trunks and connections share one set of names, so a name a trunk already uses is refused with
409 carrier_connection_name_conflict. inbound_trunk_idmust name a trunk of the same project that takes inbound calls. Omitting it on an inbound connection returns422 inbound_trunk_required; sending it on anoutboundconnection returns422 inbound_trunk_not_allowed. A trunk that cannot take calls returns409 carrier_connection_target_conflictwith areason, as in Numbers and routing.- Edits use
PATCH /byoc/connections/{connection_id}with the connection's ETag inIf-Match, as for trunks. See Revisions and ETags.
What to give your carrier
Your carrier needs four things from you. The console shows them together on the connection's page and on the completion page after you create it.
| Item | Value |
|---|---|
| Where to send calls | The connection's hostname, for example airtel-direct.sip.trunk.pressone.co. |
| Ports | SIP over UDP and TCP on 5060, and SIP over TLS on 5061. |
| Signals addresses | signaling_nodes and media_cidrs from platform endpoints, for your carrier's firewall. |
| Credentials | The username and password, if the connection uses a password. The realm is the hostname. |
Your carrier must send calls to the connection's hostname, not to sip.trunk.pressone.co or an IP
address. Signals identifies the connection by the hostname a call is addressed to. A call to the
bare domain is treated as a trunk call and is not matched to your connection.
Authentication
Signals must know that a call really comes from your carrier before it carries it. A connection uses an IP list, a password, or both:
- IP list: Signals accepts calls only from the networks in
ingress_sources. A call from any other address is refused with403and no challenge. - Password: your carrier answers a digest challenge with the connection's username and password. The realm is the connection's hostname.
- Both: a call must come from a listed network and answer the challenge.
POST /byoc/connections/{connection_id}/ingress-credentials generates a password when the
connection has none. To change it, rotate it with
POST /byoc/connections/{connection_id}/ingress-credentials/{credential_id}/rotate. The response
shows the new password once, and replaced_valid_until tells you how long the old password keeps
working, so your carrier can switch over without dropped calls.
If you rename a connection, its hostname changes with it. Passwords keep the realm they were generated with until you rotate them; the next password uses the new hostname.
Numbers your carrier holds
Numbers your carrier gives you are hosted numbers. You import them onto the connection so Signals knows which connection a call to each number belongs to:
Code
One request takes 1 to 5,000 distinct Nigerian numbers in E.164 form. Signals groups consecutive numbers into blocks of at most 1,000 and answers with the blocks it created. Hosted numbers carry no setup or monthly fee from Signals; your carrier bills you for them.
A call your carrier sends for a number that is not imported on that connection is refused with
404 NUMBER_NOT_REGISTERED, even if the number is imported on another of your connections.
Where hosted numbers ring
A number's route decides where a call goes. The connection fills in the route for its numbers:
- A hosted number with no route rings the connection's inbound destination trunk.
- You can route a hosted block, or a slice of it, to any trunk or voice application, exactly as you route a Signals block. See Route numbers to a trunk.
- A
nulltarget on a hosted slice returns those numbers to the connection's trunk.
If a route points at a trunk that cannot take calls, for example one that is suspended, the call is
refused with 480 DESTINATION_UNAVAILABLE. It does not fall back to the connection's trunk.
A hosted number is also a caller ID: a trunk may present the hosted numbers that ring it, and a voice
application may use a hosted number as its From.
Outbound calls
The caller ID decides how an outbound call leaves. A call whose caller ID is one of the connection's hosted numbers goes out through that connection; a call whose caller ID is a Signals number goes out through PressOne. You do not choose per call.
Signals tries your peers with the lowest priority value first. Peers that share a priority split
calls by weight. A peer has peer_timeout_seconds to answer. If it does not, or it answers with
one of the failover_sip_codes, Signals tries the next peer. attempt_deadline_seconds limits the
whole attempt and must be longer than the peer timeout.
Signals never sends a connection's call through PressOne's routes. If every peer fails, the call
fails. If the connection is disabled or does not send outbound calls, a call with its caller ID is
refused with 503 EGRESS_UNAVAILABLE.
These settings shape the call your carrier receives:
| Field | What it does |
|---|---|
number_format | How the dialled number is written: e164_plus (+2348031234567), e164 (2348031234567) or national (08031234567). |
tech_prefix | One to fifteen digits put before the dialled number, if your carrier asks for one. |
strip | Leading digits removed from the dialled number, up to 14. |
identity_policy | from_only sends the caller ID in From; from_and_pai also sends it in P-Asserted-Identity. |
privacy_passthrough | true passes the caller's privacy request on to your carrier. |
media_security | rtp or sdes_srtp_required. Encrypted media needs every peer on tls. |
From a voice application
Calls from a voice application follow the same rule: the From number decides. The Calls API also
accepts Byoc with the connection ID, as Twilio does. It must name the connection of the From
number, or the call is refused. <Dial byoc> and <Number byoc> work the same way in OneML.
Refused calls
Calls your carrier sends can be refused before they ring anything. The reply tells your carrier why:
| Reply | Meaning |
|---|---|
404 UNKNOWN_HOST | The call is addressed to a name under sip.trunk.pressone.co that is not a connection or a trunk. Check the hostname for a typo. |
403 SOURCE_NOT_PERMITTED | The call came from an address that is not on the IP list, or the connection is disabled or does not take inbound calls. |
407 | The connection uses a password, and the carrier has not answered the challenge yet. |
403 AUTHENTICATION_FAILED | The username or password is wrong. |
404 NUMBER_NOT_REGISTERED | The dialled number is not imported on this connection. |
480 DESTINATION_UNAVAILABLE | The number's route, or the connection's trunk, cannot take calls. |
Refusals after authentication appear in your call history as rejected calls on the connection's
trunk, with their SIP code and the connection. They are never charged. Refusals before
authentication, 403 from the IP list and wrong passwords, are not calls: the connection's
refusals field counts them and shows the last time, source address and reason. The count is
approximate, because Signals writes it at most once a minute per connection.
Pricing
A call through a connection is charged a flat platform fee per minute instead of PressOne's
destination rates, under call.byoc.inbound and call.byoc.outbound. Your carrier bills you for
the call itself. There is no fee for the connection or its numbers. Your rates are in the console
under Billing. Spend caps and daily budgets in your outbound policy
count BYOC calls at this fee.
Disable or release a connection
POST /byoc/connections/{connection_id}/disable stops new calls through the connection; calls in
progress continue. POST /byoc/connections/{connection_id}/enable allows them again.
DELETE /byoc/connections/{connection_id} releases a connection. You confirm the exact connection
name in the body. The API refuses with 409 carrier_connection_referenced while the connection
still has hosted numbers. Remove them first with DELETE /numbers/hosted/{block_id}. A trunk that is
a connection's inbound destination cannot be released until you choose another destination for the
connection.
Related
- Numbers and routing explains routes, which hosted numbers use too.
- Authentication and security covers TLS and encrypted media.
- Carrier connections API reference and Hosted numbers API reference