Callflows

A call flow is a set of steps to take in order to process dialled digits. Each step such as "answer, play file, record file" is logically grouped together and ordered.

 

 

v1/accounts/{account_id}/callflows

 

Base Parameters

Property
Description
Validation
Modifiable
numbers A list of numbers that belong to this callflow array yes
patterns A list of regular expressions that belong to this callflow array yes
flow The callflow tree (actions to execute) object yes


  The "numbers" parameter accepts a special string constant, "no_match", that can occur once per call flow realm. This will cause the call flow to execute if no other call flow matches.

 

Flow Parameters

Property
Description
Validation
Modifiable
module The module, or action, to preform   yes
data Arbitrary data passed to the module object yes
children Additional flow parameters, encapsulated in an object with properties representing the branch names object yes


  The children parameter encapsulation properties accepts one special string constant, "_", which is a wild card. This branch will be executed if no other child branch matches.

 

Operations

Verb
Accepted
Returned
Description
GET   id and name Fetches a summary of callflows
PUT ANY ALL Create a new callflow

 

Response Codes

Normal Response Code(s): 200

Error Response Code(s): 400, 401, 415, 500, 503, 504

Patterns

The callflow patterns parameter is an array of regular expressions that are used to identify a callflow when there are exact matches. The search order is therefore:

  1. Comparison of the dialed number for an exact match to an element in the numbers array (using the first match by couchdb sort order).
  2. The largest match (most characters) of any capture group or regular expression, if no capture group present.
  3. A callflow with the literal word 'no_match' in the numbers array.

When a callflow is located via a regular expression the largest capture group (if any) is provided to the children nodes. At this time the use of patterns is far less efficient then exact matches on the numbers array, and should only be used for dynamic numbers.

This allows, for example, feature codes such as *724158867900 to denote activating call forwarding with *72 and capture the number 4158867900 as the number to forward to.

 

{
   "data":{
      "patterns":[
         "^\\*72([0-9]*)$"
      ],
      "flow":{
         "module":"call_forward",
         "data":{
            "action":"1step_toggle"
         },
         "children":{
         }
      }
   }
}


  You need to escape backslashes in literal strings with an additional backslash in the regular expressions.

 

 

 

URI

 

v1/accounts/{account_id}/callflows/{callflow_id}

 

Base Parameters

Property
Description
Validation
Modifiable
numbers A list of numbers that belong to this callflow array yes
patterns A list of regular expressions that belong to this callflow array yes
flow The callflow tree (actions to execute) object yes

 

Operations

Verb
Accepted
Returned
Description
GET   ALL Fetch the details of a callflow
POST ANY ALL Update the parameters of a callflow
DELETE     Delete a callflow

 

Response Codes

Normal Response Code(s): 200, 201

Error Response Code(s): 400, 401, 404, 415, 500, 503, 504

 

METHOD

Request URI

Request Headers

Request Body

Response Body

Response Headers

GET v1/accounts/{account_id}/callflows X-Auth-Token: abc123

Accept: application/json
 
{
   "auth_token":"abc123",
   "status":"success",
   "data":[
      {
         "id":"xyz987"
      }
   ]
}
200 OK

Content-Type: application/json
PUT v1/accounts/{account_id}/callflows X-Auth-Token: abc123

Accept: application/json

Content-Type: application/json
{
   "data":{
      "numbers":[
         "*97"
      ],
      "flow":{
         "module":"voicemail",
         "data":{
            "action":"check"
         },
         "children":{
         }
      }
   }
}
  201 OK

Location: v1/accounts/{account_id}/callflows/{callflow_id}
GET v1/accounts/{account_id}/callflows/{callflow_id} X-Auth-Token: abc123

Accept: application/json
 
{
   "auth_token":"abc123",
   "status":"success",
   "data":{
      "numbers":[
         "*97"
      ],
      "flow":{
         "module":"voicemail",
         "data":{
            "action":"check"
         },
         "children":{
         }
      }
   }
}
200 OK
POST v1/accounts/{account_id}/callflows/{callflow_id} X-Auth-Token: abc123

Accept: application/json

Content-Type: application/json
{
   "data":{
      "numbers":[
         "*97"
      ],
      "flow":{
         "module":"voicemail",
         "data":{
            "action":"check"
         },
         "children":{
         }
      }
   }
}
{
   "auth_token":"abc123",
   "status":"success",
   "data":{
      "numbers":[
         "*97"
      ],
      "flow":{
         "module":"voicemail",
         "data":{
            "action":"check"
         },
         "children":{
         }
      }
   }
}
200 OK
DELETE v1/accounts/{account_id}/callflows/{callflow_id} X-Auth-Token: abc123

Accept: application/json
 
{
   "auth_token":"abc123",
   "status":"success",
   "data":[]
}
200 OK

 

Response Body

Response Headers

{

   "auth_token":"abc123",

   "status":"success",

   "data":[

      {

         "id":"xyz987"

      }

   ]

}

 

200 OK

Content-Type: application/json

 

201 OK

Location: v1/accounts/{account_id}/callflows/{callflow_id}

{

   "auth_token":"abc123",

   "status":"success",

   "data":{

      "numbers":[

         "*97"

      ],

      "flow":{

         "module":"voicemail",

         "data":{

            "action":"check"

         },

         "children":{

         }

      }

   }

}

 

200 OK

 

{
   "numbers":[
      "1000"
   ],
   "flow":{
      "module":"device",
      "data":{
         "id":"... DEVICE ID ..."
      },
      "children":{
         "_":{
            "module":"voicemail",
            "data":{
               "id":"... VOICEMAIL ID ...",
               "action":"compose"
            },
            "children":{
            }
         }
      }
   }
}

 

{
   "numbers":[
      "51"
   ],
   "flow":{
      "module":"conference",
      "data":{
         "id":"... CONFERENCE ID ..."
      },
      "children":{
      }
   }
}

 

{
   "numbers":[
      "*97"
   ],
   "flow":{
      "module":"voicemail",
      "data":{
         "action":"check"
      },
      "children":{
      }
   }
}
{
   "numbers":[
      "*98"
   ],
   "flow":{
      "module":"voicemail",
      "data":{
         "action":"check",
         "id":"... VOICEMAIL ID ..."
      },
      "children":{
      }
   }
}
{
   "numbers":[
      "+14158867900",
      "9000"
   ],
   "flow":{
      "module":"menu",
      "data":{
         "id":"... MENU ID ..."
      },
      "children":{
         "1":{
            "module":"device",
            "data":{
               "id":"... DEVICE ID ...",
               "timeout":15
            },
            "children":{
               "_":{
                  "module":"voicemail",
                  "data":{
                     "id":"... VOICEMAIL ID ...",
                     "action":"compose"
                  },
                  "children":{
                  }
               }
            }
         },
         "_":{
            "module":"voicemail",
            "data":{
               "id":"... VOICEMAIL ID ...",
               "action":"compose"
            },
            "children":{
            }
         }
      }
   }
}
{
   "numbers":[
      "2000"
   ],
   "flow":{
      "module":"ring_group",
      "data":{
         "endpoints":[
            {
               "id":"... DEVICE ID ..."
            },
            {
               "id":"... DEVICE ID ...",
               "delay": 6
            }
         ],
         "timeout": 15
      },
      "children":{
         "_":{
            "module":"voicemail",
            "data":{
               "id":"... VOICEMAIL ID ...",
               "action":"compose"
            },
            "children":{
            }
         }
      }
   }
}
{
   "numbers":[
      "no_match"
   ],
   "flow":{
      "module":"resources",
      "data":{
      },
      "children":{
      }
   }
}

Hotdesk requires 3 callflows : login, logout and bridge. In this example, call *92 to login in a device, *93 to logout, and 3000 to ring the hotdesk owner's devices.

 

{
   "numbers": [
       "*92"
   ],
   "flow": {
       "module": "hotdesk",
       "data": {
           "action": "login"
           "id": "___USER_ID___"
       },
       "children": {
       }
   },
}

 

 

{
   "numbers": [
       "*93"
   ],
   "flow": {
       "module": "hotdesk",
       "data": {
           "action": "logout"
           "id": "___USER_ID___"
       },
       "children": {
       }
   },
}

 

 

{
   "numbers": [
       "3000"
   ],
   "flow": {
       "module": "hotdesk",
       "data": {
           "action": "bridge"
           "id": "___USER_ID___"
       },
       "children": {
       }
   },
}
  All IDs below are made up and not to be copy/pasted

 

The callflow document with id = 57285274986726:

{
  "numbers": ["411"]
  ,"flow": {
    "module":"directory"
    ,"data": {
      "id":"18941094957"
    }
  }
}

 

In the directory document with id = 18941094957:

{
  "name": "sales" % required, used in the user's doc to link them to the directory
  ,"min_dtmf":3 % options, defaults to 3
  ,"max_dtmf":8 % optional, or set to 0 for no limit
  ,"sort_by":"last_name" % "last_name" or "first_name", defaults to "last_name"
  ,"confirm_match": false % if only one match, must caller confirm the selection before connection
}

 

In the user's document, add:

{
  "directories": [
    {"directory_id":"18941094957", "callflow_id":"57285274986726"} % what callflow to route to (usually a device's callflow, but can be any callflow)
  ] % may be part of more than one directory
  ,"first_name": "Guy"
  ,"last_name": "Sname"
  ...
}