Technical Success Manager
Nicholas AhrendtCombining AI telecommunication services with powerful geolocation data opens new possibilities for spatially aware travel applications, parcel tracking, and fleet management. This installment of SignalWire in Seconds places our AI agent into a wayfinding context, using a Node.js webserver to establish integrations with SignalWire’s phone number lookup REST API endpoint and the Google Maps Platform.
We'll cover the capabilities of a Call Flow Builder IVR equipped with location-based routing, as well as the major components of a SignalWire Markup Language (SWML) script designed to enable Carmen, an AI travel guide, to deliver personalized driving directions over the phone and via SMS.
This application consists of RESTful endpoints at each stage of the process for an uninterrupted data flow between APIs, our IVR, and our AI agent. The code samples are only a portion of the complete application: for the full code, view the official Github repository.
Contextual IVR routing with Call Flow Builder
We’ll begin by employing SignalWire’s phone number lookup REST API endpoint to determine the inbound caller's general location (based on the origin of their phone number).
Call Flow Builder helps developers navigate the complex intersection of telecommunication and geolocation, whether you’re charting a course for travel guides or emergency dispatch services to create a spatially-aware IVR using an intuitive drag-and-drop interface.
The Request node
The Request node is your avenue to accessing external data in your call flows. With support for HTTP methods like GET and POST, this node allows you to make requests to public URLs and use the response data during subsequent instructions.
Expanding base functionality with SWML expressions, such as ${call.from} and ${request_response_code}, the Request node allows developers to create complex workflows with little additional coding.
Phone number lookups
The call flow for this wayfinding application starts with a link to the first endpoint built for our Node.js server, `/start_pnl`. There, we’ll leverage SignalWire’s REST API to execute a phone number lookup of the inbound caller.
When a call enters our IVR, the inbound phone number is automatically passed from the IVR to the server using a custom header. The logic contained in the endpoint then normalizes the phone number format for the lookup and generates a query responsible for retrieving details like the caller’s city and state.
This data is logged to the console for real-time monitoring, and returned to the Call Flow Builder as a JSON response, informing downstream components of the caller's geographic context.
The Conditions node
Acting like a JavaScript `if...else` statement, the Conditions node provides call flows with multiple routing scenarios. In this scenario, routing based on the origin state retrieved from the PNL furthers our concept of a travel agency.
Evaluating logical expressions, such as `${vars.request_response.carrierState === 'WY'}`, sends callers from Wyoming (WY) down a custom path, while defaulting to an "else" path for calls from other states. This workflow flexibility offers a streamlined call experience for users who prefer to reach a specialized agent.
The Execute SWML node
Finally, the Execute SWML node passes the inbound caller to an AI travel guide named Carmen by executing a remote SWML document which hosts her makeup. Critical variables collected earlier in the flow, like `${request_response.carrierState}`, are also transferred from the call flow to the target SWML script.
These variables remain accessible throughout the script’s execution, ensuring that Carmen can provide personalized guidance informed by context associated with the caller’s prior interaction with the IVR.
Designing an AI travel guide using SWML
AI voice agents like Carmen can be integrated into workflows that adapt to the unique needs of each business. Unlike rigid IVRs, AI agents can respond fluidly to individual situations, guiding travelers or tracking parcels through tailor-made telecom experiences.
Iterating on our lightweight server’s REST API integration, Carmen will make use of the Google Maps Platform to identify the caller’s point of interest (POI) and extract their current coordinates, delivering route-optimized driving directions via SMS, lightening the burden of navigation for busy users.
Prompt and conversation topography
Within the context of this wayfinding application, Carmen’s prompt is configured to emphasize her role as a knowledgeable and trustworthy AI travel guide, blending a clear identity with structured, step-by-step instructions.
Functional imperatives and response-reliant decision trees ensure that Carmen maintains an engaging tone while interacting with APIs to retrieve accurate geolocation data and route information. Additional fine-tuning parameters, like `temperature` and `top_p` balance creative dialogue with focused task execution, resulting in an AI agent that parses queries effectively and keeps conversations on topic.
Fetching points of interest and callers’ coordinates
The `fetch_poi` and `locate_caller` functions are key components of Carmen's wayfinding capabilities. These functions are designed to retrieve relevant POI candidates and determine the caller’s exact location based on the caller's input.
Configured as part of SignalWire's AI Gateway (SWAIG), these functions leverage arguments to precisely define the caller’s search. The `parameters` object, with properties such as `fetchPOI_placeName`, `caller_streetName`, serves to narrow the spatial scope of the Google Maps queries. Each parameter is described for clarity, reinforcing the AI’s ability to differentiate between a type of place (e.g., "gas station") and a specific geographic boundary.
SWML functions
Interfacing with our server via a webhook, SWML functions dynamically create query URLs by encoding the caller-provided parameters using the `enc:` prefix. This webhook sends a `GET` request to our similarly named server endpoints, retrieving a candidate POI and caller coordinates, among other details.
The gathered responses are then used to encourage a natural conversation with the caller, and allow Carmen to queue up proceeding functions, like `determine_route`.
Server logic
On our server, the `/fetch_poi` and `/locate_caller` endpoints bridge Carmen's queries with the Google Maps Platform. Designed to align with their SWML functions, these endpoints accept the specified search parameters, which are then converted into acceptable structures for executing Places API and Geocode API requests.
From the APIs’ response data, critical details—such as the POI candidate’s formatted address or the caller’s latitude and longitude—are mapped into a structured JSON response and sent back to Carmen. If no candidates are found, the endpoint supplies an appropriate error message to the AI agent.
Determining the caller’s route and dispatching SMS
Finally, we’ll retrieve driving directions from the caller’s given location to their desired POI using the Google Maps Directions API. With the `dispatch_route` function and the `/determine_route` server endpoint, raw geolocation data is transformed into travel guidance, delivering personalized driving directions via SMS.
The SWML function orchestrates the conversation’s flow of information from the caller to the Node.js server, where the endpoint interfaces with the Directions API to retrieve route details.
SWML Function
The `dispatch_route` function facilitates the process of determining a caller's route and dispatching turn-by-turn driving directions. With the parameters collected in each of the prior functions, a webhook request is made to the last of our server endpoints.
Upon the payload’s return, the webhook response instructs Carmen to provide the caller with a brief vocal summary of the compiled route information, and triggers an SMS action containing the trip’s details.
Server Logic
The `/determine_route` endpoint processes the query transmitted by the AI agent, specifying coordinates representing both the caller and the POI candidate. The endpoint sends a request to the Google Maps Platform—this time aimed at the Directions API.
Following a calculation of the driving route between the caller's location and the POI, the API’s response is parsed to extract course information, like the origin and destination addresses, route distance, and expected travel time.
With SMS character count considerations in mind, turn-by-turn driving instructions are processed further, combining into a single string that enhances user readability and operational efficiency.
