Outplan

An outplan is an outbound calling plan that defines the schedule, concurrency limits, and dialing rules for automated outbound campaigns.

API Reference: Outplan endpoints

Overview

Note

AI Context

• Complexity: Low

• Cost: Free. Creating and managing outplans is free. Costs are incurred when the associated campaign dials targets.

• Async: No. POST /outplans returns immediately with the created outplan.

VoIPBIN’s Outplan API provides fine-grained control over dialing strategies for outbound campaigns. An outplan defines how the system should handle dial attempts, including timeouts, retry intervals, and maximum attempt counts. By configuring outplans, you can optimize contact rates while respecting recipient preferences and regulatory requirements.

With the Outplan API you can:

• Configure dial timeout durations

• Set retry intervals between attempts

• Define maximum retry counts

• Create different strategies for various campaign types

• Optimize contact rates and efficiency

How Outplans Work

Outplans define the “when and how” of dialing in campaign operations.

Outplan Architecture

+-----------------------------------------------------------------------+
|                         Outplan System                                |
+-----------------------------------------------------------------------+

+-------------------+
|      Outplan      |
| (dialing strategy)|
+--------+----------+
         |
         | defines
         v
+--------+----------+--------+----------+--------+----------+
|                   |                   |                   |
v                   v                   v                   v
+----------+   +----------+   +----------+   +----------+
|  Dial    |   |  Retry   |   |  Max     |   |  Timing  |
| Timeout  |   | Interval |   | Attempts |   | Windows  |
+----------+   +----------+   +----------+   +----------+
     |              |              |              |
     v              v              v              v
+---------+    +---------+    +---------+    +---------+
| 30 sec  |    | 1 hour  |    | 3 tries |    | 9am-6pm |
+---------+    +---------+    +---------+    +---------+

Key Components

• Dial Timeout: How long to wait for an answer before giving up

• Try Interval: Time between retry attempts

• Max Try Count: Maximum number of dial attempts per target

• Timing Windows: When dialing is permitted (optional)

Note

AI Implementation Hint

The dial_timeout and try_interval fields are in milliseconds. A 30-second dial timeout is 30000, not 30. A 2-hour retry interval is 7200000. The max_try_count_0 through max_try_count_4 correspond to destination indices on the outdialtarget (destination_0 through destination_4), not result types.

Outplan Configuration

Configure outplan parameters based on your campaign needs.

Dial Timeout

The dial timeout specifies how long the system waits for the target to answer before marking the attempt as failed.

Dial initiated
     |
     v
+-------------------+
| Ring...           |
| (counting time)   |
+--------+----------+
         |
         +-----> Answered within timeout? --> Success
         |
         +-----> Timeout reached? --> Mark as no_answer

Recommended Timeouts

Try Interval

The try interval defines the wait time between consecutive dial attempts to the same target.

Attempt 1: No answer
     |
     v
+-------------------+
| Wait: try_interval|
| (e.g., 1 hour)    |
+--------+----------+
         |
         v
Attempt 2: Try again
     |
     v
+-------------------+
| Wait: try_interval|
+--------+----------+
         |
         v
Attempt 3: Final attempt

Recommended Intervals

Campaign Type	Recommended	Reasoning
Sales calls	2-4 hours	Try different times of day
Reminders	30-60 minutes	Moderate urgency
Emergency	5-15 minutes	High urgency, frequent retries

Max Try Count

The maximum try count limits how many times the system will attempt to reach a target.

+-------------------+
| max_try_count: 3  |
+-------------------+
         |
         v
Attempt 1 --> No answer
Attempt 2 --> Busy
Attempt 3 --> No answer
--> Mark as FAILED (max reached)

Creating an Outplan

Create outplans via the API.

Create Outplan Example

$ curl -X POST 'https://api.voipbin.net/v1.0/outplans?token=<token>' \
    --header 'Content-Type: application/json' \
    --data '{
        "name": "Sales Standard",
        "detail": "Standard sales campaign strategy",
        "dial_timeout": 30000,
        "try_interval": 7200000,
        "max_try_count_0": 3,
        "max_try_count_1": 2,
        "max_try_count_2": 1,
        "max_try_count_3": 0,
        "max_try_count_4": 0
    }'

Field Descriptions

Field	Description
dial_timeout	Ring timeout in milliseconds (30000 = 30 seconds)
try_interval	Wait between retries in milliseconds (7200000 = 2 hours)
max_try_count_0	Max retries for result type 0 (machine/voicemail)
max_try_count_1	Max retries for result type 1 (busy)
max_try_count_2	Max retries for result type 2 (no answer)
max_try_count_3	Max retries for result type 3 (failed/error)
max_try_count_4	Max retries for result type 4 (other)

Outplan Strategies

Different campaign types require different dialing strategies.

Aggressive Strategy (Emergency)

+--------------------------------------------+
| Emergency Outplan                          |
+--------------------------------------------+
| dial_timeout:    45 seconds                |
| try_interval:    10 minutes                |
| max_try_count:   5 (all types)             |
+--------------------------------------------+

Timeline:
|--0m--|--10m--|--20m--|--30m--|--40m--|
   1      2       3       4       5
(attempts)

Standard Strategy (Sales)

+--------------------------------------------+
| Sales Outplan                              |
+--------------------------------------------+
| dial_timeout:    30 seconds                |
| try_interval:    2 hours                   |
| max_try_count:   3 (no answer/busy)        |
|                  1 (machine)               |
+--------------------------------------------+

Timeline:
|--0h--|--2h--|--4h--|
   1      2      3
(attempts spread across day)

Conservative Strategy (Reminders)

+--------------------------------------------+
| Reminder Outplan                           |
+--------------------------------------------+
| dial_timeout:    25 seconds                |
| try_interval:    1 hour                    |
| max_try_count:   2 (all types)             |
+--------------------------------------------+

Timeline:
|--0h--|--1h--|
   1      2
(minimal disruption)

Result-Based Retry Counts

Configure different retry counts based on the outcome of each attempt.

Result Types

Type	Result	Typical Retry Strategy
0	Machine/VM	Low retries (1-2); person may not check voicemail
1	Busy	Medium retries (2-3); likely to be free later
2	No answer	High retries (3-5); try different times
3	Failed/Error	Low retries (0-1); may be invalid number
4	Other	Configurable based on use case

Example Configuration

{
    "max_try_count_0": 1,  // Machine: try once more
    "max_try_count_1": 3,  // Busy: retry 3 times
    "max_try_count_2": 4,  // No answer: retry 4 times
    "max_try_count_3": 0,  // Failed: don't retry
    "max_try_count_4": 1   // Other: try once more
}

Common Scenarios

Scenario 1: B2B Sales Campaign

Reaching business contacts during work hours.

Outplan: "B2B Sales"
+--------------------------------------------+
| dial_timeout:    30 seconds                |
| try_interval:    4 hours                   |
| max_try_count_1: 3 (busy)                  |
| max_try_count_2: 4 (no answer)             |
+--------------------------------------------+

Strategy:
- Long intervals to try morning, midday, afternoon
- More retries for no answer (might be in meetings)
- Fewer retries for busy (clearly occupied)

Scenario 2: Appointment Confirmation

Confirming next-day appointments.

Outplan: "Appointment Reminder"
+--------------------------------------------+
| dial_timeout:    25 seconds                |
| try_interval:    2 hours                   |
| max_try_count_1: 2 (busy)                  |
| max_try_count_2: 2 (no answer)             |
+--------------------------------------------+

Strategy:
- Short timeout (quick notification)
- Limited retries (not critical)
- Spread across afternoon/evening

Scenario 3: Critical Alert

Emergency notifications requiring high delivery.

Outplan: "Emergency Alert"
+--------------------------------------------+
| dial_timeout:    45 seconds                |
| try_interval:    5 minutes                 |
| max_try_count_0: 5 (all types)             |
| max_try_count_1: 5                         |
| max_try_count_2: 5                         |
| max_try_count_3: 3                         |
+--------------------------------------------+

Strategy:
- Long timeout (maximize answer chance)
- Frequent retries (urgent delivery)
- Retry even failures (might be temporary issue)

Best Practices

1. Timeout Configuration

• Set realistic timeouts (25-45 seconds)

• Account for call setup time

• Consider mobile vs. landline behavior

• Test across different carriers

2. Retry Intervals

• Space retries to try different times of day

• Avoid too-frequent retries (annoys recipients)

• Match urgency level of campaign

• Consider time zone differences

3. Max Try Counts

• Balance persistence with respect for recipients

• Use result-based retry counts for efficiency

• Higher counts for critical campaigns

• Lower counts for promotional calls

4. Compliance

• Follow local regulations on retry limits

• Respect quiet hours (no early morning/late night)

• Document retry policies for auditing

• Honor do-not-call after failed attempts

Troubleshooting

Timing Issues

Symptom	Solution
Calls timing out too quickly	Increase dial_timeout; check network latency; verify carrier routing
Retries happening too fast	Increase try_interval; verify millisecond values are correct
Not enough retries	Increase max_try_count values; check result type configuration

Configuration Issues

Symptom	Solution
Outplan not applied	Verify outplan_id in campaign; check outplan exists and is active
Wrong retry behavior	Review result-type specific max_try_count values; check which result type is being set
Values seem wrong	Confirm millisecond format; 30 seconds = 30000ms, 1 hour = 3600000ms

Related Documentation

• Campaign Overview - Using outplans in campaigns

• Outdial Overview - Target management

• Queue Overview - Agent routing

• Call Overview - Call handling details

Outplan

Outplan

{
    "id": "<string>",
    "name": "<string>",
    "detail": "<string>",
    "source": {
        ...
    },
    "dial_timeout": 30000,
    "try_interval": 60000,
    "max_try_count_0": <number>,
    "max_try_count_1": <number>,
    "max_try_count_2": <number>,
    "max_try_count_3": <number>,
    "max_try_count_4": <number>,

    "tm_create": "<string>",
    "tm_update": "<string>",
    "tm_delete": "<string>"
}

• id (UUID): The outplan’s unique identifier. Returned when creating via POST /outplans or listing via GET /outplans.

• name (String): Human-readable name for the outplan.

• detail (String): Detailed description of the outplan’s strategy.

• source (Object): Source address (caller ID) used when dialing. See Address.

• dial_timeout (Integer): Maximum time in milliseconds to wait for the target to answer before marking as no-answer. For example, 30000 = 30 seconds.

• try_interval (Integer): Delay time in milliseconds between retry attempts to the same target. For example, 3600000 = 1 hour.

• max_try_count_0 (Integer): Maximum number of dial attempts for destination_0 on outdialtargets.

• max_try_count_1 (Integer): Maximum number of dial attempts for destination_1 on outdialtargets.

• max_try_count_2 (Integer): Maximum number of dial attempts for destination_2 on outdialtargets.

• max_try_count_3 (Integer): Maximum number of dial attempts for destination_3 on outdialtargets.

• max_try_count_4 (Integer): Maximum number of dial attempts for destination_4 on outdialtargets.

• tm_create (string, ISO 8601): Timestamp when the outplan was created.

• tm_update (string, ISO 8601): Timestamp of the last update to any outplan property.

• tm_delete (string, ISO 8601): Timestamp when the outplan was deleted. Set to 9999-01-01 00:00:00.000000 if not deleted.

Note

AI Implementation Hint

The dial_timeout and try_interval fields are in milliseconds. Common conversions: 30 seconds = 30000, 1 minute = 60000, 1 hour = 3600000, 2 hours = 7200000. A tm_delete value of 9999-01-01 00:00:00.000000 is a sentinel meaning the resource has not been deleted.

Example

{
    "id": "d5fb7357-7ddb-4f2d-87b5-8ccbfd6c039e",
    "name": "test outplan",
    "detail": "outplan for test use.",
    "source": {
        "type": "tel",
        "target": "+15559876543",
        "target_name": "",
        "name": "",
        "detail": ""
    },
    "dial_timeout": 30000,
    "try_interval": 60000,
    "max_try_count_0": 5,
    "max_try_count_1": 5,
    "max_try_count_2": 5,
    "max_try_count_3": 5,
    "max_try_count_4": 5,
    "tm_create": "2022-04-28 01:50:23.414000",
    "tm_update": "2022-04-30 12:01:13.780469",
    "tm_delete": "9999-01-01 00:00:00.000000"
}

Try interval

When VoIPBIN makes a retry dial attempt, it waits the try_interval duration (in milliseconds) after the previous call ends before dialing again.

Max try count

The max_try_count_N fields configure the maximum number of dial attempts for the corresponding destination_N on outdialtargets.

Tutorial

Before working with outplans, you need:

• An authentication token. Obtain one via POST /auth/login or use an access key from GET /accesskeys.

• A source phone number in E.164 format (e.g., +15559876543) to use as the caller ID. This number should be obtained from your provisioned numbers via GET /numbers.

Note

AI Implementation Hint

All time values (dial_timeout and try_interval) are in milliseconds. A common mistake is to pass seconds instead of milliseconds. For example, a 30-second timeout should be 30000, not 30. A 10-minute retry interval should be 600000.

Get list of outplans

Example

$ curl -k --location --request GET 'https://api.voipbin.net/v1.0/outplans?token=<YOUR_AUTH_TOKEN>'

{
    "result": [
        {
            "id": "d5fb7357-7ddb-4f2d-87b5-8ccbfd6c039e",
            "name": "test outplan",
            "detail": "outplan for test use.",
            "source": {
                "type": "tel",
                "target": "+15559876543",
                "target_name": "",
                "name": "",
                "detail": ""
            },
            "dial_timeout": 30000,
            "try_interval": 60000,
            "max_try_count_0": 5,
            "max_try_count_1": 5,
            "max_try_count_2": 5,
            "max_try_count_3": 5,
            "max_try_count_4": 5,
            "tm_create": "2022-04-28 01:50:23.414000",
            "tm_update": "2022-04-30 12:01:13.780469",
            "tm_delete": "9999-01-01 00:00:00.000000"
        }
    ],
    "next_page_token": "2022-04-28 01:50:23.414000"
}

Get detail of outplan

Example

$ curl -k --location --request GET 'https://api.voipbin.net/v1.0/outplans/d5fb7357-7ddb-4f2d-87b5-8ccbfd6c039e?token=<YOUR_AUTH_TOKEN>'

{
    "id": "d5fb7357-7ddb-4f2d-87b5-8ccbfd6c039e",
    "name": "test outplan",
    "detail": "outplan for test use.",
    "source": {
        "type": "tel",
        "target": "+15559876543",
        "target_name": "",
        "name": "",
        "detail": ""
    },
    "dial_timeout": 30000,
    "try_interval": 60000,
    "max_try_count_0": 5,
    "max_try_count_1": 5,
    "max_try_count_2": 5,
    "max_try_count_3": 5,
    "max_try_count_4": 5,
    "tm_create": "2022-04-28 01:50:23.414000",
    "tm_update": "2022-04-30 12:01:13.780469",
    "tm_delete": "9999-01-01 00:00:00.000000"
}

Create a new outplan

Example

$ curl --location --request POST 'https://api.voipbin.net/v1.0/outplans?token=<YOUR_AUTH_TOKEN>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "name": "test outplan",
        "detail": "outplan for test use.",
        "source": {
            "type": "tel",
            "target": "+15559876543"
        },
        "dial_timeout": 30000,
        "try_interval": 600000,
        "max_try_count_0": 5,
        "max_try_count_1": 5,
        "max_try_count_2": 5,
        "max_try_count_3": 5,
        "max_try_count_4": 5
    }'

Update outplan’s dial info

Example

$ curl --location --request PUT 'https://api.voipbin.net/v1.0/outplans/d5fb7357-7ddb-4f2d-87b5-8ccbfd6c039e/dial_info?token=<YOUR_AUTH_TOKEN>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "source": {
            "type": "tel",
            "target": "+15559876543"
        },
        "dial_timeout": 30000,
        "try_interval": 60000,
        "max_try_count_0": 5,
        "max_try_count_1": 5,
        "max_try_count_2": 5,
        "max_try_count_3": 5,
        "max_try_count_4": 5
    }'

Delete outplan

Example

$ curl --location --request DELETE 'https://api.voipbin.net/v1.0/outplans/88334a03-bc6b-40b6-878f-46df2d9865db?token=<YOUR_AUTH_TOKEN>'

Update outplan’s basic info

Example

$ curl --location --request PUT 'https://api.voipbin.net/v1.0/outplans/d5fb7357-7ddb-4f2d-87b5-8ccbfd6c039e?token=<YOUR_AUTH_TOKEN>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "name": "test outplan",
        "detail": "outplan for test use"
    }'

{
    "id": "d5fb7357-7ddb-4f2d-87b5-8ccbfd6c039e",
    "name": "test outplan",
    "detail": "outplan for test use",
    "source": {
        "type": "tel",
        "target": "+15559876543",
        "target_name": "",
        "name": "",
        "detail": ""
    },
    "dial_timeout": 30000,
    "try_interval": 60000,
    "max_try_count_0": 5,
    "max_try_count_1": 5,
    "max_try_count_2": 5,
    "max_try_count_3": 5,
    "max_try_count_4": 5,
    "tm_create": "2022-04-28 01:50:23.414000",
    "tm_update": "2022-05-02 05:59:44.290658",
    "tm_delete": "9999-01-01 00:00:00.000000"
}