The web AGI functionality allows you to build your own IVR menu using entirely custom logic. You will need the following to use our web AGI functionality:
- A publically accessible web server
- To make full use of the functionality, the server will need to be configured to run server side scripts in a language of your choice
- A Gradwell Multi User VoIP account
Please be aware that our support team are unable to provide advice on configuring your server scripts if you choose to use a web AGI router.
Creating a new web AGI router
To create a web AGI router, click on Web AGI Routing from the top menu of the control panel.
Select an unused internal and enter a descriptive name for your new router.
After you have clicked Create you can click your web AGI router to configure it.
You will need to enter the URL of the server that you have placed your scripts on. This is the URL that we will send HTTP POST requests to.
Finally, don't forget to ensure that you add the router as a destination from a phone number or call management tool (such as an IVR menu). For reference we include a Routing Information box on the configuration page to show you the internal routes to the number.
After a call is made to a web AGI router, we will log full details of the call on this page. This helps you troubleshoot any problems you encounter.
When a call is received at the Web AGI number, our system will make an HTTP POST request to the configured URL. The following fields will be included in the POST request.
|_time||The time of the request, as a UNIX timestamp||1312551926|
|_callerid||The phone number of the caller (or anonymous, withheld, etc)||01225800800|
|_calleridname||Any name provided, from an internal SIP call or retrieved from the customer’s directory||Gradwell Support|
|_extension||The internal 7 digit extension number||1122345|
The script must return a JSON encoded data structure, as follows:
|response_url||Optional||URL||If provided, this URL will be used for all subsequent HTTP requests. If omitted, the URL used for the previous request will be used again|
|actions||Required||Array of 'Action' objects||This is the list of actions which defines how the call will be handled (see below)|
Each entry in the ‘actions’ list is an object with the following fields:
|response_url||Optional||URL||Must be one of ‘read’, ‘dial’, ‘play’, or ‘hangup’|
|voiceprompt_id||Required for 'play'
Optional for 'read'
|Integer||This specifies the voice prompt to play as a standalone prompt (‘play’ action) or before a ‘read’ action. If a voiceprompt is played by a ‘read’ action then the user can start typing digits as soon as the prompt starts to play. To force a user to listen to a prompt before entering digits, use a ‘play’ followed by a ‘read’ with no voiceprompt specified. The voiceprompt IDs are listed on the ‘Voice Prompts’ page in the VoIP control panel|
|name||Optional for 'read'||String||The name of the field when this field is sent back with the HTTP POST request. If omitted, the field name will be “p0” for the first action, incrementing for each action. Note that all actions count, so an action sequence “play, read, play, read” would submit “p1” and “p3”, if they didn’t have names specified|
|error||Optional for 'read'||String||This field defines how to handle errors when reading numbers. If set to ‘start’ then after an error, the call will return to the first of the current set of actions. If set to ‘submit’, then all data read so far (if any) will immediately be sent to the HTTP URL. If omitted, then errors are ignored, and are simply omitted when sending all fields after processing all actions|
|destination||Required for 'dial'||Phone number||This is the phone number to dial. This may be any number that you can dial from an extension, for example a PSTN number, or an internal 7 digit extension number|
|min||Optional for 'read'||Integer||The minimum number of digits for a ‘read’ action. If the user enters fewer digits, it will be handled as specified by the ‘error’ setting above. The default is no minimum|
|max||Optional for 'read'||Integer||The maximum number of digits for a ‘read’ action. A user may enter fewer digits (subject to the ‘min’ setting) however the script will keep waiting for as long as the ‘wait’ setting specifies, or until the user presses the hash key to end input of that field|
|wait||Optional for 'read'||Integer||This field specifies how long to wait between each digit of a ‘read’ action, in milliseconds. The default is 5000 (5 seconds). Note that this is the period between each digit, not the time limit to enter the whole sequence of digits. If a user pauses too long between digits, it will be handled as specified by the ‘error’ setting|
Authenticating a customer
You may use this on their phone system to authenticate their own customers, before passing them through to a support team.
- Phone call is received
- HTTP POST to http://www.example.com/callhandler.php with fields _callerid=01225800800, _calleridname=Gradwell, _time=12223334444, _extension=1122345
- HTTP response lists 2 actions: [action=read, name=customer_id, voiceprompt_id=100], [action=read, name=pin, voiceprompt_id=101]
- The Web AGI system will process these actions. It is assumed that voice prompt 100 would say something like “Thank you for calling us, please enter your customer number” and that voice prompt 101 would say “Please enter your PIN code”
- After the customer enters the data, a second HTTP POST is sent to the same URL with two fields: customer_id=12345, pin=9876
- The response at this point is where the customer can create an extremely flexible phone system. Obviously the internal implementation is up to the end user, but querying a customer database is likely to be a common scenario
- If the customer ID and PIN are not valid, it may simply send a “play” action with an appropriate message, followed by the two read actions, to prompt the user to try again
- If the customer ID is valid, and is a key account, it may route directly to their account manager
- If the customer ID is valid, and is another customer, it may route to a standard support queue
Routing based on caller ID
The functionality may also be used to route based on the caller ID, for example to route callers to their local branch, or routing known customers to their account manager.
In this case, you would simply return an appropriate “dial” action in response to the initial request, after inspecting the _callerid field provided.