Building Your First Campaign

This guide walks you through creating a complete calling campaign from scratch. By the end, you'll have a working campaign that calls contacts and plays a message.

What you'll build

A payment reminder campaign that:

1. Calls customers with outstanding balances

2. Plays a personalized message with their balance

3. Collects a response (press 1 to confirm, press 2 for callback)

4. Retries failed calls once after 30 minutes

Prerequisites

• Gomobile account with API access

• Access token (see Authentication)

• At least one DID allocated to your account

• Audio files for your messages (or use text descriptions for now)

Step 1: Create your contacts

First, add the people you'll be calling:

curl -X POST https://api.gomobile.io/contact \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Ahmed",
    "lastName": "Tazi",
    "primaryPhone": "[phone]",
    "customAttributes": {
      "account_balance": 1500,
      "days_overdue": 15
    }
  }'

Save the contact ID from the response. Repeat for additional contacts.

For bulk import, use the upsert endpoint:

curl -X POST https://api.gomobile.io/contact/upsert \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {
        "firstName": "Ahmed",
        "lastName": "Tazi",
        "primaryPhone": "[phone]",
        "customAttributes": { "account_balance": 1500 }
      },
      {
        "firstName": "Fatima",
        "lastName": "Benali",
        "primaryPhone": "[phone]",
        "customAttributes": { "account_balance": 2300 }
      },
      {
        "firstName": "Omar",
        "lastName": "Alami",
        "primaryPhone": "[phone]",
        "customAttributes": { "account_balance": 850 }
      }
    ]
  }'

Step 2: Create an audience

Group your contacts into a targetable audience:

curl -X POST https://api.gomobile.io/audience \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "January Payment Reminders",
    "description": "Customers with outstanding balances for January campaign"
  }'

Save the audience ID.

Step 3: Add contacts to the audience

Link your contacts to the audience:

curl -X POST https://api.gomobile.io/audience/AUDIENCE_ID/add-contacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      "CONTACT_ID_1",
      "CONTACT_ID_2",
      "CONTACT_ID_3"
    ]
  }'

Step 4: Upload audio files

Upload the audio files you'll use in the flow:

# Welcome message
curl -X POST https://api.gomobile.io/audio-management/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "title=Payment Reminder Welcome" \
  -F "usageType=welcome"

# Your balance is... (before the number)
curl -X POST https://api.gomobile.io/audio-management/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "title=Your Balance Is" \
  -F "usageType=prompt"

# Dirhams (currency)
curl -X POST https://api.gomobile.io/audio-management/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "title=Dirhams" \
  -F "usageType=prompt"

# Menu prompt
curl -X POST https://api.gomobile.io/audio-management/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "title=Menu Prompt" \
  -F "usageType=prompt"

# Confirmation message
curl -X POST https://api.gomobile.io/audio-management/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "title=Confirmation" \
  -F "usageType=notification"

# Callback message
curl -X POST https://api.gomobile.io/audio-management/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "title=Callback Scheduled" \
  -F "usageType=notification"

Save all the audio IDs.

Step 5: Create the call flow

Now build the flow that defines what happens during each call:

curl -X POST https://api.gomobile.io/flows \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payment Reminder Flow",
    "description": "Reminds customers of balance and collects response",
    "graph": {
      "startNodeId": "dial-1",
      "nodes": [
        {
          "id": "dial-1",
          "type": "dial",
          "label": "Call Customer",
          "config": {
            "timeout": 30000,
            "enableAMD": true
          },
          "outputs": {
            "onAnswer": "play-welcome",
            "onVoicemail": "hangup-vm",
            "onNoAnswer": "hangup-na",
            "onBusy": "hangup-busy"
          }
        },
        {
          "id": "play-welcome",
          "type": "play",
          "label": "Play Balance Message",
          "config": {
            "audioItems": [
              { "type": "audioFile", "audioId": "WELCOME_AUDIO_ID" },
              { "type": "audioFile", "audioId": "YOUR_BALANCE_IS_AUDIO_ID" },
              {
                "type": "number",
                "value": { "source": "customAttribute", "attributeName": "account_balance" },
                "mode": "full",
                "language": "ar",
                "dictionaryId": null
              },
              { "type": "audioFile", "audioId": "DIRHAMS_AUDIO_ID" },
              { "type": "audioFile", "audioId": "MENU_PROMPT_AUDIO_ID" }
            ]
          },
          "outputs": {
            "onComplete": "collect-response"
          }
        },
        {
          "id": "collect-response",
          "type": "dtmf",
          "label": "Get Customer Response",
          "config": {
            "mode": "single_digit",
            "variable": "customerResponse",
            "timeout": 10000,
            "singleDigitConfig": {
              "allowedDigits": ["1", "2"]
            },
            "retry": {
              "maxRetries": 2
            }
          },
          "outputs": {
            "branches": {
              "1": "play-confirmation",
              "2": "play-callback"
            },
            "onTimeout": "hangup-timeout",
            "onMaxRetries": "hangup-max-retries"
          }
        },
        {
          "id": "play-confirmation",
          "type": "play",
          "label": "Confirm Payment",
          "config": {
            "audioItems": [
              { "type": "audioFile", "audioId": "CONFIRMATION_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 - Success",
          "config": { "reason": "completed", "hangupType": "normal" }
        },
        {
          "id": "hangup-vm",
          "type": "hangup",
          "label": "End - Voicemail",
          "config": { "reason": "voicemail", "hangupType": "voicemail" }
        },
        {
          "id": "hangup-na",
          "type": "hangup",
          "label": "End - No Answer",
          "config": { "reason": "no_answer", "hangupType": "no_answer" }
        },
        {
          "id": "hangup-busy",
          "type": "hangup",
          "label": "End - Busy",
          "config": { "reason": "busy", "hangupType": "busy" }
        },
        {
          "id": "hangup-timeout",
          "type": "hangup",
          "label": "End - Timeout",
          "config": { "reason": "dtmf_timeout", "hangupType": "timeout" }
        },
        {
          "id": "hangup-max-retries",
          "type": "hangup",
          "label": "End - Max Retries",
          "config": { "reason": "max_retries", "hangupType": "timeout" }
        }
      ]
    }
  }'

Save the flow ID.

Step 6: Create the program

Configure the campaign with all the pieces:

curl -X POST https://api.gomobile.io/programs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "January Payment Reminders",
    "audienceId": "AUDIENCE_ID",
    "flowId": "FLOW_ID",
    "startAt": "2025-01-20T09:00:00Z",
    "stopAt": "2025-01-20T18:00:00Z",
    "didPool": ["[phone]"],
    "retryStrategy": {
      "type": "fixed_delay",
      "delayMinutes": 30,
      "maxRetries": 1
    },
    "pauseWindows": {
      "monday": [
        { "startAt": { "hour": 12, "minute": 0 }, "endAt": { "hour": 14, "minute": 0 } }
      ]
    }
  }'

Save the program ID.

Step 7: Launch the campaign

Start the execution:

curl -X POST https://api.gomobile.io/programs/PROGRAM_ID/launch \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "executionId": "execution-uuid"
}

Step 8: Monitor progress

Check how the campaign is doing:

curl -X GET https://api.gomobile.io/program-executions/EXECUTION_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Watch the counters:

{
  "status": "running",
  "totalContacts": 3,
  "contactsCompleted": 1,
  "contactsFailed": 0,
  "contactsPending": 1,
  "contactsInProgress": 1
}

Verification

Your campaign is working when:

• Status shows running or completed

• contactsCompleted increases over time

• You can answer a test call and hear your audio

Troubleshooting

No calls going out?

• Check that startAt is in the past or current

• Verify you're not in a pause window

• Confirm DIDs are valid

Calls fail immediately?

• Check phone number formats

• Verify DID is allocated to your account

Audio doesn't play?

• Confirm audio IDs are correct

• Check audio was processed successfully

What's next

• Designing Call Flows - Build more complex flows

• Retry Strategies - Optimize your retry configuration

• Call Flows - Complete node reference