Plum DEV Documentation
routes

Plum Routes

In many applications call transfers are placed to a single phone number or SIP end point. However, if your application needs to place call transfers to multiple phone numbers or multiple SIP end points using dynamic fair load balancing then Plum Routes is the tool you are looking for. Plum Routes is used to create route groups which fairly distribute VoiceXML call transfers across multiple end points. Users have the ability to create multiple route groups as necessary and each route group can contain multiple destinations with specific percent allocations.

Getting Started

To get started you will need to log into Plum Routes:

https://routes.plumvoice.com

If you do not have a login for this tool you can submit a ticket to the Plum Support team to have this feature enabled. If you do not have an active support contract you can reach out to your sales rep to get demo access. Once you are logged in you will see the Route Manager which lists the active route groups on your account. For new users this list will be empty, but you can create your first route group by clicking on “+ Add Group”.

Clicking “+ Add Group” will bring up the form for creating a new route group. On this page you will be able to give your route group a logical name and to provide an initial list of destinations. Clicking on “+ Add Destination” will create additional blank destinations for you to fill in. This is where you can provide a name for your destination, the full destination string (e.g. tel:+1617712300 or sip:1234@10.0.1.2) and define the percent allocation each for destination when this route is used.

After you save the route group you will be taken back to the route manager where you will see the route you created. You can see the list of destinations and their percent allocation. You can easily edit () or delete () any routes you have already created and any changes will only impact future calls that reference the route.

Using a route in VoiceXML

Now that you have created your route group you will want to use it within your VoiceXML applications. Here is some sample VoiceXML that you can use to get started:

<?xml version="1.0"?>
<vxml version="2.1">
  <form>
    <!-- lookup the route we should use for this session -->
    <data name="route" src="$$route_group_url$$" method="post" namelist="session.id" accept="application/json"/>

    <!-- transfer to the route provided while also providing a backup number in the event of a failure -->
    <transfer destexpr="'success' in route && route.success ? route.destination : '16177123000'">
      <prompt>Please wait while you are transferred</prompt>
    </transfer>
    
    <!-- trap disconnect events to report the completion of this session -->
    <catch event="connection.disconnect">
      <data name="route" src="http://routes.local.plumvoice.com/ws/complete" method="post" namelist="session.id" accept="application/json"/>
    </catch>
  </form>
</vxml>

In the code above you will notice a reference to $$route_group_url$$. You will need to replace this with the URL for your route group. You can find the URL in the route manager by right clicking on the link icon () and selecting copy from the context menu in your browser. Your link should look something like this:

http://routes.local.plumvoice.com/ws/route/2/24d2cebbaae24adc9e13e9f85116bd41

This link is unique to your route and you will need to place that in your VoiceXML replacing $$route_group_url$$ in the code sample provided above. The sample code will now automatically load balance any call transfers using the percent allocation you provided when the route group was created. The <data> tag call to http://routes.local.plumvoice.com/ws/complete is not explicitly required but it is a good practice to avoid any delays in updating the list of active sessions on your route which can impact the fairness of your load balancing.

Final Notes

You can go back to the route manager at any time and make changes to your list of destinations and all future calls to the route group URL will automatically use the changes you have saved. Take care when deleting a route group entirely as that can cause transfers that reference that route group to stop functioning. In the sample VoiceXML code above we demonstrated how to use a fallback phone number in the event that there is an issue determining the next destination for your route group. This will safeguard your application in the event that your route group is deleted.

For applications that wish to make multiple attempts in the event of a failure that is fully supported by Plum Routes. You can use the code provided above using a <foreach> tag or with multiple forms where each form uses the <data> tag to fetch a new destination and a <transfer> tag to attempt the transfer.