1. Tasks
  2. Make Call

Tasks

Make Call

Calls a phone number or extension through your phone system (PBX), with a voice assistant on the line. Useful for calling a lead, calling a customer back, or reminding someone of an appointment.

The call is made from a SIP connection's extension, the same way someone would dial from that desk phone. Your phone system's outbound rules pick the trunk, the caller ID and the number format. Extensions on the same phone system work too, which is a cheap way to test.

Start the voice call first with Start Voice Chat, then run this task with its voice_session_uuid. The assistant is ready the moment the person picks up.

The task doesn't wait for the call to be answered: it returns calling as soon as the call is placed. How it went follows later, in an _update_from_call with call_data.event set to outgoing:

  • result: "answered": the person picked up and is talking to the assistant.
  • busy, no_answer, declined or failed: nobody is on the line. call_data.reason says more.
NOTE

Outgoing calls must be allowed on the SIP connection first. In the manage platform, open the connection under Notifications → SIP and turn on Allow outgoing calls in the Outgoing Calls section. See Who may be called.

Basic usage

loading...

Parameters

sipconnectionuuid
required
string

The SIP connection to call from, in your organization. Its extension makes the call. Find it in the manage platform under Notifications → SIP, or in call_data.sipconnectionuuid of a call that came in on it.


to
required
string

The number or extension to call, eg 0821234567, +27821234567 or 802. Digits with an optional leading +, at most 20. Spaces, dashes, dots and brackets are removed first. The number is passed to your phone system as it is, and its outbound rules turn it into what the trunk needs.


voice_session_uuid
required
string

The voice call the person talks to once they pick up, from Start Voice Chat with channel set to call. Start it in the same action, just before this task.


ring_timeout_seconds
optional
number

How long to let the phone ring before giving up, from 5 to 50 seconds. When it runs out, the call is cancelled and the outgoing event comes back with result: "no_answer" and reason: "ring_timeout".

Default: 30

Result

loading...

Save calluuid on the stub. Once the call is answered, Collect Call Digits and Transfer Call work on it the same as on an incoming call.

The outcome follows later, in an outgoing event on _update_from_call:

        "call_data": {
  "event": "outgoing",
  "calluuid": "8c1f3a52-55c4-4c8e-9d0b-2f1f6f0e4b7a",
  "sipconnectionuuid": "161bc664-3c90-4a1e-ba07-6d1f5438dfe4",
  "to": "0821234567",
  "result": "busy",
  "reason": "486 Busy Here",
  "audio_format": { "type": "audio/pcma", "rate": 8000 }
}

      
result Meaning
answered The person picked up and is talking to the assistant. reason is null
busy The line was busy. reason is what the phone system reported, eg 486 Busy Here
no_answer Nobody picked up. reason is ring_timeout when ring_timeout_seconds ran out, otherwise what the phone system reported
declined The person declined the call, eg 603 Decline
failed The call didn't go through. reason says why, see below

Common reasons for failed:

reason Meaning
403 Forbidden The phone system or trunk refused the call, eg the extension isn't allowed to dial this number or the trunk doesn't accept its caller ID
404 Not Found, 484 … The phone system couldn't route the number. Some phone systems also report a trunk's refusal this way
503 Service Unavailable The trunk is down
no_response_from_pbx The phone system never answered
callee_hung_up The person hung up straight after picking up
no_usable_sdp_answer The phone system answered with an audio format Stubber can't use
gateway_join_failed: … The voice call couldn't be joined, eg it had already ended

Errors

message Meaning
sipconnectionuuid and voice_session_uuid are required A required param is missing
ring_timeout_invalid ring_timeout_seconds isn't a whole number from 5 to 50
unknown_connection No SIP connection with this sipconnectionuuid in your organization
connection_not_registered The connection is disabled or not logged in to the phone system. error.details has enabled and registration
outbound_not_allowed Outgoing calls aren't allowed on this connection
number_invalid to isn't a phone number or extension
number_not_allowed The connection doesn't allow this number. error.details.reason is international, or prefix when it doesn't start with one of the allowed prefixes
connection_busy The connection is already on as many calls as it allows, incoming and outgoing together
rate_limited The connection has made its maximum calls for the past hour

These are conceptual errors: no call was made. A technical error with message: "call_failed" means the call couldn't be set up on Stubber's side.

Who may be called

Outgoing calls cost money on your trunk, so each SIP connection decides what its template may call. Set these in the manage platform, in the connection's Outgoing Calls section:

Setting Default Meaning
Allow outgoing calls off Without it, make_call returns outbound_not_allowed
Country code 27 Your own country. Numbers starting with + and this code, eg +27821234567, aren't international
Allow international numbers off International numbers start with + and another country code, or with the international dialling prefix
International dialling prefix 00 What your phone system dials before an international number: 00 in most countries, 011 in North America
Allowed prefixes none When set, only numbers starting with one of these may be called, eg 0 for national numbers and 8 for extensions. Without any, every number
Max calls per hour 60 Outgoing calls in the past hour, answered or not, from 1 to 1000

Your phone system's own outbound rules apply as well.

Things to know

  • Who speaks first. With a greeting on Start Voice Chat, the assistant speaks as soon as the person picks up. Without one, it waits for their "hello" and answers it.
  • Audio format. Start the voice call as audio/pcma at 8000 (A-law, used in most of the world), or audio/pcmu (μ-law) in North America and Japan. Stubber offers both to your phone system, and converts if it picks the other one, so either works. call_data.audio_format in the outgoing event says which one the phone system picked.
  • Caller ID. The person sees the caller ID your phone system sends for the extension, set on the extension or the trunk. The task can't change it. Many providers refuse calls whose caller ID isn't one of the trunk's own numbers, often with 403 Forbidden.
  • Phone system setup. The extension needs an outbound rule for the numbers it calls (in 3CX: Outbound Rules). Check that the rule matches every form your template sends, eg a rule limited to 10 digits matches 0821234567 but not +27821234567.
  • Unanswered calls. The voice call you started waits about a minute for the call to be answered, then ends by itself. To try again straight away, end it first with a hangup, because a stub can only have one live voice call.
  • The outgoing event goes to this stub, the one that ran the task.
  • Ending the call. End an answered call like any voice call, eg with a hangup voice notification. When the person hangs up, _update_from_voice reports session_ended as usual.

Examples

Call a lead back

A form action that calls the number saved on the stub, with the assistant speaking first:

loading...

Try again later when nobody answers

On the outgoing event, schedule another attempt when the call wasn't answered:

loading...

Then, with the condition stubpost.data._incoming_call_data.call_data.result in ['busy', 'no_answer'], run Schedule Task to run the calling action again later.