Traveler Assistant

An intelligent conversational assistant that helps users discover both restaurants and a wide variety of other places (such as parks, hotels, shopping malls, markets, cultural centers, etc.) with Qloo

Comment

Traveler Assistant

An intelligent conversational assistant that helps users discover both restaurants and a wide variety of other places (such as parks, hotels, shopping malls, markets, cultural centers, etc.) based on specific criteria like location, type, amenities, and preferences. The assistant uses the Qloo API to provide accurate, real-time information across multiple communication channels.

You can use it with Telegram: https://t.me/travelerassist_bot

This demo is in a free hosting, so maybe the first time you ask any request for the bot, it lasts more than the rest of the queries (maybe 1 minute you need to wait after your first message, after that, just a couple of seconds).

🍽️🗺️ What This Assistant Does

This assistant specializes in:

  • Restaurant discovery with advanced filtering capabilities.
  • Discovery of other places of interest (parks, hotels, shopping malls, markets, cultural centers, etc.) with flexible filters.
  • Remembering your preferences and previous queries thanks to its conversation memory, so you don't have to repeat information in long or multi-turn conversations.

It understands natural language queries and can filter results by a wide range of criteria.

🏙️ Examples of Searches

Restaurant Searches

  • "Restaurants in Providencia"
  • "What restaurants are there in Las Condes?"
  • "Places to eat in downtown Santiago"

🍕 Cuisine Types

  • "Italian restaurants in Vitacura"
  • "Mexican food in Ñuñoa"
  • "Where is Chinese food in Santiago"

🐾 Pet-Friendly Options

  • "Pet-friendly places in Providencia"
  • "Restaurants that accept dogs in Las Condes"
  • "Places to go with pets in Vitacura"

👨‍👩‍👧‍👦 Family-Friendly Features

  • "Restaurants with children's menu in La Reina"
  • "Places with games for children in Lo Barnechea"
  • "Family-friendly places in Providencia"

🌱 Dietary Preferences

  • "Vegan restaurants in Santiago"
  • "Vegetarian options in Las Condes"
  • "Gluten-free food in Providencia"

🚗 Services & Amenities

  • "Free parking restaurants in Vitacura"
  • "Delivery places in Ñuñoa"
  • "Restaurants with bar in Providencia"
  • "Places that accept cards in Santiago"

☕ Meal Types

  • "Where to have breakfast in Las Condes"
  • "Places to have lunch in Providencia"
  • "Restaurants for dinner in Vitacura"
  • "Where to have brunch on Sunday in Santiago"
  • "Places to have once in Ñuñoa"

🏢 Other Places (get_places)

🛍️ Shopping & Markets

  • "Shopping malls with free parking in Las Condes"
  • "Markets with restrooms in Vitacura"
  • "Shops with wifi in Santiago"
  • "Tourist shopping centers in Providencia"

🌳 Parks & Outdoor

  • "Parks with playgrounds for kids in Ñuñoa"
  • "Dog parks in Lo Barnechea"
  • "Smoke-free parks with free admission in Las Condes"
  • "Parks with restrooms and coffee in Providencia"

🏨 Hotels

  • "Hotels that are smoke-free in Providencia"
  • "Hotels with wifi and free parking in Santiago"
  • "Hotels that accept credit card in Ñuñoa"

🏛️ Cultural & Tourist

  • "Cultural centers with free admission in Santiago"
  • "Tourist attractions with restrooms in Vitacura"
  • "Cultural centers with coffee and wifi in Las Condes"

🚻 Amenities & Filters

  • "Places with restrooms and free admission in Providencia"
  • "Dog parks with playgrounds for kids in Ñuñoa"
  • "Markets with coffee and free parking in Vitacura"
  • "Shopping malls that accept credit card and have wifi in Santiago"
  • "Tourist places with alcohol in Las Condes"
  • "Hotels with playgrounds for kids and smoke-free in Lo Barnechea"
  • "Cultural centers with parking, coffee, and restrooms in Santiago"
  • "Restaurants that accept dogs in Las Condes"
  • "Places to go with pets in Vitacura"

👨‍👩‍👧‍👦 Family-Friendly Features

  • "Restaurants with children's menu in La Reina"
  • "Places with games for children in Lo Barnechea"
  • "Family-friendly places in Providencia"

🌱 Dietary Preferences

  • "Vegan restaurants in Santiago"
  • "Vegetarian options in Las Condes"
  • "Gluten-free food in Providencia"

🚗 Services & Amenities

  • "Free parking restaurants in Vitacura"
  • "Delivery places in Ñuñoa"
  • "Restaurants with bar in Providencia"
  • "Places that accept cards in Santiago"

☕ Meal Types

  • "Where to have breakfast in Las Condes"
  • "Places to have lunch in Providencia"
  • "Restaurants for dinner in Vitacura"
  • "Where to have brunch on Sunday in Santiago"
  • "Places to have once in Ñuñoa"

Why is This App Necessary?

Travelers and residents alike often face difficulties when searching for reliable, up-to-date information about places to visit, dine, or explore in a specific city. Traditional travel guides quickly become outdated, and searching through various websites or apps can be time-consuming and overwhelming. There is a clear need for an accessible, real-time solution that delivers trustworthy recommendations directly to users, without requiring them to download yet another app.

What Problem Does It Solve?

This project solves several important challenges:

  • Information Accessibility: Many visitors and locals struggle to find accurate, current details about local attractions, restaurants, and points of interest.
  • Overwhelming Choices: With so much information scattered across the internet, users often feel lost or unsure which sources to trust.
  • Language and Usability Barriers: Tourists may not be familiar with local apps or may face language barriers when trying to access information.
  • App Fatigue: Users are reluctant to install new applications for every city they visit or every need they have.

Benefits of Using Telegram and WhatsApp Instead of Creating a New App

  1. Lower Adoption Barrier Users do not need to install or learn a new application. Most people are already familiar with Telegram and WhatsApp, ensuring immediate usability and engagement.
  2. Broad User Base Telegram and WhatsApp have billions of active users worldwide. Leveraging these platforms allows the solution to reach a much larger audience without additional marketing or onboarding efforts.
  3. Enhanced Trust and Security Users trust established platforms with their data and privacy. Both Telegram and WhatsApp offer robust security features, including end-to-end encryption.
  4. Seamless Integration Bots and integrations can deliver notifications, reminders, and interactive features directly within users’ existing chat groups. No need for users to switch contexts or manage multiple apps for different purposes.
  5. Cost and Time Efficiency Developing a new app from scratch requires significant resources for design, development, testing, deployment, and maintenance. Building on top of existing platforms accelerates time-to-market and reduces costs.
  6. Higher Engagement Users are more likely to interact with tools and notifications in platforms they already use daily. Reduces the risk of users ignoring or missing important updates.
  7. Cross-Platform Compatibility Telegram and WhatsApp are available on all major devices and operating systems, ensuring accessibility for all users.

Configuration and channels

  • Multi-channel integration: Twilio (WhatsApp/SMS), WhatsApp Business API (WABA), and Telegram
  • Dedicated webhook for Telegram (/webhook/telegram) and a single extensible webhook for other channels
  • SQLite database for local development
  • SQL Server or Supabase database for production
  • Dynamic and extensible tools system (executed in backend)
  • Flexible model and endpoint (baseURL) configuration

📋 Prerequisites

  • Node.js (v14 or higher)
  • npm or yarn
  • An OpenAI account or compatible API service
  • A Twilio account (for messaging integration)
  • A WhatsApp Business API (Meta) account (optional)
  • A Telegram account and a bot created with @BotFather (optional)
  • SQL Server or Supabase (production only)

🛠️ Installation

  1. Clone the repository:

    git clone [repo-url]
cd agent

  2. Install dependencies:

    npm install

  3. Create a .env file in the project root.

📱 Supported Messaging Channels

Telegram

  • Create a bot with @BotFather and obtain the token.
  • Add the token as TELEGRAM_BOT_TOKEN in your .env.
  • Expose your server to the internet (e.g., using ngrok) and configure the Telegram webhook pointing to:

https://<your-domain>/webhook/telegram

  • The Telegram channel supports text messages and displays detailed restaurant responses, just like WhatsApp and Twilio.

Twilio (WhatsApp/SMS)

  • Configure your Twilio credentials and number in the .env.
  • Point the Twilio webhook to /assistant.

WhatsApp Business API (WABA)

  • Configure your WABA credentials and number in the .env.
  • Point the WABA webhook to /assistant.

🧠 Assistant Behavior

  • The assistant analyzes each message and, if applicable, executes the get_restaurant tool using structured tool-calling.
  • Tool responses now display all details of each restaurant: name, status (open/closed), address, phone, web, and cuisine type.
  • If no restaurants are found, the assistant explicitly indicates this.
  • The prompt forces displaying the information as returned by the tool, without summarizing or paraphrasing.
  • Supports natural language queries about city, food type, filters (vegan, children's menu, pets, etc.), services (delivery, bar, parking, etc.), and meal types (breakfast, brunch, etc.).

📝 Example Detailed Response

1. Boragó
   Estado: Abierto
   Dirección: Av. Nueva Costanera 3467, Vitacura
   Teléfono: +56 2 2953 8893
   Web: https://www.borago.cl
   Tipo de cocina: Contemporánea, Chilena

2. La Mar
   Estado: Abierto
   Dirección: Av. Nueva Costanera 4076, Vitacura
   Teléfono: +56 2 2218 0100
   Web: https://www.lamarcebicheria.cl
   Tipo de cocina: Peruana, Mariscos

⚙️ Environment Variables (.env)

Make sure to define in your .env:

  • QLOO_ENDPOINT, QLOO_API_KEY
  • OPENAI_API_KEY, OPENAI_MODEL
  • TELEGRAM_BOT_TOKEN
  • (Optional) Twilio and WABA credentials
  • DB_TYPE, SUPABASE_URL, SUPABASE_KEY or SQL Server

🚀 Available Commands

  • npm run setup-db: Setup the database (generic tables)
  • npm run setup-client-db: Setup the database with client tables (run after setup-db)
  • npm run start-api: Start the API server (development mode)
  • npm run compile: Compile TypeScript code
  • npm start: Start in a production mode (after compilation)

🌐 Multi-Channel Support & Single Webhook

  • The /assistant endpoint accepts messages from Twilio and native WhatsApp Business API (and is extensible to more channels).
  • The system automatically detects the source channel, normalizes the message, and responds using the appropriate format:
    • Twilio: Responds with XML (TwiML) using ResponseHandler.
    • WABA: Sends the response using Meta's API.
  • To add more channels, just create a file in channels/ and update the dispatcher.

📝 API Usage & Webhook

Main Endpoint

POST /assistant
Content-Type: application/json or application/x-www-form-urlencoded

// Twilio:
Body=user_message&From=phone_number

// WhatsApp Business API:
{
  "messages": [
    { "from": "phone_number", "text": { "body": "user_message" }, ... }
  ]
}

Identification and message storage flow

  • The backend identifies each user by the combination of provider and external_id.
  • If the identity does not exist, a new global user and identity are created.
  • All messages are associated with the user-provider identity, allowing unified conversations even if the user switches channels.

Example Response

  • Twilio: XML (TwiML)
  • WABA: Message sent via Meta API
  • Other channels: Adaptable

🔄 Extensibility

Adding New Channels

  1. Create a new file in the channels/ folder (e.g., telegram.ts)
  2. Implement the parser and sender for that channel
  3. Add the CHANNEL_TYPE property to specify the name of the channel to register in the database for conversations (for example WABA and Twilio are registered as whatsapp)
  4. Register it in the channel dispatcher

Adding New Tools

  1. Create a new file in the tools/ folder (generic tools, available for all instances)
  2. Or create a file in clientConfig/tools/ (client-specific tools)
  3. Register the tool in the corresponding file (tools/allGeneralTools.ts for generic, or in the export of clientConfig/allTools.ts for specific)
  4. In the final export of clientConfig/allTools.ts, combine both:
import { tools as generalTools } from "../tools/allGeneralTools";
import { getStatusTool } from "./tools/getStatus";

export const tools = {
  ...generalTools,
  get_status: getStatusTool,
  // ...other client-specific tools
};
  • Client-specific tools can overwrite generic ones if they have the same name.
  • This way, each instance can have its own tools and the generic ones will always be available.

Recommendation: Every new tool should consider a parameter called externalId to receive the user's identifier. This allows for multi-channel identification and proper traceability of user actions.

Built With

Share this project:

Updates