Designing Call Flows

Effective call flows balance simplicity with functionality. This guide covers patterns, best practices, and common scenarios to help you design flows that work.

Flow design principles

Keep it short

Phone calls should be brief and focused:

• Get to the point quickly

• Limit menu options (3-4 max)

• Provide an easy exit

• Total call time: 30-60 seconds for simple messages

Handle every outcome

Every node should have paths for all possible results:

Dial
├── onAnswer → Continue flow
├── onVoicemail → Leave message or hangup
├── onNoAnswer → Hangup (retry later)
├── onBusy → Hangup (retry later)
├── onRejected → Hangup
└── onError → Hangup

Fail gracefully

When things go wrong, don't leave the caller confused:

• Always have error paths

• End with a polite hangup message

• Log errors for debugging

Common patterns

Simple notification

Just deliver a message, no interaction needed:

Dial → Play Message → Hangup

{
  "startNodeId": "dial",
  "nodes": [
    {
      "id": "dial",
      "type": "dial",
      "config": { "timeout": 30000, "enableAMD": false },
      "outputs": { "onAnswer": "play", "default": "hangup" }
    },
    {
      "id": "play",
      "type": "play",
      "config": { "audioItems": [{ "type": "audioFile", "audioId": "message" }] },
      "outputs": { "onComplete": "hangup" }
    },
    {
      "id": "hangup",
      "type": "hangup",
      "config": { "reason": "completed", "hangupType": "normal" }
    }
  ]
}

Menu with options

Collect a response and branch:

Dial → Play Menu → Collect DTMF → Branch by digit → Hangup

Key considerations:

• Repeat the menu if no input received

• Handle invalid inputs gracefully

• Provide a "repeat" option if menu is complex

Confirmation flow

Get explicit confirmation before proceeding:

Dial → Play Question → Collect DTMF
         ↓ "1" = Yes          ↓ "2" = No
    Confirm action        Cancel action
         ↓                     ↓
      Hangup               Hangup

Information collection

Gather multi-digit input:

Dial → Play Prompt → Collect Digits → Validate → Confirm → Hangup
                                          ↓ Invalid
                                    Retry prompt

Use multi_digit mode for account numbers, PINs, etc.

Conditional messaging

Different messages based on contact data:

Dial → Check Condition → Branch
           ↓ True              ↓ False
    Play Message A      Play Message B
           ↓                   ↓
        Hangup              Hangup

{
  "id": "check-tier",
  "type": "condition",
  "config": {
    "expression": {
      "type": "simple",
      "variable": { "type": "custom_attribute", "name": "is_premium" },
      "operator": "eq",
      "value": true
    }
  },
  "outputs": {
    "onTrue": "play-premium-message",
    "onFalse": "play-standard-message"
  }
}

Working with audio

Sequencing audio items

Audio items play in order:

{
  "audioItems": [
    { "type": "audioFile", "audioId": "greeting" },
    { "type": "audioFile", "audioId": "your-balance-is" },
    { "type": "number", "value": {...}, "mode": "full", "language": "ar" },
    { "type": "audioFile", "audioId": "dirhams" }
  ]
}

Result: "Hello! Your balance is one thousand five hundred dirhams."

Dynamic content

Reference contact data for personalization:

{
  "type": "number",
  "value": { "source": "customAttribute", "attributeName": "account_balance" },
  "mode": "full",
  "language": "ar"
}

Barge-in

Let users skip ahead by pressing a key:

{
  "type": "play",
  "config": {
    "audioItems": [...],
    "allowBargeIn": true,
    "bargeInDtmfNodeId": "collect-input"
  }
}

Use barge-in for:

• Long messages users might have heard before

• Menu prompts where users know their choice

• Time-sensitive situations

DTMF collection tips

Single digit menus

Keep it simple:

{
  "mode": "single_digit",
  "singleDigitConfig": {
    "allowedDigits": ["1", "2", "3"]
  }
}

Best practices:

• Use "1" for the most common action

• Use "0" for operator/help

• Use "*" for repeat

• Use "#" for main menu

Multi-digit input

For account numbers, PINs, etc.:

{
  "mode": "multi_digit",
  "multiDigitConfig": {
    "minDigits": 4,
    "maxDigits": 16,
    "terminators": ["#"],
    "interDigitTimeout": 3000
  }
}

Always tell users:

• How many digits to enter

• What key ends input (usually #)

• What happens if they make a mistake

Retries

Give users multiple chances:

{
  "retry": {
    "maxRetries": 2,
    "invalidAudioId": "invalid-input-audio",
    "timeoutAudioId": "no-input-audio"
  }
}

After max retries, route to a helpful ending—not a dead drop.

Answering machine detection

AMD helps you handle voicemails appropriately:

{
  "type": "dial",
  "config": {
    "enableAMD": true
  },
  "outputs": {
    "onAnswer": "human-flow",
    "onVoicemail": "voicemail-flow"
  }
}

Voicemail options:

• Leave a brief message

• Hang up and retry later

• Hang up with no message

Recording responses

Capture voice input when DTMF isn't enough:

{
  "id": "record-feedback",
  "type": "record",
  "config": {
    "variable": "recordingId",
    "maxDurationMs": 30000,
    "silenceThresholdMs": 3000,
    "beep": true
  }
}

Tips:

• Keep max duration reasonable (30-60 seconds)

• Play a beep before recording

• Confirm recording was received

Testing your flows

Ad-hoc calls

Test with a single call before launching campaigns:

curl -X POST https://api.gomobile.io/call-requests \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "fromNumber": "[phone]",
    "contactId": "test-contact-id",
    "flowId": "your-flow-id",
    "retry": { "type": "none" }
  }'

Test each path

Make sure you test:

• Answering and completing the flow

• Letting it ring (no answer)

• Rejecting the call

• Invalid DTMF input

• Timeout scenarios

Check reports

Review the call report for details:

curl -X GET https://api.gomobile.io/call-report/JOB_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Look at the execution path to verify the flow behaved as expected.

Debugging common issues

Flow stops unexpectedly

• Check that all nodes have outputs defined

• Verify output node IDs exist

• Look for typos in node references

Wrong audio plays

• Confirm audio IDs are correct

• Check audio was successfully uploaded

• Verify variable references resolve correctly

DTMF not collecting

• Increase timeout value

• Check allowed digits match what users press

• Verify barge-in isn't consuming the input

Condition always takes one path

• Test with known data values

• Check operator is correct

• Verify variable reference syntax

Best practices summary

1. Plan before building - Sketch the flow on paper first

2. Start simple - Get basic flow working before adding complexity

3. Handle all outcomes - Every node needs proper outputs

4. Test thoroughly - Try every path before production

5. Keep messages short - Respect your recipients' time

6. Use descriptive labels - Future you will appreciate it

7. Document complex logic - Use node descriptions

Next steps

• Audio Management - Prepare your audio files

• Call Flows Reference - Complete node documentation

• Building Your First Campaign - End-to-end example