CallerHub
EN
Download

Asterisk, FreePBX, VitalPBX and Issabel: caller ID lookup via HTTP

Asterisk sets the caller name in the dial plan. You decide where the name comes from: an HTTP lookup per call that returns it from your CRM, database or directory.

How Asterisk looks up a name

  • Asterisk directly: in the incoming context, the function CURL (module func_curl) calls an address; the result is written to CALLERID(name) before the phone rings.
  • FreePBX and Issabel: the module CallerID Lookup Sources takes an HTTP source with host, port, path and query. Details are in the Sangoma documentation.
  • VitalPBX: a CID lookup source (HTTP/HTTPS) in the inbound route.

Keep the time-out short: if the service does not answer, the call should still ring at once. With HTTPS, Asterisk must trust the certificate of the service (store the root certificate on the Asterisk server).

With CallerHub: the address for your phone system

In CallerHub, create an interface for your phone system under Interfaces → Add interface, enter the address of the Asterisk server under Allowed IP addresses and choose Save and apply. “Copy instructions” provides the complete address with the real API key. The examples use 192.168.10.5 as the CallerHub computer and the placeholder API-KEY.

Phone systemQuery to enter
Asterisk / FreePBX (dial plan)…/lookup?apikey=…&called=${EXTEN}&number=${URIENCODE(${CALLERID(num)})}
FreePBX / Issabel (CallerID Lookup Sources)path /lookup, query format=text&apikey=…&number=[NUMBER]
VitalPBX (CID lookup source)…/lookup?apikey=…&number=[CIDNUM]

Dial plan example (FreePBX: extensions_custom.conf, context from-pstn-custom or similar)

exten => _X.,1,Set(CURLOPT(httptimeout)=2)
 same => n,Set(CALLERID(name)=${CURL(http://192.168.10.5:8080/lookup?apikey=API-KEY&called=${EXTEN}&number=${URIENCODE(${CALLERID(num)})})})
 same => n,Goto(from-pstn,${EXTEN},1)

Then reload the dial plan (dialplan reload). If CallerHub cannot be reached, the name stays empty after 2 seconds and the call continues normally. called passes the called number on for the statistics.

Call analytics via AMI or Master.csv

For answer rate and service level, the callback list and the live view, CallerHub reads the call records:

  • Live via AMI: CallerHub connects to port 5038. Create a user with read = cdr in manager.conf and set enabled = yes in cdr_manager.conf.
  • File: Master.csv from the Asterisk CDR module, also for past calls.
Call analytics
Call analytics for the last 30 days with figures on calls, answer rate, service level, callback rate and open callbacks.

Common errors

ObservationCause and remedy
Name stays empty, CallerHub shows no requestThe request does not reach CallerHub: check address, port, Windows firewall and firewalls between the networks; test from the Asterisk server with curl. Is func_curl loaded?
Log: status=401 or 403Wrong API key, or the address of the Asterisk server is not among the allowed IP addresses. Behind NAT the sender differs.
Request arrives, but no nameNumber unknown (test with “Check number”), wrong format, or the time-out is shorter than the response time.
Umlauts or accents wrongResponses are UTF-8; check the character set of the phone system.

The guides for Asterisk, FreePBX, VitalPBX and Issabel are based on published interfaces and have not yet been checked with these systems. Check placeholders, menu paths and setting names against the documentation of your version.

Frequently asked questions

Which response format does Asterisk expect?

Plain text: just the name, empty for unknown numbers. This is the CallerHub default for Asterisk, FreePBX, VitalPBX and Issabel; with format you can also choose JSON or XML.

Does the lookup slow down the call?

CallerHub answers calls from the phone number list in memory, so a slow database does not delay the response. The time-out in the dial plan also limits the wait, to 2 seconds in the example.

Can I connect several Asterisk servers?

Yes. Each phone system gets its own interface with its own API key, its own allowed IP addresses and its own selection of data sources. The basic edition allows one interface, the full edition up to ten.

Try it

Test it with your own data.

Try the full edition for 30 days: choose “Request trial …” in CallerHub and the trial key arrives by e-mail. The setup wizard guides you through data source, phone system and test lookup. After that, CallerHub continues as the free basic edition without losing settings or data.