Changing a DID's routing with update_did

Inbound routing changes all the time. A campaign closes, a new Ingroup opens, you turn recording on for compliance. Instead of opening the admin screen each time, the update_did function edits a single existing inbound DID (direct inward dialing) (the number callers dial) straight from an API call.

It updates the row in the inbound DID table for a number that already exists. This is a sibling of the copy_did call: copy_did creates new numbers, update_did fixes the ones you already have. The VICIdial API and AGI overview sets the broader context.

Required vs editable fields

Only two fields are required:

• did_pattern - the DID to edit, 2 to 50 characters, must be a valid DID in the system. URL-encode special characters (a plus sign becomes %2B).
• source - a short description of what triggered the call (max 20 characters).

Everything else is an editable field you include only if you want to change it. The useful ones:

• did_description - 6 to 50 characters.
• active - Y or N, to turn the number on or off.
• did_route - one of EXTEN, VOICEMAIL, AGENT, PHONE, IN_GROUP, CALLMENU, or VMAIL_NO_INST. This is the routing target.
• record_call - Y, N, or Y_QUEUESTOP.

When the route is IN_GROUP there are extra fields for the in-group's group id, call handle method, agent search method, list id, and campaign id. There is also delete_did (Y or N, default N) if you want to remove the DID entirely. The DID route value decides which of those extras matter.

Permission requirement

Same gate as copy_did: the API user needs user_level 8 or higher and "Modify DIDs" enabled. Deleting a DID needs the delete permission on top of that. Permission tiers across the whole API are explained in API user level permissions.

Example call

Re-point a DID at an extension, turn it off, and set recording:

http://your-server/vicidial/non_agent_api.php?source=test&user=6666&pass=1234&function=update_did&did_pattern=7275553331&did_description=Testing+DID&active=N&did_route=EXTEN&record_call=Y_QUEUESTOP&extension=8300&exten_context=notdefault

How update_did decides what to change

flowchart TD
  Call[update_did call] --> CheckPerm{user_level 8 plus Modify DIDs}
  CheckPerm -- no --> Deny[Permission error]
  CheckPerm -- yes --> CheckDID{DID exists}
  CheckDID -- no --> NotExist[DID DOES NOT EXIST]
  CheckDID -- yes --> Apply[Apply editable fields]
  Apply --> Route{did_route is IN_GROUP}
  Route -- yes --> Group[Use group and list settings]
  Route -- no --> Done[Update saved]
  Group --> Done

Reading the response

The common failures are clear. ERROR: update_did USER DOES NOT HAVE PERMISSION TO UPDATE DIDS means the user level or flag is wrong. ERROR: update_did DID DOES NOT EXIST means the did_pattern points at nothing. Each optional field validates separately, so a bad route returns ERROR: update_did DID ROUTE IS NOT VALID, THIS IS AN OPTIONAL FIELD, and a bad active value returns ERROR: update_did ACTIVE MUST BE Y OR N, THIS IS AN OPTIONAL FIELD. Fix the named field and resend.

Pair update_did with copy_did and you can manage a whole inbound DID inventory from a script with no clicking. On a VICIfast server the API is live as soon as the box provisions, in under 40 seconds. See our plans to start.