DataSource Reference

The DataSource feature allows you to setup a simple Web API that returns JSON data. There are two types of DataSource APIs:

  • KnowledgeBase — useful for FAQs, help content, and product catalogs
  • GeoSearch — useful for store locators

For complete tutorials see:

Setting Up Your Google Sheet

Data for your API is stored in a Google Sheet. You can include as many columns as you like, and pull data from those columns into your results. But you can only search by particular column names.

KnowledgeBase Column Names

The contents of the following columns are indexed for returning relevant results to user queries.

  • id — a unique numeric id
  • title — the main content for search queries
  • alternates — comma-delimited list of alternate titles
  • summary — a short response, usually less than 200 characters (< 80 if you want to use it as a subtitle in a structured tile)
  • detail — a longer response, but still no more than 320 characters (If you don’t plan on displaying it to the user in a chat window, you can place longer content here for indexing, to improve relevancy.)
  • tags — a comma-delimited list of relevant keywords

Title and Alternates together act like Seed Sentences in an Intent. It is often helpful for Titles and Alternates to be phrased as questions that a user might ask.

Other columns are not indexed for search results, but can be returned in the KB API:

  • content_url
  • image_url
  • audio_url
  • video_url

GeoSearch Column Names

  • id
  • locationName
  • locationType
  • country
  • address1
  • address2
  • address3
  • address4
  • city
  • stateProvince
  • zipPostalCode
  • contactPhone
  • contactFax
  • email
  • url
  • facebookPageId
  • internationalAddress

Special Tags

Google Sheets for both KnowledgeBase and GeoSearch datasets can hold arbitrary boolean data about each record in columns labelled with (tag) after the column name. Mark an X where the condition is true for each record.

../_images/special-tags-columns.png

Setting Up the DataSource API

For both the GeoSearch and KnowledgeBase DataSources, all you really need to do in the setup screen is give the DataSource a title, select a type, and paste in a link to a Google Sheet. Make sure the sharing setting for the Google Sheet is “Anyone with Link Can View.”

There are some URLs in Search by fields. You can ignore most of it, but you need the source string.

../_images/search-by-url-with-comment.png

Calling the DataSource API from a Web Responder

In the Web Responder setup:

  • Webhook URL the determines which kind of search you are doing (see below)

  • Parameters

    • Key source

KnowledgeBase — Search by Phrase

  • Webhook http://dataservice.botcentralapi.com/knowledge-0.1/articles/phraseSearch

  • Parameters

    • Key phrases

      • Value query string — To send the most recent user input as the value, use {$query}
    • Key mode

      • Value intents — Tries to match records from the query string using the same Natural Language Processing algorithm that powers the ref:intents feature, based on the content of the Title and Summary columns.
      • Value all — Matches records using a basic string search on all indexed columns.

KnowledgeBase — Search by Special Tags

  • Webhook http://dataservice.botcentralapi.com/knowledge-0.1/articles/specialTagSearch

  • Parameters

    • Key specialTags

      • Value comma-separated list of tags, corresponding to Special Tags defined in your Google Sheet. This is normally done by creating a creating a variable in Embedded Code and calling it with {$botContext.name-of-variable}.
    • Key mode (optional)

      • Value and All returned results will be True for all included tags.
      • If this parameter is not included, the “or” condition (true for at least one tag) is the default.

GeoSearch — Search by City or LatLong

  • Webhook http://dataservice.botcentralapi.com/knowledge-0.1/storeLocator

  • Parameters

    • To Search by City:

      • Key city | Value city (if using a location context, {$location.city})
    • To Search by LatLong:

      • Key city | Value latlong (if using a location context, {$location.latlng})
    • Key radius | Value number — radius in miles

    • Key specialtags (optional)

      • Value comma-separated list of tags, corresponding to Special Tags defined in your Google Sheet. This is normally done by creating a creating a variable in Embedded Code and calling it with {$botContext.name-of-variable}.
    • Key mode (optional)

      • Value and All returned results will be True for all included tags.
      • If this parameter is not included, the “or” condition (true for at least one tag) is the default.

Handling Results

Iterable KnowledgeBase results are returned as an array, and are accessible through {$.successResult.success[i], which has the following dot-accessible properties:

  • id
  • tags
  • title
  • summary
  • alternatives (an array)
  • detail
  • contentURL
  • imageURL
  • audioURL
  • videoURL
  • createdBy
  • source
  • score
  • specialTags (an array)
../_images/kb-structured-tile-example.png

Iterable GeoSearch results are returned as an array, and are accessible through $.successResult.storeLocations[i], which has the following dot-accessible properties:

  • id
  • active
  • locationName
  • locationType
  • url
  • address1
  • address2
  • address3
  • address4
  • city
  • stateProvince
  • zipPostalCode
  • country
  • internationalAddress
  • contactPhone
  • contactFax
  • facebookPageID
  • location.lat
  • location.lon
  • source
  • specialTags (an array)
../_images/geo-structured-tile-example.png