loading

Action - Return Pinned Result| Hitchhikers Platform

What You’ll Learn

In this section, you will learn:

  • How to structure the Return Pinned Result action
  • Example of the Return Pinned Result action

Action Structure

There are two top level properties of this action - directAnswer and verticals.

Top Level Properties

Key Type Example
directAnswer Optional, Direct Answer Object See below
verticals Array of Vertical Object with length of at least 1 See below

Vertical Object

The vertical object defines the behavior of each vertical included in the pinned results. For a Knowledge Graph vertical, entityIds or savedFilterId is required. For a vertical that is not powered by the Knowledge Graph, it will show the normal results from that backend wherever that vertical is referenced - you cannot control the order of the results.

Key Type Example
verticalKey String “specialties”
entityIds Array of strings [“2323”, “2342”]
savedFilterId String “21466424”

Direct Answer Object

You can also specify the direct answer that should show alongside the entity results. entityId, fieldId, and verticalKey are required. Note that the fieldId you specify must also be set in your verticals Answers Configuration object as "directAnswer": "true".

Key Type Example
entityId String “230s”
fieldId String - Field API Name “name”
verticalKey String doctors

Config Structure

{
  "actionType": "RETURN_PINNED_RESULT",
  "directAnswer": {
    "entityId": "230s",
    "fieldId": "name",
    "verticalKey": "doctors"
  },
  "verticals": [
    {
      "verticalKey": "specialties",
      "savedFilterId": "21466424"
    },
    {
      "verticalKey": "faqs",
      "entityIds": [
        "FAQ-1",
        "FAQ-2"
      ]
    },
    {
      "verticalKey": "links"
    }
  ]
}

If you’re using the UI, you can paste this in to the input:

{"actionType":"RETURN_PINNED_RESULT","directAnswer":{"entityId":"230s","fieldId":"name","verticalKey":"doctors"},"verticals":[{"verticalKey":"specialties","savedFilterId":"21466424"},{"verticalKey":"faqs","entityIds":["FAQ-1","FAQ-2"]},{"verticalKey":"links"}]}

The following example will reference the JSON editor, but you can use either.

Pinned Results Example

For a query like “turtlehead tacos headquarters”, we might want to push users to apply for a job.

We’ll do the following:

  • Look for any search terms that contain turtlehead tacos headquarters
  • Set the directAnswer object to return the address field for entity hq-1 in the restaurants vertical
  • Return the FAQs vertical filtered to the savedFilterId of 146669234.
{
	 "criteria": {
        "searchTermContains": [
          "turtlehead tacos headquarters"
        ]
      },
      "actions": [
        {
          "actionType": "RETURN_PINNED_RESULT",
          "directAnswer": {
            "entityId": "hq-1",
            "fieldId": "address",
            "verticalKey": "restaurants"
          },
          "verticals": [
            {
              "savedFilterId": "146669234",
              "verticalKey": "faqs"
            }
          ]
        }
      ]
    }
 

Pinned HQ Query

light bulb
Tip
Use pinned results sparingly. By pinning results, you are completely overriding the algorithm behavior for the queries that match your criteria, which could have unintended consequences and be difficult to maintain.
unit Quiz
+20 points
Daily Quiz Streak Daily Quiz Streak: 0
Quiz Accuracy Streak Quiz Accuracy Streak: 0
    Error Success Question 1 of 3

    What are the top level properties used in the Return Pinned Result action? Select all that apply.

    Error Success Question 2 of 3

    What are the components in the Vertical Object for the Return Pinned Result action? Select all that apply.

    Error Success Question 3 of 3

    What are the components in the Direct Answer Object for the Return Pinned Result action? Select all that apply.

    You're out of this world! 🌎

    You've already completed this quiz, so you can't earn more points.You completed this quiz in 1 attempt and earned 0 points! Feel free to review your answers and move on when you're ready.
1st attempt
0 incorrect
Splash Loading