Inbound

Bulk-adding DIDs to VICIdial: 300 numbers in two seconds

Adding 200 DIDs one at a time through the VICIdial API took 40.5 seconds. Copying 300 from one template DID took 1.9. The replies, limits and traps.

By Published 5 min read
Blue plastic wires with white tips connected to server and provide access to information

To the point

To load a block of inbound numbers, build and test one template DID, then clone it with the API function copy_did. It was about thirty times faster than add_did in our test, and every copy comes out configured the same.

  • add_did, one number per request: 200 numbers in 40.5 seconds.
  • copy_did, 100 numbers per request: 300 numbers in 1.9 seconds.
  • A new DID took a call two seconds after the API replied, with no reload.
  • The final reply line can say SUCCESS when a number was skipped, so count the lines.

The three functions

The Non-Agent API has add_did, copy_did (it "adds new Inbound DID entries to the system, copied from an existing DID entry") and update_did. Deleting is update_did with delete_did=Y. There is no API function for carriers. copy_did is recent: the changelog lists it in July 2024. Ask your server what it runs:

https://YOUR-SERVER/vicidial/non_agent_api.php?function=version

Both builds we tested (2.14-206 and 2.14-210) had all three.

Bar chart of time per number: add_did about 200 ms, copy_did about 6 ms
Time per number on one scratch server, one run of each

What the API user needs

The documentation asks for user level 8 or higher and the Modify DIDs permission. On our servers two more things applied: API access enabled on the user, and the function in the user's allowed API functions. Make a dedicated user with only those, limited to the three functions.

Copy in batches

Create one DID in the admin screen with everything set: route, in-group or call menu, recording. Dial it and confirm where it lands. Every copy inherits it, so this is the only number you set by hand. Use one template per destination.

Required fields:

  • source_did_pattern: 2 to 50 characters, a DID that exists.
  • new_dids: 2 to 2000 characters, comma separated.
  • source: a label for the caller, 20 characters at most.

The 2,000 character cap sets the batch size. We sent 100 ten-digit numbers (1,099 characters); about 180 fit.

https://YOUR-SERVER/vicidial/non_agent_api.php?source=didload&user=APIUSER&pass=APIPASS&function=copy_did&source_did_pattern=5550100001&new_dids=5552000001,5552000002

Read every reply line

One line comes back per number. The fields after the user are the new number, the template and the new DID's ID.

NOTICE: copy_did DID HAS BEEN ADDED - APIUSER|5552000001|5550100001|203|1

The trap is a mixed batch. We sent one existing number and one new one:

NOTICE: copy_did DID ALREADY EXISTS - APIUSER|5551000001
NOTICE: copy_did DID HAS BEEN ADDED - APIUSER|5553000006|5550100001|505|1
SUCCESS: copy_did DIDS HAVE BEEN ADDED - APIUSER|5550100001|1|1

The last line says SUCCESS, yet one of two was skipped. We read the last two fields as added and not added. Do not test for the word. Count the HAS BEEN ADDED lines against what you sent, and keep every raw reply. A missing template returns ERROR: copy_did SOURCE DID DOES NOT EXIST.

Checklist of reply lines and what each means for a bulk DID load
What to do with each kind of reply

Call three numbers

The API returned at 49.6 seconds past the minute and an inbound call to the new number was logged at 51, routed correctly. DIDs are looked up in the database at call time, which is why no reload is needed. Call the first, middle and last number, then check the log:

SELECT call_date, extension, did_id, did_route, channel
FROM vicidial_did_log
WHERE call_date >= CURDATE()
ORDER BY call_date DESC LIMIT 20;

The channel column shows which trunk delivered the call, a better record of carrier than the DID's carrier description field.

Replies that are not what you expect

  • A plus sign is accepted and can never ring. The inbound context is exten => _X.,1,AGI(agi-DID_route.agi), and _X. matches digits only. Store numbers exactly as the carrier sends them. The extension column in vicidial_did_log shows what arrives.
  • Wrong length gives a misleading error. A 1-character or 51-character pattern returned YOU MUST USE ALL REQUIRED FIELDS. Nothing was missing; 2 to 50 is the rule.
  • Descriptions under six characters are refused. "Sales" is five. Leave the field out and the template's is used.
  • Bad targets are caught. A nonexistent route, in-group or call menu is refused before a DID points at nothing.
  • Deleting is one at a time. update_did takes one pattern, so removing 300 is 300 requests.
  • Copies are snapshots. Change the template next month and nothing else changes. If a block may move together, route it all to one in-group or call menu.

Use add_did when each number needs its own settings, such as a number per client. At about 200 ms a number it still beats the form.

How we tested

One scratch cloud server, Ubuntu, Asterisk 22, API 2.14-210. All 200 add_did calls and all 300 copies succeeded. We did not record the network distance, so absolute times will not transfer. We did not test a new_dids value at the 2,000 limit, or parallel batches.

Questions people ask

How many numbers fit in one copy_did request?

The limit is 2,000 characters in new_dids. Ten-digit numbers with commas fit about 180.

Why did a call reach a new number without a reload?

The dialplan matches _X. and looks the DID up in the database when the call arrives.

Next steps

  1. Call version and confirm copy_did exists.
  2. Create an API user with Modify DIDs only.
  3. Test a template per destination, then send batches of 100 and count the added lines.

The carrier must deliver calls first: see PJSIP carrier setup. If the menu behind a number plays silence, read audio upload and conversion. Moving numbers from another host? We load DIDs as part of a migration, or order a server.

VICIdial is a trademark of its owner. Trustane is an independent hosting provider.

Trustane

Managed VICIdial hosting

Run it on cores of your own

Managed VICIdial, billed by the hour against a balance you top up.

Or try one server free for 7 days, no top-up.