This article covers Press8’s call web URL features, which connect your phone service to your own web server. In the Press8 phone-system portal these are called “Web URLs” (you may also see the term “call web URL”). There are two features. Most integrations that only need to know about calls, such as logging calls or spotting missed calls, need only the first:
- Events URL (account-wide call notifications): your account tells your web server about every call as it starts, is answered and ends, without affecting how calls are routed.
- Web URLs: a number, menu option or other destination sends a call to a Web URL, and your web server decides where the call goes. Your server can also be told when that call is answered and when it ends.
1. Events URL (account-wide call notifications)
Your account can also send a notification to one URL on your server for every call on the account: when a call starts, when it is answered and when it ends, including incoming calls. These notifications only tell your server what is happening; they do not route calls.
Setting it up
- The address is set with the API:
customers/updatewith your account ID (id) and theevents_urlparameter. This needs the administrator permission on your API user; if you do not have it, ask the administrator on your Press8 account. See Press8 Phone System API. - Important:
customers/updatewithoutevents_urlclears it, so any software that updates your account settings must include your current address. - To stop notifications, set
events_urlto an empty value. - Notifications are sent with the scheme your URL has, so use an
https://address. - If the address does not take effect after a successful update, contact Press8 support to have the feature enabled on your account.
What arrives
Each event is one POST request with the event’s details as form fields. Every notification includes class (for example “call”), event (for example “start”, “answer” or “hangup”) and timestamp (a Unix timestamp to the microsecond). Other fields depend on the event; use uniqueid to tie together the events for one call and to look it up later through the API. A call start event looks like this (some fields omitted):
{"callid":"1234567890.100000","class":"call","event":"start","timestamp":"1234567890.123456","uniqueid":"1234567890.100000"}
Notifications only concern your own account. Other account events may also arrive; ignore any you do not use. If an incoming caller has withheld their number, the caller’s number is left blank. Your reply body is ignored.
2. Web URLs
A Web URL lets your own software make the routing decision for a call. When a call reaches a Web URL, the phone system sends the call’s details to your server and asks where the call should go. Your server replies with a destination, for example a hunt group, a mailbox or an extension, and the call continues there.
What a Web URL contains
| Portal field | API parameter | Description |
|---|---|---|
| Name | name | Required. Must be unique on your account. |
| Description | description | Optional. |
| URL to ask how to route call | route | Required. Your server is asked here where each call should go. |
| URL to inform on answer | answer | Optional. Your server is told here when the call is answered. |
| URL to inform on hangup | hangup | Optional. Your server is told here when the call ends. |
| Timeout waiting for web server | timeout | Seconds to wait for your server. Default 5. |
| On timeout or if routing URL returns an error, forward to | dtype, dnumber | Where the call goes if your server does not give a usable answer. Default: hang up. |
Use https:// addresses. A URL entered without a scheme is treated as plain http://, which is not encrypted.
Setting one up in the portal
- Log in at manage.press8.com and open the Web URLs page (in the portal menu under Features and tools, Call features, Web URLs).
- Create a new Web URL and fill in the fields above.
- Wherever you choose where a call goes (for example a phone number’s routing, a menu option, or where a hunt group sends unanswered calls), choose the destination Ask web URL and pick your Web URL.
If you do not see the Web URLs page or cannot create one, your login or plan does not include it; ask the administrator on your Press8 account.
Setting one up with the API
Web URLs can also be managed with the urls functions of the Press8 Phone System API: urls/create, urls/update, urls/get, urls/list and urls/delete, using the parameter names above. These need the urls (Web URLs) permission on your API user, and Web URLs must be included in your account’s plan; if either is missing, ask the administrator on your Press8 account. urls/create returns the new Web URL’s id. To send calls to it from any destination setting, use destination type url with the Web URL’s id as the destination number. See Press8 Phone System API.
The routing request
When a call reaches the Web URL, your route URL receives one HTTP POST request with these form fields:
| Field | Description |
|---|---|
| uniqueid | ID of this call leg. The same value is sent to your answer and hangup URLs, so use it to tie them together. |
| callid | ID of the overall call. |
| machine | Identifies the call server handling the call. For information only. |
| customer, scustomer | Account ID recorded as the source of the call. |
| stype, snumber | Type and number of the caller. snumber is blank if the caller has withheld their number. Other caller ID fields are sent as received and are not blanked. |
| callerid_internal, callerid_external | Caller ID details of the call. |
| ctype, cnumber | Type and number that was called. |
| dcustomer | Your account ID. |
| dtype, dnumber | The destination the call came through on its way to the Web URL. |
| state | ring if the call has not been answered yet, answer if it already has (for example after passing through a menu). |
| patternmenu_digits | Only sent when the call came through a pattern menu: the digits the caller entered. |
Your reply
Reply with a success status (2xx) and a plain-text body of name=value lines (name: value also works), one per line. Names are not case-sensitive, values cannot contain spaces, and lines the system does not recognise are ignored.
| Line | Description |
|---|---|
| dtype | Required. The destination type, for example huntgroup, mailbox, phone, ivr, queue, forward or hangup. With forward, the number in dnumber is dialled as if it were dialled on your account, so an outside number places an outgoing call. |
| dnumber | Required, but may be empty for types that need no number (such as hangup). The ID or number of the destination, for example the hunt group ID, mailbox number or number to forward to. |
| answer_url | Optional. Replaces the Web URL’s answer URL for this call only. |
| hangup_url | Optional. Replaces the Web URL’s hangup URL for this call only. |
Example reply sending the call to hunt group 1234:
dtype=huntgroup dnumber=1234
Only return destinations that belong to your own account. Your reply is not checked when it arrives: if the destination you return does not exist, the call fails instead of going to the fallback destination, so test each reply your server can give. Destination IDs are shown in the portal and returned by the API (for example huntgroups/list).
When your server does not answer
If your server does not reply within the timeout, returns an error status, or its reply lacks either a dtype or a dnumber line, the call goes to the Web URL’s fallback destination (“On timeout or if routing URL returns an error, forward to”). The default fallback is to hang up, so set a sensible fallback, such as your main hunt group or a mailbox, so callers are never cut off if your server is down. Keep the timeout short, since the caller is waiting. Replies larger than 1 MB are not accepted.
Answer and hangup notifications
If an answer URL is set, it receives a POST when the call is answered, with state set to answer, the same call fields as the routing request except patternmenu_digits (including uniqueid), the call’s current dtype and dnumber, recording, and type (how the call was answered; it can be blank, queue or callback).
If a hangup URL is set, it receives a POST when the call ends, with state set to hangup, the same call fields, plus status, totaltime and talktime (seconds).
Replies to the answer and hangup URLs are ignored and cannot change the call; an empty reply is fine. The same timeout applies to them.
Good practice for both features
- Reply quickly, within a few seconds. For a Web URL, the caller is waiting while your server decides.
- Secure your URLs so nobody else can send you fake requests, for example with a long secret key in the URL, and use HTTPS.
- Be tolerant of change. New fields and events can be added without warning; ignore anything you do not recognise.
Help
For permissions, or to create or change Web URLs and the notification address, ask the administrator on your Press8 account. If requests stop arriving and nothing on your side has changed, contact Press8 support.
