Web URLs (Admin Center Voice Features)

Usage and Advantages
- Access and Existing Web URLs
Implementing Web URLs in the Admin Center
Adding new Web URLs
Predefined Web URLs
- Types of Predefined Web URLs
Custom Web URLs

Usage and Advantages

Web URLs let the Telebroad system dynamically route calls by consulting an external web address. Based on parameters passed by the system, the Web URL server responds with a destination, and the system routes the call accordingly. The external server can also be notified when a call is answered or ends.

Web URLs facilitate a software routing solution that is easy to implement, requiring no additional telephony resources, and does not complicate your phone system.

Access and Existing Web URLs

Web URLs work on incoming calls from external phone numbers. Internal and outbound calls are not relevant, with the exception of the Recent Agent Callback predefined Web URL which does support outbound calls.

The Web URL page is accessed from the side navigation menu under Voice Features>Web URLs.

Existing Web URLs are listed by Name, Description (optional), and Type ("Custom" or one of the five predefined Web URLs). The Name and Type columns can be sorted in ascending, descending, or creation order. Clicking on the Starred column will add a Web URL to the home page Starred Features panel for fast access.

You can delete Web URLs by checking them and clicking , but be aware that this cannot be undone.

Web URL Settings

View a Web URL settings by selecting it and expanding its General Settings toggle.

The settings displayed will vary depending on whether the Web URL is custom or predefined and on the type of predefined URL. You can modify any setting except the type of web URL. To change the type of Web URL, you have to delete it and add a new Web URL.

The arrow buttons let you select the next or previous Web URL without having to go back to the main page.

Implementing Web URLs in the Admin Center

You can use Web URLs with any Admin Center feature that allows call forwarding and routing, like IVRs, extensions, schedules, phone numbers, call queues (for exiting the queue), etc.

Simply select Ask web URL as the Destination Type and select the Web URL you want to use as the Destination.

The Web URL will be triggered by the routing or forwarding function of the feature. For example, as shown in the figure, the Web URL for "Callback general" is triggered by a caller dialing 4 when reaching the IVR menu.

For a custom Web URL, the system will route the call based on the response from the external server. For a predefined Web URL, the system will route the call automatically to a predefined destination.

Adding new Web URLs

You can add a new URL by clicking ADD WEB URL and selecting a Custom or Predefined URL:

Custom Web URLs: These allow for flexible call routing by consulting an external web address. Custom Web URLs can also provide a notification to another URL address when a call is answered or ends.
Predefined Web URLs: These are easier and faster to set up as they don't require an external server. Routing does not depend on any response parameters, and calls are routed instantly to a predefined destination. Additionally, they also offer automation of agent notifications, SMS replies, and other system functions.

You can also add a new custom Web URL from the Voice Features Quick menu.

Predefined Web URLs

The Predefined Type drop-down list (discussed in the next section) offers five types of predefined Web URLs, each with a different function and different settings. Calls will be routed after the predefined function is performed.

All predefined Web URLs share the following settings:

Name/Description: The name and description Web URL. The description is optional, but it can help other users understand the function of the Web URL.
Route to: Select where the call will be routed to. If applicable, also provide the Route Destination. For example, if you select to route to an extension, you need to provide the extension number.

Routing for predefined web URLs is automatic and instant. It does not require any parameters or a response from a server.
On fallback, route to: This is displayed only for the Recent Agent Callback option (see next).

Types of Predefined Web URLs

The Agent SMS Notification and Agent Email Notification can work even when callers have a blocked (anonymous) caller ID. For the other three types, if callers have a blocked caller ID, no function will be performed and the call will just be routed.

Recent Agent Callback

This Web URL tries to connect the caller to an agent they recently spoke with or had a missed call from. Unlike the other predefined Web URLs, routing is not automatic and depends on the system finding a recent call match and a couple of other parameters.

Callback Window: Select a time range, from 1 to 48 hours, for the system to look for recent call matches to agents. Outside of this range, callers will not be connected to agents even if there is a recent call match.
Missed Outgoing Calls Only: The default choice of No will connect a caller to an agent for all recent interactions, including incoming answered calls from the caller, answered outgoing calls from the agent, or missed calls from either party.

Select Yes to have the system connect the caller only for missed outgoing calls from the agent. In other words, only when the agent tried and failed to reach the caller, but not vice versa.
Action type:
- Connect to agent will connect the caller to the agent when the system finds a recent call match.
- Route to different destination will connect the caller to an IVR menu or Extension when the system finds a recent call match. This allows you to have other agents or departments handle the call.
  
  If you want to give callers a choice, you can set up two Web URLs – one to connect to the agent and another to connect to a different destination. Then use an IVR menu that prompt callers to make a selection between the two.
On fallback, route to: If the system cannot find a recent call match, it will route the call to the destination you select here.

Trigger SMS Auto Reply

This Web URL replies to callers with an SMS/MMS message using the Auto Reply feature, taking the text, attachments, and delivery phone number from the auto reply.

Any scheduling for the auto reply is ignored and the message is instantly sent by the Web URL. The message is sent even if the auto reply is disabled.

Auto Reply: Select the auto reply to use for the Web URL. Auto replies can be created or configured by navigating to SMS Features>Auto Replies.

Agent SMS Notification

This Web URL sends a missed call SMS notification to an agent, saying "Agent message: You have a missed call from {caller name or number} on {date and time}".

SMS Sender Number: Select one of the SMS-enabled phone numbers in the drop-down list to deliver the notification from. You can make phone numbers SMS-enabled from their general settings (for Web URL usage, you do not need to select any SMS users).
Agent Phone Number: Enter the phone number of the agent who will receive the notification.

Agent Email Notification

This Web URL sends a missed call email notification to an agent, saying "You have a missed call from {caller name or number} on {date and time}". The notification will be delivered from "noreply@telebroad.com" and you should have the agent add it to his email contacts to reduce the likelihood of it being marked as spam.

Agent Email: Enter the email of the agent who will receive the notification.

Add to SMS Campaign

This Web URL adds the caller's phone number to the SMS Campaigns Contacts page.

You need to make sure you inform callers that they are being added to an SMS campaign and obtain their consent to do so. Please review the CTIA Messaging Principles and Best Practices article for suggestions in this regard, and please contact us if you need help with setting up a mechanism for obtaining campaign registration consents.

Contact Tag: Select the tag category on the Contacts page to which the callers will be added to.

Custom Web URLs

Custom Web URLs require configuration of Admin Center settings and an external server that can handle POST API requests. The external server should be configured first since you need the full Web URL address from it.

External Web URL Server Configuration

The system will communicate with the external server using an HTTP POST request, passing the Input Fields detailed below.

You need to configure the external server to process these fields and dynamically generate a text response using a CGI script or similar server-side processing technology. The response has to be encoded as plain text (content type: "text/plain").

The response has to include the Output Fields detailed below that specify a routing destination and (optionally) URLs to be invoked when the call is answered or ends.

Note that calls are tracked in segments as they get routed through the phone system (referred to as the call flow). The response, therefore, may have identification fields relating to the entire call or to one call segment. The answer and hangup URLs may be invoked multiple times if there are multiple segments.

Input Fields

scustomer: A custom ID assigned by the system to the source customer (caller). This is sent just for legacy purposes and can be ignored.
stype: The type of source point, where the call originated or was routed from. The value is "external" for an inbound call from an outside source or "phone" for a user's phone line. It can also be any system points or features – "ivr", "accessmenu, "queue", "extension", "huntgroup", etc.
snumber: The phone number of the source point, where the call originated or was routed from. Depending on the direction of the call, this can be either an internal line or a full telephone number.
ctype: The type of called point, where the source customer (caller) dialed to or where the preceding call segment routed the call to. Ctype examples can be – "ivr", "phone", "huntgroup", "voicemailbox", or "external" for outbound calls.
cnumber: The phone number of the called point, where the source customer (caller) dialed to or where the preceding call segment routed the call to.
dcustomer: A custom ID given to the destination customer (recipient) or the next destination segment in the call flow. This is sent just for legacy purposes and can be ignored.
dtype: The type of destination point (where the call was routed to) that sent the call to the URL. For example "ivr", if the call was sent to the URL when the caller pressed a key on an IVR selection menu.
dnumber: The number of the destination point (where the call was routed to) that sent the call to the URL. For dtypes, such as IVR, that do not have a phone number, this will be their system ID instead.
server: A numerical ID or a hostname for the Telebroad server invoking the URL request.
callid: An identifier for the call itself, including all its segments, created by combining its start time, direction, and other values. Segments of the same call will have the same callid but may have different uniqueids.
uniqueid: An identifier for the call segment, within a call. It is created by combining its start time, direction, and other values. The first uniqueid in a call flow is almost always identical to the callid because they have the same values.
state: The status of the call or segment. URLs invoked at the start of the call will be passed as "ring" or "answer". URLs at the end of the call will be passed as "hangup".
patternmenu_digits: The digits registered by the system if the call passed through a pattern menu that collected DTMF digits from the caller.

In addition, the following fields will be passed on hang-up:

totaltime: The total time, in seconds, for the call since it was initiated, including ringing. For calls that were not answered, this will be 0.
talktime: The talk time, in seconds, for the call since it was answered, excluding ringing.
status: The status of the call. Possible responses include "answer", "noanswer" (by the recipient), "cancel" (by the caller), "congestion" (too much traffic preventing a connection), "busy" (the recipient is on another call), or "chanunavail" – the destination communication channel is unavailable or the requested peer is not registered. Other values indicating routing errors are also possible.
recording: A "true" or "false" value indicating if a recording of the call or segment took place and was saved on the system.

Output fields

The document may be formatted with lines terminated by newline sequence("\n") or carriage return followed by newline ("\r\n"). Don't forget to add any HTTP headers required by your web server, such as "Content-Type: text/plain\r\n\r\n".

The returned output depends on the value of the state field. For the answer and hangup URLs ("answer" or "hangup" values), the text is ignored and an empty document (apart from any required HTTP headers) should be returned.

For a routing URL at the start of the call ("ring" value), the following fields should be returned:

dtype: The destination type to send the call to.
dnumber: The destination number to send the call to.
answer_url (optional): A URL to invoke after the call has been answered. This field overrides the setting specified in the Admin Center settings of the Web URL.
hangup_url (optional): A URL to invoke after the call has hung up. This field overrides the setting specified in the Admin Center settings of the Web URL.

Sample document:

dtype: phone

dnumber: 1234567

answer_url: http://example.com/answer.cgi

hangup_url: http://example.com/hangup.cgi

Admin Center Configuration

When adding a new custom Web URL, enter the following and click Create:

Name/Description: The name and description Web URL. Description is optional, but it can help other users understand the function of the Web URL.
URL to ask how to route call: Provide the external Web URL server address that you configured to advise the system about where to route the call to.
URL to inform on answer (optional): A URL that the system informs when the call has been answered.
URL to inform on hangup (optional): A URL that the system informs when the call has been hung up.
Timeout waiting for web server: If the request exceeds the timeout value provided here (5 seconds by default), including time for DNS lookup, it will be cancelled and the call will be routed to the timeout destination.
On timeout or error, route to: The destination to route the call when the Web URL routing fails due to timeout or error.

Articles in this folder