Calling out
Outbound calls: which numbers may dial, the dialling rules, and a call back from the console.
An agent can place a phone call: to call a customer back, or to call somebody your backend names. The call goes out from one of your org's own numbers, through your own carrier account, and every dial passes a set of rules first.
How it works#
outbound in its log.
Pinecall dials only through an account of the org's. A number Pinecall sold you, or one you pointed at Pinecall from a carrier it does not drive, answers calls but places none.
Turn on outbound calls#
Connect a carrier and a number#
On production's console, Numbers ▸ Add a number, with a Twilio account or a SIP peer. The agent must answer at a phone number there. See Twilio and SIP & your own PBX.
Review the plan#
Under Numbers, press Turn on outbound calls. The console lists what will happen on your carrier account and on the gateway. For Twilio: a trunk pointing at Pinecall, its termination address, a credential list and the org's credential on it. A SIP peer needs nothing written: it is dialled at the host it gave.
Confirm#
Press Confirm. The panel turns On and names the numbers agents call from.
Make a test call#
Under Make a test call, pick an agent and a number and press Call. Watch it live opens the call.
The same from your own code: GET /v1/carrier/outbound says what is missing, and
POST /v1/carrier/outbound?dry_run=true returns the plan without writing anything.
Place a call#
| from | how |
|---|---|
| the console | Call back on a conversation in Calls, or the + that dials a number as the agent in view |
| your backend | POST /v1/agents/{slug}/dial with { "to": "+14155550142" }, on a key that opens talk |
| your page | dial() from @pinecall/room/server, behind a route of your own server |
The dial answers 202 with the call's id and a log_token for following it. from picks which of
the agent's numbers is shown; it defaults to the first. The agent must be held by a running process,
or the dial is refused before anything rings.
curl -X POST https://cloud.pinecall.io/v1/agents/front-desk/dial \
-H "authorization: Bearer $PINECALL_KEY" -H "pinecall-env: production" \
-H "content-type: application/json" \
-d '{"to": "+14155550142", "consent": {"kind": "express", "source": "booking form"}}'The rules every dial passes#
In this order. A dial refused by one rings nobody, and the gateway's answer says which rule refused:
| rule | refuses when | where |
|---|---|---|
shape |
the number is not E.164, too short, or a satellite or global-service range | sandbox and production |
stranger |
the number never called or wrote to the org there | sandbox and production |
do_not_call |
the number is on the org's do-not-call list | production |
no_consent |
a +1 number, or any number when the org asks for consent everywhere, has no consent on file and none sent with the dial |
production |
quiet_hours |
it is outside the hours the number may ring, in its own time zone. A +1 number never rings before 8:00 or after 21:00 |
production |
too_fast · too_many |
the org already dialled 6 times in the last minute, or 200 times in 24 hours | sandbox and production |
too_often |
the number was rung too many times in 24 hours. A +1 number: 3 unless the org sets another limit |
production |
By default, every call placed also ends after 600 seconds. The defaults for strangers, the pace and the length are set per org by whoever runs the gateway, not by the org: the console shows them as one line under Numbers. The calling hours, the per-number limit and consent everywhere are the org's own, in Data & privacy.
In the sandbox, and to the phone you named as yours with
pinecall line from, the do-not-call list, consent, calling hours and the per-number limit do not apply. The shape, stranger and pace rules still do.
A consent sent with the dial is written to the number's record before anything rings. It never
lifts the do-not-call list: only a consent recorded with pinecall data consent or on the console
does. Which countries the call may reach is also your carrier account's own setting, such as
Twilio's geographic permissions.
What the caller hears first#
An outbound call opens with a disclosure in the agent's voice, before its greeting: by default "This is an automated assistant calling on behalf of …" in the agent's language. A recorded call then says "This call may be recorded." Both are set in Data & privacy.