Build location routing with VoiceML.

What callers get

• The nearest restaurant

  Callers from New Mexico reach Albuquerque, callers from Arizona reach Phoenix, and callers from El Paso reach El Paso, with no menu.

• A menu as a fallback

  Any other caller hears the list of restaurants and presses a key.

• One number for every restaurant

  Each restaurant’s own number lives in the document, so the chain advertises a single number.

Before you start

1. A VoiceML account with a phone number. See VoiceML or start a free trial.
2. Each location’s phone number, and the area codes that should reach it.

Step 1: Publish the document and point the number at it

Replace the locations, area codes, and numbers with your own. Then publish it at voiceml.org and set the /r/ URL it returns as the phone number’s voice URL. Keep the URL exactly as returned, key included, and don’t post it publicly.

main.xml

<Response>
  {% comment %} From is E.164: +1 and then the area code, for North American numbers. {% endcomment %}
  {% assign country = From | slice: 0, 2 %}
  {% assign area = From | slice: 2, 3 %}
  {% if country != "+1" %}{% assign area = "" %}{% endif %}

  {% comment %} A key pressed in the menu below takes priority over the area code. {% endcomment %}
  {% case Digits %}
    {% when "1" %}{% assign area = "505" %}
    {% when "2" %}{% assign area = "602" %}
    {% when "3" %}{% assign area = "915" %}
  {% endcase %}

  {% case area %}
    {% when "505", "575" %}
      {% assign store = "Albuquerque" %}
      {% assign line = "+15055550101" %}
    {% when "480", "520", "602", "623", "928" %}
      {% assign store = "Phoenix" %}
      {% assign line = "+16025550101" %}
    {% when "915" %}
      {% assign store = "El Paso" %}
      {% assign line = "+19155550101" %}
  {% endcase %}

  {% if store %}
    <Say>Thank you for calling Los Pollos Hermanos, the chicken brothers. Connecting you to our {{ store }} restaurant.</Say>
    <Dial timeout="25" ringTone="us">
      <Number>{{ line }}</Number>
    </Dial>
    <Say>Thank you for calling Los Pollos Hermanos. Goodbye.</Say>
    <Hangup/>

  {% else %}
    <!-- No match: let the caller choose. With no action, the key comes back to this document. -->
    <Gather input="dtmf" numDigits="1" timeout="5" method="POST">
      <Say>Thank you for calling Los Pollos Hermanos, the chicken brothers.</Say>
      <Say>For Albuquerque, press 1. For Phoenix, press 2. For El Paso, press 3.</Say>
    </Gather>
    <Say>We did not receive a selection. Goodbye.</Say>
    <Hangup/>
  {% endif %}
</Response>

Step 2: Test it

Call from a phone whose area code is on your list, and that location rings without a menu. Call from any other phone, and you hear the menu; press a key, and that location rings.

How the routing works

From is the caller’s number in E.164, such as +15055551234. For North American numbers, the first two characters are +1 and the next three are the area code, so two slice filters split it:

A {% case %} on the area code sets the restaurant’s name and number, and <Number>{{ line }}</Number> dials it. Several area codes can share a restaurant in one when, as Arizona’s five do for Phoenix.

When nothing matches, the menu’s <Gather> has no action, so the key comes back to the same document as Digits. A {% case Digits %} near the top replaces the area code with the chosen restaurant’s, and the same routing runs again.

Where the show turns up

Limits of this design

• An area code isn’t a location. Mobile numbers keep their area code when people move, so a caller from Phoenix with an Albuquerque number reaches Albuquerque.
• No city or state from the network. The VoiceML runtime sends FromCity, FromState, and the other location fields empty, so the area code is the only clue in the call.
• The list is fixed in the document. A new location or area code means publishing again and pointing the number at the new URL.
• Closed restaurants still ring. To skip a location outside its hours, combine this with the checks in the business-hours example.

Credits

• Los Pollos Hermanos comes from Breaking Bad (AMC, 2008–2013), created by Vince Gilligan. Bryan Cranston plays Walter White, and Giancarlo Esposito plays Gus Fring, the owner of the chain, which has 14 restaurants across the Southwest in the show.
• The Phoenix and El Paso restaurants, the area-code assignments, and the phone numbers are fictional in this example. VoiceTel is not affiliated with the show or its rights holders.
• References: the voiceml.org publishing and integration guide, whose Liquid cookbook routes by area code, and the VoiceML language reference.