Webhooks (formerly known as data collection in earlier versions) are powerful action rules in the Axeos pbx that you can e.g. use to:

• measure calls by recording an event in Google Analytics whenever your office is called.
• automate redirection of calls from customer service to your sales or finance department, if the caller has overdue invoices to pay.
• automate appointments in healthcare offices.
• automate prescription renewal in pharmacies.

How does it work?

When a call reaches a rule triggering this action, the caller will hear the voice prompt asking him to enter specified digits (this could be a customer number). An HTTP request can then be sent to your web application/API. The PBX matches a response against a regular expression. If the regexp matches or if it is not provided, the action will be treated as successful. If not (4xx, 5xx response, regexp does not match or I/O error), the action will be treated as failure and handled by the ‘on failure’ or ‘on error’ conditions.

• Prompt: set custom sound to play
• Number of digits: maximum number of digits to accept. 0 = no maximum, or no data input at all if ‘Exact length’ is enabled.
• Exact length only:
  • Yes: only the specified number of digits will be allowed. In this example the request will be sent when the caller enters 6 digits. Until then the sound prompt will be repeated.
  • No: entered digits must be finished by pressing the pound (#) key.
• Service URL: ‘https’ or ‘http’ URI to remote server which may contain special variables, e.g every DID may have separate URI on the server e.g. http://webserveraddress/did/${called_did}.
• Request timeout: the number of seconds to wait for a response.
• Request method: POST or GET.
• Content type: text/plain, application/json, or application/x-www-form-unencoded.
• Request body: request body for POST. May contain the same special variables as the URL, it can also be text, XML, JSON.
• Response body regexp: regular expression to match the successful response body to.
• On success: set which action should be executed when action will be successful.
  Please note that a positive response (2xx) will be matched against the regexp provided. If the regexp is not provided, the action will be considered successful.
  • Continue: execute next dialplan action
  • Extension: call local extension. The regexp match will be used to retrieve which extension number should be called. The Response body regexp must be provided and must contain at least one group (parentheses pair). The first group of the match will be used as the extension number to call.
  • Dialplan actions: set specified IVR. The regexp match group will be used as a selected option of this IVR.
  • Dial number: call the phone number returned by your HTTP service. The web service used by the rule is then expected to return a string (as whole HTTP response or the part matched by the ‘Response body regexp’ provided): NUMBER or NUMBER/CALLERID or NUMBER/anonymous or NUMBER/original. Please note that this feature gives dialout control to the external web service. Never use this with untrusted servers. If you want to be absolutely sure to limit the allowed destination, you are to use the extension or IVR actions.
  • Play digits: play the digits returned by your HTTP service to the caller.
• Condition: Unconditionally, Status, Caller-ID, Time rule and Switches

Caveat: if you use an audio prompt, make sure the audio channel is opened as there is no human yet to answer the call, or the caller will not be able to hear the prompt you set. This can be done by using the ‘Answer’ rule.

Variables

Special variables which can be used in URI and request body:

• ${data} – strings of digits entered by the caller on the phone
• ${unique_id} – the unique ID of the call
• ${called_did} – called DID number if data collection is set as action rule for inbound number
• ${called_extension} – caller extension if data collection is set as action rule for local extension
• ${caller_user_uuid} – caller user uuid if caller is one of PBX users
• ${caller_phone_uuid} – caller phone uuid if caller is using one of PBX phones
• ${caller_trunk_uuid} – caller trunk uuid
• ${caller_number} – caller number
• ${caller_normalized_number} – caller normalized number
• ${caller_original_number} – caller original number