Phone numbers
A number belongs to an org and points at one agent, in the sandbox or in production: inbound, outbound, and the ways to get one.
A number belongs to your org and points at one agent, in the sandbox or in production. People call it or write to it, and that agent answers. Which agent answers is a setting you change in the console or the CLI, not something in your code, so moving a number never needs a deploy.
What is a number on Pinecall?#
A number is one row the org keeps: the number, its channel (phone or whatsapp), the agent that
answers, and whether it answers in the sandbox or in production. Your agent's class names no number. When pinecall start
connects, it prints the numbers the agent answers at, read from that row.
Every agent can also be reached from a web page, through the web widget, with no number at all.
The ways to get one#
| way | what you do | the number lives | can call out | page |
|---|---|---|---|---|
| Buy one here | pick a country and an area code | on Pinecall's own Twilio account | no | Twilio |
| Twilio | connect your Twilio account once | on your Twilio account | yes, after you turn it on | Twilio |
| Telnyx, Vonage, Plivo | paste one address into the carrier's portal | at that carrier | no | Telnyx, Vonage, Plivo |
| Your own PBX, or another carrier | declare a SIP peer, and Pinecall approves its addresses once | on your PBX or at your carrier | yes, if you give it an outbound host | SIP & your own PBX |
| connect a WhatsApp Business number at Meta | at Meta | no: WhatsApp is written |
The console offers only the ways your gateway allows: buying appears only where Pinecall sells numbers, and a carrier appears only once it is enabled.
Adding a number#
In the console, open Numbers ▸ Add a number. It asks where the number lives first, then shows the form for that way. For Twilio and buying, it shows every step it will take before it takes any.
From a terminal, a number that one of the org's accounts already owns is two commands:
$ pinecall carriers add twilio --account-sid AC0123… --user SK4567… # once; the secret on stdin
$ pinecall numbers import +34910000000 --agent clinica-norte --prodpinecall numbers import acts in the sandbox unless you add --prod. Add --dry-run to print the
steps and write nothing. It has no flag to name an account, so it works while the org holds one
carrier account; with more than one (a Twilio account and a WhatsApp number, say) the gateway
refuses it and names them, and the number is added from the console instead.
The Numbers screen is on production's console, and adds numbers to production. A sandbox number is optional: you can test on the production number from your own phone with
pinecall line from(Sandbox and production).
Inbound#
The Numbers screen lists each number with what a call to it does now:
| the screen says | means |
|---|---|
| Rings the agent | a call reaches the agent |
| Not reaching us yet | waiting for its first call, or for an approval |
| Not answered | nobody is running the agent the number points at |
Open a number to see its path: the carrier, the fence (which addresses may send its calls), sandbox or production, and the agent, each with what would fix it, and when the last call arrived.
To point a number at another agent, add it again with the other agent. It moves on the next call. Remove stops the number reaching Pinecall; your carrier account keeps it. Move to sandbox moves it out of production.
One number belongs to one org. Adding a number another org already holds is refused.
Outbound#
An agent can place a call from one of its own numbers, through the carrier account that number lives in. Only two kinds of account can dial:
- your own Twilio account, once you turn on outbound calls on the Numbers screen's Calling out tab;
- a SIP peer that declared an outbound host.
A number bought through Pinecall, or one you pointed here from a carrier's portal, dials through no account of yours, so it cannot call out. Every call out passes the org's dialling rules first: who may be called, when, and how often. Calling out covers them.
Pinecall does not handle number porting, emergency calls, SMS or caller-name lookup. Those stay with your carrier.