Connect the bot to any backend system

1. Create the Custom API tool

Name: OpenStreetMap office finder Description: Finds the company office nearest to a visitor’s stated location using OpenStreetMap geocoding and routing.

2. Add a credential

Add the following credential:

api_key = YourCompany Office Finder (support@yourcompany.com)

This value is used as the User-Agent for OpenStreetMap requests. Use a clear application name and contact address.

3. Add office locations to the knowledge base

Create or upload a source containing each office’s: - Name - Full address - Latitude - Longitude - Optional information, such as opening hours or a service note Example:

[
  {
    "name": "Helsinki Office",
    "address": "Example Street 1, 00100 Helsinki",
    "lat": 60.1699,
    "lon": 24.9384,
    "info": "Open weekdays 09:00–17:00"
  }
]

4. Create the function

Function name: find_nearest_office Description: Find up to three of the company’s offices nearest to a visitor’s stated location. Call only after the visitor has provided a postcode and city, street address, landmark, or district and city. Use this parameter schema:

{
  "type": "object",
  "properties": {
    "location_text": {
      "type": "string",
      "description": "The visitor's stated location. Never guess it."
    },
    "locations": {
      "type": "array",
      "description": "The company's office locations. Retrieve these from the knowledge base; never ask the visitor for them.",
      "items": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "address": { "type": "string" },
          "lat": { "type": "number" },
          "lon": { "type": "number" },
          "info": { "type": "string" }
        },
        "required": ["name", "address", "lat", "lon"]
      }
    }
  },
  "required": ["location_text"]
}

Configure locations to be populated from the knowledge base. The function should receive office locations automatically, rather than asking the visitor to choose from a list.

5. Add the function code

Use the configured implementation, changing country_hint if your business operates primarily outside Finland:

location_text = arguments[:location_text].to_s.strip
user_agent = credentials[:api_key].to_s.strip
country_hint = "Finland"

offices = (arguments[:locations] || []).take(20)

usable_offices = offices.select do |office|
  office["name"].present? &&
    office["lat"].present? &&
    office["lon"].present? &&
    office["address"].present?
end

if location_text.blank?
  success_response({
    "status" => "location_needed",
    "message" => "Ask the visitor for a postcode and city, street address, landmark, or district and city."
  })
elsif user_agent.blank?
  failure_response("Office finder User-Agent is missing")
elsif usable_offices.empty?
  success_response({
    "status" => "office_locations_unavailable",
    "message" => "No office locations with coordinates were available from the knowledge base."
  })
else
  query = "#{location_text}, #{country_hint}"

  geocode_response = make_api_call(
    "https://nominatim.openstreetmap.org/search",
    { "q" => query, "format" => "jsonv2", "limit" => 1, "addressdetails" => 0 },
    :get,
    { "User-Agent" => user_agent, "Accept-Language" => "en" },
    false
  )

  unless api_call_succeeded?(geocode_response)
    geocode_response
  else
    matches = geocode_response[:result] || []

    if matches.empty?
      success_response({
        "status" => "location_not_found",
        "message" => "Ask the visitor for a more precise street address or nearby landmark and city."
      })
    else
      origin = matches.first
      origin_lat = origin["lat"].to_f
      origin_lon = origin["lon"].to_f

      coordinates = usable_offices.map { |office| "#{office["lon"]},#{office["lat"]}" }.join(";")

      route_response = make_api_call(
        "https://router.project-osrm.org/table/v1/driving/#{origin_lon},#{origin_lat};#{coordinates}",
        { "annotations" => "distance,duration" },
        :get,
        {},
        false
      )

      unless api_call_succeeded?(route_response)
        route_response
      else
        data = route_response[:result] || {}
        distances = (data["distances"] || []).first || []
        durations = (data["durations"] || []).first || []

        results = usable_offices.each_with_index.filter_map do |office, index|
          distance = distances[index + 1]
          duration = durations[index + 1]
          next unless distance.present? && duration.present?

          {
            "name" => office["name"],
            "address" => office["address"],
            "info" => office["info"],
            "driving_distance_km" => format("%.1f", distance.to_f / 1000),
            "driving_duration_minutes" => (duration.to_f / 60).to_i,
            "maps_url" => "https://www.openstreetmap.org/directions?engine=fossgis_osrm_car&route=#{origin_lat}%2C#{origin_lon}%3B#{office["lat"]}%2C#{office["lon"]}"
          }
        end.sort_by { |office| office["driving_distance_km"].to_f }.take(3)

        success_response({
          "status" => "ok",
          "offices" => results,
          "attribution" => "© OpenStreetMap contributors",
          "attribution_url" => "https://www.openstreetmap.org/copyright"
        })
      end
    end
  end
end

6. Create the role or intent

Name: Find nearest office Description: The visitor asks which company office, branch, store, or service point is nearest to them. Instructions: Ask for the visitor’s postcode and city, street address, landmark, or district and city if they have not provided one. Never infer their location. Call find_nearest_office as soon as a usable location is available. Present offices nearest first, including name, address, driving distance, estimated driving time, available opening-hours information, and the map link. Do not repeat the visitor’s home address. Include this attribution: © OpenStreetMap contributors If the location cannot be found, ask for a more precise address or nearby landmark. If office data is unavailable or the tool fails, explain that the nearest office cannot currently be determined: never guess.