Programs

Programs are campaign configurations. They combine an audience, a flow, a schedule, and retry rules into a launchable package. Think of programs as templates that you can execute multiple times.

What programs define

A program specifies:

Property	Purpose
name	Identifies the campaign
audienceId	Who to call
flowId	What to do during the call
startAt	When to begin
stopAt	When to stop (optional)
didPool	Which numbers to call from
retryStrategy	How to handle failed calls
pauseWindows	When NOT to make calls

Creating a program

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-uuid",
    "flowId": "flow-uuid",
    "startAt": "2025-01-20T09:00:00Z",
    "stopAt": "2025-01-20T18:00:00Z",
    "didPool": ["[phone]", "[phone]"],
    "retryStrategy": {
      "type": "fixed_delay",
      "delayMinutes": 60,
      "maxRetries": 2
    },
    "pauseWindows": {
      "monday": [
        { "startAt": { "hour": 12, "minute": 0 }, "endAt": { "hour": 14, "minute": 0 } }
      ],
      "tuesday": [
        { "startAt": { "hour": 12, "minute": 0 }, "endAt": { "hour": 14, "minute": 0 } }
      ]
    }
  }'

Response:

{
  "id": "program-uuid",
  "name": "January Payment Reminders",
  "status": "draft",
  "audienceId": "audience-uuid",
  "flowId": "flow-uuid",
  "startAt": "2025-01-20T09:00:00.000Z",
  "stopAt": "2025-01-20T18:00:00.000Z",
  "didPool": ["[phone]", "[phone]"],
  "retryStrategy": {
    "type": "fixed_delay",
    "delayMinutes": 60,
    "maxRetries": 2
  },
  "createdAt": "2025-01-15T10:30:00.000Z"
}

Program status

Programs have three statuses:

Status	Description
draft	Just created, not yet launched
active	Has been launched at least once
archived	No longer in use

DID pool

The didPool is a list of phone numbers that can be used as caller ID. Gomobile rotates through these numbers when placing calls.

Benefits of using multiple DIDs:

• Distribute call volume

• Reduce carrier flagging

• Improve answer rates

Make sure all numbers in your DID pool are allocated to your account.

Retry strategies

Three options for handling failed calls:

No retries

{ "type": "none" }

Each contact gets one call attempt. Failed calls are marked as failed.

Fixed delay

{
  "type": "fixed_delay",
  "delayMinutes": 30,
  "maxRetries": 3
}

Retry failed calls after a fixed delay. With maxRetries: 3, a contact gets up to 4 total attempts (1 initial + 3 retries).

Scheduled

{
  "type": "scheduled",
  "retryDates": ["2025-01-20T14:00:00Z", "2025-01-21T09:00:00Z"]
}

Retry at specific times. The number of dates equals the number of retry attempts.

See Retry Strategies for detailed guidance.

Pause windows

Define times when calls should NOT be made:

{
  "pauseWindows": {
    "monday": [
      {
        "startAt": { "hour": 12, "minute": 0 },
        "endAt": { "hour": 14, "minute": 0 }
      }
    ],
    "advanced": [
      { "startAt": "2025-12-25T00:00:00Z", "endAt": "2025-12-26T00:00:00Z" }
    ]
  }
}

Use cases:

• Lunch breaks

• Outside business hours

• Holidays

• Special events

See Pause Windows for more details.

Launching a program

Programs don't run automatically when created. You explicitly launch them:

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

Response:

{
  "executionId": "execution-uuid"
}

This creates an execution that processes the audience. See Executions for details on monitoring.

Updating programs

Modify program settings:

curl -X PATCH https://api.gomobile.io/programs/PROGRAM_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Campaign Name",
    "retryStrategy": { "type": "none" }
  }'

Changes don't affect already-running executions. They apply to future launches.

Listing programs

View all programs:

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

Deleting programs

Remove a program:

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

This stops any running executions and removes the program.

Best practices

• Name clearly - Include dates or campaign type in the name

• Test first - Launch with a small test audience before full deployment

• Set stop times - Prevent runaway campaigns

• Use pause windows - Respect recipients' time

• Start with simple retries - Add complexity as needed

Related concepts

• Audiences - Who the program calls

• Flows - What happens during the call

• Executions - Running instances of programs

• Retry Strategies - Handling failures