Setting up call forwarding in KAZOO

James Aimonetti — Mon, 06 Apr 2020 21:59:59 GMT

With the transition to working from home in full swing, let's look at the ways KAZOO makes it easy to bring your office with you!

From Scratch

Let's say you are a solo business owner who needs to forward your business phone calls to your personal mobile phone. Assuming the business phone number is provisioned for the account already, here's the basic steps to set that up!

Setup the callflow

A callflow in KAZOO is what is executed when a configured phone number, extension, or regexp matches the incoming call. The flow portion will then be a series of actions (like ringing devices, going to voicemail, sending to the carrier, etc) chained together to control how the caller progresses through the call.

Since you want to forward calls from your business number to your mobile, you'll need to use the resources action. The callflow data object would look like:

{
  "flow": {
    "data": {
      "to_did": "{MOBILE_NUMBER}"
    },
    "module": "resources"
  },
  "name": "forward business to mobile",
  "numbers": [
    "{BUSINESS_NUMBER}"
  ]
}

Simply stated, the resource action's to_did will override the normal action to call the to number with to_did instead. The power here is that the same callflow can be used for many numbers (say multiple businesses you might accept calls for).

The basic API call then becomes:

curl -H "X-Auth-Token: {API_AUTH_TOKEN}" \
     -X PUT \
     -d '{"data":{"name":"forward business to mobile","numbers":["{BUSINESS_NUMBER}"],"flow":{"module":"resources","data":{"to_did":"{MOBILE_NUMBER}"}}}}'
     https://api.kazoo.domain/v2/accounts/{ACCOUNT_ID}/callflows

Voicemail considerations

With calls forwarded to the carriers in the manner above, your personal voicemail will answer the call if you are unable to at the time. If this is not desirable, you will need to slightly modify how you make this happen.

What you need is to require the callee (you) to press 1 to accept the call before KAZOO will let connect the caller to your mobile phone. If your personal voicemail tries to pick up the call, KAZOO will not continue and will return to the callflow and try the child of the resources action. Since there is no child, the call will be hung up - not ideal!

To setup the required keypress, you'll need to create a call-forwarded device.

Call-Forwarded Device

KAZOO devices can be configured to represent anything from SIP devices to call-forwarded devices, WebRTC, and other types. The other nice benefit is that you can assign the device, via the owner_id property, to your KAZOO user and get calls to ring any of your devices!

To create the call-forwarded device, you only need to setup the call_forward object:

{
  "call_forward": {
    "enabled": true,
    "number": "{MOBILE_NUMBER}",
    "require_keypress": true
  },
  "name": "WFH device",
  "owner_id": "{USER_ID}"
}

Not strictly required to include owner_id (especially if this is a temporary setup until the office re-opens).

The API command then becomes:

curl -H "X-Auth-Token: {API_AUTH_TOKEN}" \
     -X PUT \
     -d '{"data":{"name":"WFH device","call_forward":{"enabled":true,"number":"{MOBILE_NUMBER}","require_keypress":true},"owner_id":"{USER_ID}"}}'
     https://api.kazoo.domain/v2/accounts/{ACCOUNT_ID}/devices

The callflow action is then changed to:

"flow":{
  "module":"device"
  ,"data":{"id":"{WFH_DEVICE_ID}"}
}

Now when your personal voicemail picks up, KAZOO will not connect the caller and will instead go to the child (which currently is missing!). Let's add your business voicemail box.

Call-forwarding plus Voicemail

If you haven't already created a KAZOO voicemail box its a straight-forward process similar to device and callflow creation via API.

Once you have the voicemail box ID you can modify the callflow's flow to look like:

{
  "flow": {
    "children": {
      "_": {
	"data": {
	  "id": "{VOICEMAIL_BOX_ID}"
	},
	"module": "voicemail"
      }
    },
    "data": {
      "id": "{WFH_DEVICE_ID}"
    },
    "module": "device"
  }
}

Of course now that you have KAZOO voicemail, you can enable voicemail-to-email, transcription (if your cluster supports it), auto-delete from the voicemail box after successfully sending the email, and more.

Configure using the UI

You can also use two of 2600Hz's UI apps, SmartPBX or Advanced Callflows, to achieve the same configurations as the direct API examples above.

Take a walk-through of SmartPBX to see more or jump to the call-forwarding setup.

Customize routing decisions

Sometimes KAZOO callflow actions can't quite encode the flow you would like to achieve, or KAZOO doesn't have access to data sources needed to make routing decisions. Fortunately KAZOO has Pivot to help you take control of call routing when you need more dynamic handling.

The callflow is simple:

{
  "flow": {
    "children": {
      "_": {
	"data": {
	  "id": "{WFH_CALLFLOW_ID}"
	},
	"module": "callflow"
      }
    },
    "data": {
      "method": "POST",
      "req_format": "kazoo",
      "voice_url": "https://your.http.server/pivot/whatever/language/you/like.ext"
    },
    "module": "pivot"
  },
  "name": "dynamic call control",
  "numbers": [
    "{BUSINESS_NUMBER}"
  ]
}

Now any call to {BUSINESS_NUMBER} will issue an HTTP request to your.http.server. If your server fails to respond, the callflow will continue and run the callflow from above (you would need to remove the {BUSINESS_NUMBER} from the numbers array on that callflow so they don't conflict with the Pivot callflow here).

Your server, in your language of choice, will process the request data, consult any data sources, make any business logic decisions, then send a response with the appropriate callflow 'flow' object. For instance, to have callflow mirror the routing to the call-forwarded device, your PHP script might look like:

<?php
header('content-type: application/json');

/* Business logic
 * Database lookups
 * Whatever shenanigans
 */
?>
{
  "module":"device"
  ,"data":{"id":"{WFH_DEVICE_ID}"}
}

Wrap-up

In this post we've walked through what API calls and JSON objects would be needed to setup call-forwarding of a phone number (like the business' phone number) to another phone number (like the owner's personal mobile number). Depending on what voicemail box you'd like to answer if the callee is unavailable will determine which path, device or resource, you use to route the caller.

We also briefly introduced the idea of using Pivot to encode custom logic when routing callers to the call-forwarded device (and provide a child action if the Pivot request fails for any reason).

The building blocks exposed in KAZOO's callflow actions are many (~75 at last count) and run the gamut from low-level - collecting touch tones (DTMF) or playing text (TTS) to the caller, or time of day routing - up to more conceptual actions like leaving and checking voicemails, ringing a user's devices, user directories, and so much more.

Have questions? Join our forum, hop on IRC (Freenode #2600hz) to chat, and start an all-in-one install to test things out.

If you have a business and want to engage on using our hosted platform or other offerings, we at 2600Hz are ready to chat (sales@2600hz.com) and help you build it!

Chewing the Cud (Posts about kazoo work 2600Hz wfh)