Documentation and FREE DOWNLOADS for each script are below.

Manual AGI Integration

The scripts described on this page are downloadable, pre-made scripts. If you wish to integrate our carrier lookup directly into your own AGI script to perform more complex routing or analysis, see sample code here.

nplquery (Performs a carrier lookup and returns the response to dialplan variable)

nplquery: Free Download

nplquery performs a network query on a mobile number from your Asterisk dialplan.

The number to be queried should be stored (using SetVar) in CARRIER_QUERY. After calling our AGI lookup service, the network code of the mobile carrier is returned into the CARRIER_RESPONSE variable where it can be used in your dialplan.

If you're looking to route calls based on the response, see our nplroute utility below...

Example number lookup query in extensions.conf:

This example picks up on a user dialing a number starting with "07" - in the United Kingdom, 07xxx numbers are mobile numbers. We then use 44${EXTEN,1} to convert 07xxx to 447xxx (adding the international country code and dropping the national zero).

exten => _07X.,1,SetVar(CARRIER_QUERY=44${EXTEN,1}) exten => _07X.,2,AGI(/var/lib/asterisk/agi-bin/nplquery)

${CARRIER_RESPONSE} will now contain the carrier, eg "23415" for Vodafone, "23433" for Orange, etc etc, and you can use this variable as required in your script. If you simply want to route to a SIP provider based on the carrier, "nplroute" (below) might be more suited to your needs.

nplroute (Performs carrier lookup and finds your preferred SIP provider for this destination)

nplroute: Free Download

nplroute performs a lookup in the same way as nplquery, but also matches the carrier against a custom routing table, and returns the name of the SIP provider that should be used to call this destination. You can then use this directly in your Dial() command to place the call.

Like nplquery (above), nplroute still sets the dialplan variable CARRIER_RESPONSE to the carrier code (so you have access to the lookup response from your dialplan if needed), but it also performs a lookup on your preferred SIP routing table, and sets a new variable, CARRIER_ROUTE to contain your chosen SIP provider for this destination - which you can use directly in a DIAL command to route the call, for example:

Example: Routing a UK Mobile to a SIP provider based on a carrier lookup:

exten => _07X.,1,SetVar(CARRIER_QUERY=44${EXTEN,1}) exten => _07X.,2,AGI(/var/lib/asterisk/agi-bin/nplroute) exten => _07X.,3,Dial(SIP/44${EXTEN,1}@sip-${CARRIER_ROUTE});

When running, nplroute looks like this:

-- Executing SetVar("SIP/testphone-b5a52ab8", "CARRIER_QUERY=447785123456") in new stack
-- Executing AGI("SIP/testphone-b5a52ab8", "/var/lib/asterisk/agi-bin/nplroute") in new stack
-- Launched AGI Script /var/lib/asterisk/agi-bin/nplroute
-- AGI Script /var/lib/asterisk/agi-bin/nplroute completed, returning 0
-- Executing Dial("SIP/testphone-b5a52ab8", "SIP/447785123456@sip-vodafone") in new stack

During operation, nplroute will looks in your /etc/asterisk/nplroutes file to determine which SIP provider should be used for each destination network. The file should contain plmn codes, and sip providers, seperated a spaces, one pair per line. The first matching entry is used, allowing you to specify "fallbacks", for example "234" by itself will match any UK carrier, whereas 23415 (if placed ABOVE 234) will match only Vodafone UK.

Example /etc/asterisk/nplroutes file:

(A sample file is provided in the download, above)

23415 uk-provider-1
23410 uk-provider-2
234 uk-fallback-provider
50503 australia-vodafone
505 australia-other
 fallback-provider

Note the global "fallback" on the last line - preceded by only a space, and no network code - this will be used as a final fallback if nothing above it matched the returned carrier.

Other Code Samples & Asterisk Carrier Lookup Examples

To find code samples for other languages, click here.

To find an example of integrating carrier lookups into your Asterisk AGI scripts, click here.