VoIPBin Documentation
Outplan
Overview
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)
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 |
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: Outplan’s id.
name: Outplan’s name.
detail: Outplan’s detail.
source: Source address. See detail here.
dial_timeout: Timeout for dialing. milliseconds
try_interval: Delay time for retry. milliseconds
max_try_count_0: Maximum try count for destination 0.
max_try_count_1: Maximum try count for destination 1.
max_try_count_2: Maximum try count for destination 2.
max_try_count_3: Maximum try count for destination 3.
max_try_count_4: Maximum try count for destination 4.
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 the VoIPBIN makes a retry dialing, it waits try interval after the previous call’s end.
Max try count
The max try count configs max try count for the given destination.
Tutorial
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"
}