Call Flow Object

The Call Flow Object describes what happens to an incoming phone call to a tracking number. This can involve multiple steps before ultimately routing a call to the destination number or voicemail.

API Representation

A distinction is made between a “basic” call flow and an “advanced” call flow. A basic call flow may play either a text or recorded greeting before routing the call to the destination number. An advanced call flow may have multiple steps including menus, time of day based routing, voicemail, or more.

At this time, only Basic Call Flow Objects are supported when creating a new Source Tracker or Session Tracker. Advanced Call Flow Objects can only be configured through the CallRail application interface. However, when retrieving Trackers with Advanced Call Flows the format described below will be used.

Basic Call Flow Object Fields

  • type: Always the word “basic”.
  • recording_enabled: Whether or not this Call Flow records calls. Note that in some jurisdictions you may be obligated to inform the caller that the call is being recorded. If this applies to you, use the greeting options below when creating a Call Flow in order to play a greeting message that informs the caller about call recording.
  • destination_number: where incoming calls should ring.
  • greeting_text: Text, if any, that should be read to the caller prior to connecting to the destination number.
  • greeting_recording_url: The web address of a recording to be played to the caller prior to connecting to the destination number. This can be either a .wav or .mp3 file.

Examples:

/* text greeting */
{
  "type": "basic",
  "recording_enabled": true,
  "destination_number": "+15558675309",
  "greeting_text": "This call will be recorded for quality assurance",
  "greeting_recording_url": null
}

/* no greeting */
{
  "type": "basic",
  "recording_enabled": false,
  "destination_number": "+15558675309",
  "greeting_text": null,
  "greeting_recording_url": null
}

/* recorded greeting */
{
  "type": "basic",
  "recording_enabled": true,
  "destination_number": "+15558675309",
  "greeting_text": null,
  "greeting_recording_url": "https://s3.aws.com/.../recording.mp3"
}

Note that when specifying a greeting_recording_url during creation, CallRail will retrieve the specified file once and store it within the application. (This is necessary to ensure availability and playback compatibility.) The URL returned in the response will be the location of the copy stored by CallRail, and any future changes the the original recording will not be reflected within CallRail.

Advanced Call Flow Objects

The format for more advanced call flows is necessarily more complex:

  • type: Always the word “advanced”
  • recording_enabled: Whether or not this Call Flow records calls.
  • initial_step_id: The numerical id of the first step in the call flow.
  • steps: An array of step objects. Each step object will contain one or more next_step_id entries indicating which step follows it. Terminal steps (e.g. “Ring a phone”, “Send to Voicemail”) will not have a next_step_id. Each step has its own distinct format.

Example:

/* route to voicemail or dial a number based on a menu */

{
  "type": "advanced",
  "recording_enabled": false,
  "initial_step_id": 210884509,
  "steps": [
    {
      "destination_number": "+15551234567",
      "timeout": 60,
      "timeout_step_id": null,
      "id": 344126405,
      "type": "dial"
    },
    {
      "prompt_type": "text",
      "prompt_recording_id": null,
      "prompt_text": "Thank you for your support call. Please leave a message.",
      "transcribe": false,
      "id": 250778404,
      "type": "voicemail"
    },
    {
      "prompt_type": "text",
      "prompt_recording_id": null,
      "prompt_text": "Press 1 for Sales, press 2 for Support.",
      "menu_options": [
        {
          "key": "1",
          "description": "Forward to Sales",
          "next_step_id": 344126405
        },
        {
          "key": "2",
          "description": "Forward to Support",
          "next_step_id": 250778404
        }
      ],
      "id": 210884509,
      "type": "menu"
    }
  ]
}