VoIPBin Documentation
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 /outplansreturns 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 destination_0 on the outdialtarget |
max_try_count_1 |
Max retries for destination_1 on the outdialtarget |
max_try_count_2 |
Max retries for destination_2 on the outdialtarget |
max_try_count_3 |
Max retries for destination_3 on the outdialtarget |
max_try_count_4 |
Max retries for destination_4 on the outdialtarget |
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_0: 5 (destination_0) |
| max_try_count_1: 5 (destination_1) |
+--------------------------------------------+
Timeline:
|--0m--|--10m--|--20m--|--30m--|--40m--|
1 2 3 4 5
(attempts per destination)
Standard Strategy (Sales)
+--------------------------------------------+
| Sales Outplan |
+--------------------------------------------+
| dial_timeout: 30 seconds |
| try_interval: 2 hours |
| max_try_count_0: 3 (destination_0) |
| max_try_count_1: 2 (destination_1) |
+--------------------------------------------+
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_0: 2 (destination_0) |
| max_try_count_1: 0 (skip destination_1) |
+--------------------------------------------+
Timeline:
|--0h--|--1h--|
1 2
(minimal disruption)
Destination-Based Retry Counts
Each outdialtarget supports up to 5 destination addresses (destination_0 through destination_4). The max_try_count_0 through max_try_count_4 fields on the outplan control how many times each destination index is attempted before moving to the next destination.
How Destination Fallback Works
destination_0 (+15551234567) -- max_try_count_0 attempts exhausted
|
v
destination_1 (+15559876543) -- max_try_count_1 attempts exhausted
|
v
destination_2 (sip:user@pbx) -- max_try_count_2 attempts exhausted
|
v
Target marked as done (all destinations exhausted)
Example Configuration
{
"max_try_count_0": 3, // Try destination_0 up to 3 times
"max_try_count_1": 2, // Try destination_1 up to 2 times
"max_try_count_2": 1, // Try destination_2 once
"max_try_count_3": 0, // Skip destination_3
"max_try_count_4": 0 // Skip destination_4
}
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_0: 4 (primary number) |
| max_try_count_1: 3 (secondary number) |
+--------------------------------------------+
Strategy:
- Long intervals to try morning, midday, afternoon
- More retries for primary number
- Fewer retries for secondary number
Scenario 2: Appointment Confirmation
Confirming next-day appointments.
Outplan: "Appointment Reminder"
+--------------------------------------------+
| dial_timeout: 25 seconds |
| try_interval: 2 hours |
| max_try_count_0: 2 (primary number) |
| max_try_count_1: 1 (secondary number) |
+--------------------------------------------+
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 (primary number) |
| max_try_count_1: 5 (secondary number) |
| max_try_count_2: 5 (office phone) |
| max_try_count_3: 3 (alternate) |
+--------------------------------------------+
Strategy:
- Long timeout (maximize answer chance)
- Frequent retries (urgent delivery)
- Multiple destination fallback for high delivery
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 per-destination 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 destination-specific configuration |
Configuration Issues
Symptom |
Solution |
|---|---|
Outplan not applied |
Verify outplan_id in campaign; check outplan exists and is active |
Wrong retry behavior |
Review per-destination max_try_count values; check which destination index is being dialed |
Values seem wrong |
Confirm millisecond format; 30 seconds = 30000ms, 1 hour = 3600000ms |
Outplan
Outplan
{
"id": "<string>",
"customer_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 viaPOST /outplansor listing viaGET /outplans.customer_id(UUID): The customer who owns this outplan. Obtained from theidfield ofGET /customers.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 fordestination_0on outdialtargets.max_try_count_1(Integer): Maximum number of dial attempts fordestination_1on outdialtargets.max_try_count_2(Integer): Maximum number of dial attempts fordestination_2on outdialtargets.max_try_count_3(Integer): Maximum number of dial attempts fordestination_3on outdialtargets.max_try_count_4(Integer): Maximum number of dial attempts fordestination_4on 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 to9999-01-01 00:00:00.000000if 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/loginor use an access key fromGET /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 viaGET /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 --location --request GET 'https://api.voipbin.net/v1.0/outplans?token=<YOUR_AUTH_TOKEN>'
{
"result": [
{
"id": "d5fb7357-7ddb-4f2d-87b5-8ccbfd6c039e",
"customer_id": "7a1b2c3d-4e5f-6789-abcd-ef0123456789",
"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 --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",
"customer_id": "7a1b2c3d-4e5f-6789-abcd-ef0123456789",
"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
}'
{
"id": "d5fb7357-7ddb-4f2d-87b5-8ccbfd6c039e",
"customer_id": "7a1b2c3d-4e5f-6789-abcd-ef0123456789",
"name": "test outplan",
"detail": "outplan for test use.",
"source": {
"type": "tel",
"target": "+15559876543",
"target_name": "",
"name": "",
"detail": ""
},
"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,
"tm_create": "2022-04-28 01:50:23.414000",
"tm_update": "9999-01-01 00:00:00.000000",
"tm_delete": "9999-01-01 00:00:00.000000"
}
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",
"customer_id": "7a1b2c3d-4e5f-6789-abcd-ef0123456789",
"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"
}