What the server_refresh API does after phone changes

When you add or edit phones over the API, the database changes right away, but the Asterisk side does not always pick it up immediately. The server_refresh function forces a conf file refresh on all telco servers in the cluster, so the changes you just made through the Non-agent API actually take effect on the dialer.

It is the simplest call in the set. The API (application programming interface) user still needs user_level 8 or higher with "ast admin access", and there is exactly one required field.

The one field it needs

server_refresh takes a single required field: stage, which must be the literal value REFRESH. Send anything else and you get YOU MUST USE ALL REQUIRED FIELDS. On success it returns SERVER REFRESH HAS BEEN TRIGGERED. There are no per-phone arguments — it is a cluster-wide nudge, not a targeted one.

Where it fits in a change

flowchart TD
  A[add_phone or update_phone] --> B[Database updated]
  B --> C[Call server_refresh stage REFRESH]
  C --> D[Conf files rebuilt on telco servers]
  D --> E[Asterisk reloads peers]
  E --> F[Phone can register]

In practice the Conf file that defines each Asterisk peer is regenerated from the database, and server_refresh is what asks for that rebuild across the cluster. After it runs, the new or changed SIP peer is present in the configuration and the phone can complete its registration.

When to call it

A good pattern is to do all your add_phone and update_phone work first, then call server_refresh once at the end. Calling it after every single phone is wasteful — one refresh after a batch is enough to push the whole set out. Treat it as the commit step that follows a round of changes.

It also matters when timing is tight. If you are standing up a room of agents before a shift and want every device able to register the moment it powers on, you do not want to wait for the next scheduled rebuild. One server_refresh after the import closes that gap. On a single-server install the cluster is just the one box, so the call still applies — it simply refreshes that one server rather than several.

If a phone still will not register after a refresh, the problem is usually the entry itself rather than the refresh. The checks are in how to test phone registration, and the broader setup is in the phones and aliases guide.

VICIfast handles the server side so refreshes just work — see pricing.