Raffle Search API (2.0.0)

Top questions can be used to give the end-user the option to choose from a list of popular search queries. The top questions provided by this endpoints are managed in the Raffle Web App.

Note that an API based search solution doesn't have to provide top questions, and the questions can come from different sources not managed by Raffle.

The autocomplete endpoint is used to fetch suggestions based on the input provided by the user so far. The response will be a list of search queries that can be suggested to the user. If no suggestions are found, an empty list is returned.

Insufficient Data

The suggestions returned by the API are based on actual user queries (i.e. what other users have asked previously). A certain amount of existing queries are required before any suggestions can be generated.

The summary endpoint provides a structured response with three main properties:

1. status: Indicates whether the query has a summary. Possible values are:

• success: A summary is available.
• no-relevant-results: No summary could be generated for the query.

2. summary: Contains an HTML-formatted summary of the search results. The summary may include references to items in the references array, denoted by numbers in square brackets (e.g., [1]).

3. references: An array of objects, where each object contains detailed information about a referenced source. These include the source's title, a relevant snippet of text (formatted as HTML), and, if available, a URL.

This endpoint is used to generate concise overviews of search results and link them to their original sources.

The search endpoint can be queried with the question or keywords provided by the user and will respond with a list of search results. Each search result will include the information necessary to display the results back to the user and to provide feedback to Raffle.

Sessions

A user can perform multiple related searches and for the purpose of retraining and analyzing the data, the related searches must be grouped into sessions. It is the responsibility of the client to provide an identifier that allow us to perform this grouping. An identifier could be a user id, a session id, and simply a random string generated on page load. We will not store the identifier in its raw form on our side, but instead use a hashed version.

Displaying results

Depending on the source of the results and its configuration, the available properties can vary.

For most types of sources, results will be of the type "paragraph", and will contain a title, a url (if available), and a snippet of the relevant section in the original content. The snippet will be wrapped in a "

"-tag for consistentcy with other result types, but will otherwise be a plain text representation of the content, to avoid unintentional formatting of the results. Placeholders will be inserted where the original content contained line breaks, so separating characters can be inserted. An example of a paragraph with line break place holders is

<p>Some text <span class="raffle line-break"></span> Some more text</p>

Results originating from instant answer sources will be of the type "instant_answer". These will not include a title, but can optionally be assigned a url by the author. The content will contain the full html-formatting of the original instant answer. It is the responsibility of the client to ensure that it can be displayed properly. If the instant answer is configured with additional call-to-actions or similar, this will be available in "configuration" property.

Annotating results

Certain sources, like webscrapes, can be configured to extract additional html fragments. These will be returned together with the result, and can be used to annotate the result with additional custom information. The html fragment will be represented in json to simplify the extraction of relevant data on the client side. An example of this json format is shown below. If the fragment was not found on the original page, an empty list of matches are returned.

  ...
  "metadata": [{
    "selector": "my-selector"
    "matches": [{
      "type": "tag",
      "tag": "p",
      "children": [{
        "type": "tag",
        "tag": "a",
        "attr": {
          "href": "/link/",
        },
        "children": [{
          "type": "text"
          "data": "link sample text",
        }]
      }]
    }]
  }]
  ...

Providing feedback

A big advantage of AI based search is its ability to learn from its usage and improve over time. All search results will include a "feedback_data" property that will allow for this. See the feedback endpoint for more details.

To avoid test searches from being used in retraining or showing up in insights, the searches can be marked as preview, which will disable all tracking of the search.

In order to improve search results and provide useful insignts, we track what results turned out most useful. An important signal used for determining this is what results a user is following (i.e. clicking or tapping on).

To allow correlating a result with the user action, whenever the user is following a url from a result, the client must call the feedback endpoint with the feedback data provided together with the result. This feedback data is a base64 encoded string that contains relevant information used internally at Raffle, so it must be sent back in its full original form (i.e. no lower casing or truncation).

When a user is forwarded to support outside the raffle widget, it will not be reflected in our analytics. You can use this endpoint to notify us that a user was send to support.

The chat endpoint replies to a chat message, based on the results of a search and previous conversation. If there are no relevant search results, it will be indicated by the status property.

References

A chat reply can reference the search results. These references are provided as indexes enclosed by square brackets (e.g. [1]). The references contain information about the source of the information, including a title, relevant text snippet, and a url (if available).

Follow up questions

If relevant, we will provide a list of related follow up questions that can be suggested to the user. These can be used in subsequent chat requests.

Latency

Note that it may take some time to generate the reply. It is highly recommended to display a placeholder to the user while the reply is being fetched. Once the reply is available, the placeholder can then be replaced by the actual reply.

Extract a list of conversation ids and urls that can be used for external statistics. The conversation ids are extracted from the DOM of the chat application used in the extension. If multiple relevant topics are discussed in a conversation we choose to return the url from the latest topic discussed.