Flows

Flows define what happens during a call. They're the brains of your campaigns—controlling everything from the initial dial to the final hangup.

How flows work

A flow is a directed graph of nodes. Each node performs an action and then routes to the next node based on what happened. Execution starts at a designated start node and continues until it reaches a terminal node (usually a hangup).

┌─────────┐     ┌─────────┐     ┌─────────┐     ┌─────────┐
│  Dial   │────▶│  Play   │────▶│  DTMF   │────▶│ Hangup  │
└─────────┘     └─────────┘     └─────────┘     └─────────┘
     │                              │
     │ onBusy                       │ onTimeout
     ▼                              ▼
┌─────────┐                    ┌─────────┐
│ Hangup  │                    │ Hangup  │
└─────────┘                    └─────────┘

Node types

Gomobile supports these node types:

Node	Purpose	Outputs
Dial	Places the outbound call	onAnswer, onVoicemail, onNoAnswer, onBusy, onRejected, onError, default
Answer	Answers an inbound call	onSuccess, onError, default
Play	Plays audio to the recipient	onComplete, onError, default
DTMF	Collects keypad input	branches (by digit), onSuccess, onTimeout, onInvalid, onMaxRetries, onError, default
Record	Records the recipient's voice	onComplete, onTimeout, onError, default
Condition	Branches based on variables	onTrue, onFalse, onError
Set Variable	Stores a value for later use	onSuccess, onError, default
Hangup	Ends the call	None (terminal node)

Creating a flow

Here's a complete flow that plays a message and collects a response:

curl -X POST https://api.gomobile.io/flows \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payment Reminder",
    "description": "Reminds customers about pending payments",
    "graph": {
      "startNodeId": "dial-1",
      "nodes": [
        {
          "id": "dial-1",
          "type": "dial",
          "label": "Call Customer",
          "config": {
            "timeout": 30000,
            "enableAMD": true
          },
          "outputs": {
            "onAnswer": "play-greeting",
            "onVoicemail": "hangup-vm",
            "onNoAnswer": "hangup-na",
            "onBusy": "hangup-busy"
          }
        },
        {
          "id": "play-greeting",
          "type": "play",
          "label": "Play Reminder",
          "config": {
            "audioItems": [
              { "type": "audioFile", "audioId": "greeting-audio-id" }
            ]
          },
          "outputs": {
            "onComplete": "collect-response"
          }
        },
        {
          "id": "collect-response",
          "type": "dtmf",
          "label": "Get Response",
          "config": {
            "mode": "single_digit",
            "variable": "customerResponse",
            "timeout": 10000,
            "singleDigitConfig": {
              "allowedDigits": ["1", "2"]
            }
          },
          "outputs": {
            "branches": {
              "1": "play-confirmed",
              "2": "play-callback"
            },
            "onTimeout": "hangup-timeout"
          }
        },
        {
          "id": "play-confirmed",
          "type": "play",
          "label": "Confirm Payment",
          "config": {
            "audioItems": [
              { "type": "audioFile", "audioId": "confirmed-audio-id" }
            ]
          },
          "outputs": {
            "onComplete": "hangup-success"
          }
        },
        {
          "id": "play-callback",
          "type": "play",
          "label": "Schedule Callback",
          "config": {
            "audioItems": [
              { "type": "audioFile", "audioId": "callback-audio-id" }
            ]
          },
          "outputs": {
            "onComplete": "hangup-success"
          }
        },
        {
          "id": "hangup-success",
          "type": "hangup",
          "label": "End Call - Success",
          "config": { "reason": "completed", "hangupType": "normal" }
        },
        {
          "id": "hangup-vm",
          "type": "hangup",
          "label": "End Call - Voicemail",
          "config": { "reason": "voicemail", "hangupType": "voicemail" }
        },
        {
          "id": "hangup-na",
          "type": "hangup",
          "label": "End Call - No Answer",
          "config": { "reason": "no_answer", "hangupType": "no_answer" }
        },
        {
          "id": "hangup-busy",
          "type": "hangup",
          "label": "End Call - Busy",
          "config": { "reason": "busy", "hangupType": "busy" }
        },
        {
          "id": "hangup-timeout",
          "type": "hangup",
          "label": "End Call - Timeout",
          "config": { "reason": "dtmf_timeout", "hangupType": "timeout" }
        }
      ]
    }
  }'

Variables in flows

Flows can read and write variables during execution. Variables come from several sources:

Source	Example	Description
System	sys.callId, sys.contactPhone	Automatically available
Contact	contact.firstName, contact.city	From the contact being called
Custom Attribute	contact.customAttributes.balance	Custom fields on contacts
Flow Variable	customerResponse	Set during execution

Use variables in conditions or to personalize audio playback.

Answering Machine Detection (AMD)

When enableAMD is true on a dial node, Gomobile attempts to detect if a human or machine answered:

• Human detected → Routes to onAnswer

• Machine detected → Routes to onVoicemail

This helps you leave voicemail messages instead of playing interactive prompts to answering machines.

Audio playback options

The Play node supports several audio types:

{
  "audioItems": [
    { "type": "audioFile", "audioId": "welcome-message" },
    { 
      "type": "number", 
      "value": {
        "source": "customAttribute",
        "attributeName": "accountBalance"
      },
      "mode": "full",
      "language": "ar"
    },
    { "type": "audioFile", "audioId": "currency-mad" }
  ]
}

Types include:

• audioFile - Pre-recorded audio

• number - Dynamic number playback

• date - Dynamic date playback

• word - Dictionary-based word playback

Flow validation

Before saving, Gomobile validates your flow:

• Every node must be reachable from the start node

• All output references must point to existing nodes

• Terminal nodes (hangup) shouldn't have outputs

• Required configuration must be present

You can validate without saving:

curl -X POST https://api.gomobile.io/flows/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "graph": { ... } }'

Best practices

• Start simple - Get a basic flow working before adding complexity

• Handle all outcomes - Every dial result should route somewhere

• Use descriptive labels - Makes debugging much easier

• Test thoroughly - Use ad-hoc calls to test before launching campaigns

• Version carefully - Changing a flow affects all programs using it

Related concepts

• Call Flows Guide - Detailed node configuration

• Audio Management - Managing audio files

• Dictionaries - Dynamic audio for numbers and words

• Programs - Using flows in campaigns