#+BEGIN_COMMENT
.. title: Setting up call forwarding in KAZOO
.. slug: setting-up-call-forwarding-in-kazoo
.. date: 2020-04-06 21:59:59 UTC
.. tags: kazoo work 2600Hz wfh
.. category: work
.. link:
.. description: Building work-from-home callflows to continue receiving business calls
.. type: text
#+END_COMMENT
With the transition to working from home in full swing, let's look at the ways [[https://docs.2600hz.com/dev/][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 [[https://docs.2600hz.com/dev/applications/crossbar/doc/callflows/][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 [[https://docs.2600hz.com/dev/applications/callflow/doc/resources/][resources]] action. The callflow data object would look like:

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

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:

#+begin_src bash
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
#+end_src

**** 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

[[https://docs.2600hz.com/dev/applications/crossbar/doc/devices/][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:

#+begin_src json
{
  "call_forward": {
    "enabled": true,
    "number": "{MOBILE_NUMBER}",
    "require_keypress": true
  },
  "name": "WFH device",
  "owner_id": "{USER_ID}"
}
#+end_src

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

The API command then becomes:

#+begin_src bash
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
#+end_src

The callflow action is then changed to:

#+begin_src json
"flow":{
  "module":"device"
  ,"data":{"id":"{WFH_DEVICE_ID}"}
}
#+end_src

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 [[https://docs.2600hz.com/dev/applications/crossbar/doc/voicemail/][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:

#+begin_src json
{
  "flow": {
    "children": {
      "_": {
        "data": {
          "id": "{VOICEMAIL_BOX_ID}"
        },
        "module": "voicemail"
      }
    },
    "data": {
      "id": "{WFH_DEVICE_ID}"
    },
    "module": "device"
  }
}
#+end_src

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 [[https://www.youtube.com/watch?v=ERSq0GNUfvQ&list=PLwhBNccjGCsZ6tS-3QBdLqSbb_5QpJZb5][walk-through of SmartPBX]] to see more or jump to the [[https://www.youtube.com/watch?v=_Wr-5H6q2sQ][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 [[https://docs.2600hz.com/dev/applications/pivot/doc/README/][Pivot]] to help you take control of call routing when you need more dynamic handling.

The callflow is simple:

#+begin_src json
{
  "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}"
  ]
}
#+end_src

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 [[https://docs.2600hz.com/dev/applications/pivot/doc/requests/][the request data]], consult any data sources, make any business logic decisions, then [[https://docs.2600hz.com/dev/applications/pivot/doc/kazoo/README/][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:

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

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

** 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 [[https://forums.2600hz.com/forums/][forum]], hop on IRC (Freenode #2600hz) to chat, and start an [[https://docs.2600hz.com/sysadmin/doc/install/install_via_centos7/][all-in-one install]] to test things out.

If you have a business and want to engage on using [[http://info.2600hz.com/small-business-reseller-success-suite][our hosted platform]] or [[http://info.2600hz.com/small-business-servers][other offerings]], we at [[https://2600hz.com/][2600Hz]] are ready to chat (sales@2600hz.com) and help you build it!