Start a Guided Help Search

Overview

The Start a Guided Help search can be used to start a search session in the Guided Help.

A Guided Help profile can also be specified while starting the session and it is used to filter the results of search. If this is not passed in the request, the default profile of the portal is used. Questions can also be answered at time of starting the search session.

A Guided Help search session can be started in following ways:

  • Launch session for a specific Casebase Release.
  • Launch session for a Casebase and specify the release type.
  • Use a Guided Help session Article and pass the required session parameters.

Prerequisites

  • A Guided Help profile must be assigned to the user.
  • Casebase Release passed in the request must be associated with the portal passed in URI.
SecurityoAuthUser or oAuthOnBehalfOfUser or oAuthCustomer or oAuthOnBehalfOfCustomer or oAuthAnonymousCustomer
Request
path Parameters
portalID
required
string [ 7 .. 20 ] characters ^[a-zA-Z0-9]{2,4}-\d{4,15}$

The ID of the portal being accessed.

A portal ID is composed of a 2-4 letter prefix, followed by a dash and 4-15 digits.

Example: PROD-1000
query Parameters
$lang
string

The language that describes the details of a resource. Resources available in different languages may differ from each other.

  • If lang is not passed, then the portal's default language is used.

    • Enum: "en-US" "fr-FR" "en-GB" "es-ES" "it-IT" "nl-NL" "da-DA" "sv-SE" "pt-PT" "fi-FI" "no-NB" "no-NN" "ja-JA" "de-DE" "pt-BR" "zh-CN" "zh-TW" "ko-KO" "ru-RU" "el-EL" "tr-TR" "pl-PL" "cs-CS" "sk-SK" "hu-HU" "sr-SR" "ar-SA" "hr-HR" "ro-RO" "th-TH" "de-AT" "vi-VN" "id-ID" "ms-MY" "fil-PH" "fr-CA" "hi-IN" "uk-UA" "bg-BG" "sl-SI" "sr-RS" "xx-XX"
    Example: $lang=en-US
    ghCustomAdditionalAttributes
    string [ 1 .. 4000 ] characters ^question\.custom\.[^,]+(?:,question\.custom\...

    Custom attributes to be fetched.

    Possible values are:

    • question.custom.<name> where <name> is the internal name of custom attribute of question. 'question' is used as a prefix to distinguish question's custom attribute from other objects custom attributes.
    Examples:
    A user-defined custom attribute.
    ghCustomAdditionalAttributes=question.custom.score
    Multiple user-defined custom attributes.
    ghCustomAdditionalAttributes=question.custom.score,question.custom.test
    header Parameters
    x-egain-activity-id
    string [ 4 .. 9 ] characters ^[0-9]{4,9}$

    A unique numeric interaction identifier from eGain.

    Example: 59237
    x-ext-integration-id
    string <= 40 characters ^[\w\W]+$

    The unique numeric identifier for a tenant, used in self-service functionality as well as third-party integrations.

    Note: If x-egain-activity-id is not provided, then this must be passed along with x-ext-interaction-id.

    Examples:
    3155180e-0c13-43e9-9c38-e9045bcbf176
    00Dbn00000IxGnx
    x-ext-interaction-id
    string <= 40 characters ^[\w\W]+$

    A unique interaction identifier from other CRM applications.

    Note: If x-egain-activity-id is not provided, then this must be passed along with x-ext-integration-id.

    Examples:
    3155180e-0c13-43e9-9c38-e9045bcbf176
    00Dbn00000IxGnx
    Accept-Language
    required
    string

    The Language locale accepted by the client (used for locale specific fields in resource representation and in error responses).

    Enum: "en-US" "es-ES" "fr-FR" "it-IT" "de-DE" "nl-NL" "pt-BR" "pt-PT" "da-DK" "ru-RU" "fr-CA" "zh-CN" "ja-JP" "ko-KR" "sv-SE"
    Example: en-US
    Content-Type
    required
    string
    Default: application/json

    The media type sent by the client.

    Value: "application/json"
    Request Body schema: application/json
    casebaseId
    required
    string (CasebaseId) = 15 characters ^[1-9]\d*$

    The numerical ID of the Casebase.

    Array of objects (Question and Answers) [ 0 .. 500 ] items

    Pre-answered Questions in Guided Help search

    profileId
    string [ 1 .. 15 ] characters ^1$|^[1-9]\d{9,15}$

    The ID of the guided help profile.
    1 will always be the system profile.

    Array of objects (SessionContextVariable)

    Session variables used to give Guided Help additional context.

    startOver
    boolean

    Restart the current Guided Help search with the existing context along with session variable context.

    useLiveRelease
    boolean

    Use current live release snapshot of the Casebase otherwise use the authoring release.

    ghsArticleId
    string = 15 characters ^[1-9]\d*$

    Numeric ID of the guided help session article used for starting search.

    Responses
    200

    Success

    400

    Bad Request

    401

    Unauthorized

    403

    Forbidden

    404

    Not Found

    406

    Not acceptable

    415

    Incorrect Content Type Header

    429

    Too Many Request

    500

    Internal server error

    post/portals/{portalID}/gh/search
    Request samples
    application/json
    {
    • "casebaseId": "202201000000002"
    }
    Response samples
    application/json
    {
    • "casebase": {
      },
    • "actionSearch": [ ],
    • "answeredQuestion": [ ],
    • "caseSearch": [ ],
    • "dynamicSearch": [ ],
    • "unansweredQuestion": [
      ],
    • "startupQuestion": [
      ],
    • "targetClusters": [
      ]
    }