Onboarding

The onboarding process of the end user consists of a series of consecutive steps necessary for the initial setup of the user profile. These steps may be messages sent to the user, data to be requested, permissions to be requested, and so on.

Onboarding services provide the information needed to create an initial dialogue, based on these steps. If there is no onboarding data for the user or it has already been completed, no steps will be returned.

There are two possible requests:

  • Start: Used to request the first steps of the onboarding process, if it needs to be completed.
  • Step response: Used to answer the requested information. It will return the next steps.

Start

GET /onboarding/start
Return the first steps of the user onboarding or an empty list, if the onboarding has been completed.

curl -X GET "https://api.sherpa.ai/v2/onboarding/start" \
-H  "Authorization: Basic XXXX-SHERPA-TOKEN-XXXX"
-H  "accept: application/json" \
-H  "content-type: application/x-www-form-urlencoded" \
-H  "Accept-Language: en" \
[
    {
        "id": 5010,
        "type": "SHOW_MESSAGE",
        "payload": {
            "message": "Hello and welcome to the new Sherpa. "
        },
        "next": 5020
    },
    {
        "id": 5020,
        "type": "SHOW_MESSAGE",
        "payload": {
            "message": "Even though we've already met, I'd like to know more about you."
        },
        "next": 5040
    },
    {
        "id": 5040,
        "type": "WAIT_ACK",
        "payload": {
            "message": "Ready to begin?",
            "ack": "Yes, let's begin",
            "colorAck": "",
            "textColorAck": ""
        },
        "next": 5060
    },
    {
        "id": 5060,
        "type": "WAIT_INPUT",
        "payload": {
            "message": "First of all, tap 'Send' if you’d like me to continue calling you %%USERNAME%%. If not, please tell me what you’d like to be called.",
            "parameter": "name",
            "preference": "USERNAME",
            "defaultValue": "test ",
            "validation": {
                "retries": 2,
                "regExps": []
            }
        },
        "next": null
    }
]

Response

CodeName
200OK
401Unauthorized
500Internal Server Error
503Service Unavailable

First steps

FieldTypeDescription
idStringCurrent step ID
typeStringCurrent step type
payloadStringNeeded information for the step. Each step type has its own payload schema.
nextStringNext step ID

Step Response

POST /onboarding/{STEP_ID}/response
This endpoint is used to provide the required responses for the steps.

curl -X POST "https://api.sherpa.ai/v2/onboarding/5060/response" \
-H  "Authorization: Basic XXXX-SHERPA-TOKEN-XXXX"
-H  "accept: application/json" \
-H  "content-type: application/x-www-form-urlencoded" \
-H  "Accept-Language: en" \
-d "data={\"name\": \"new name\"}"
[
    {
        "id": 5090,
        "type": "SHOW_MESSAGE",
        "payload": {
            "message": "Delighted to speak with you, %%USERNAME%%."
        },
        "next": 5095
    },
    {
        "id": 5095,
        "type": "WAIT_PERMISSION",
        "payload": {
            "message": "I’m checking to see what permissions I have in order to do my job as best I can. I might need you to give me another permission or two, though.",
            "permissions": [
                "NOTIFICATIONS",
                "LOCATION",
                "CONTACTS",
                "CALENDAR"
            ]
        },
        "next": null
    }
]

Parameters

FieldTypeDescription
dataStringJSON field with the response to the step. Each type of step has an expected response format.

Response

CodeName
200OK
400Bad Request
401Unauthorized
500Internal Server Error

Onboarding Step Types, Payloads
and Expected Response to Steps

The following step types may be returned. The required payload and expected response are also shown below.

SHOW_MESSAGE

A message needs to be shown.

Payload

FieldTypeDescription
messageStringText to show
    {
        "id": 5090,
        "type": "SHOW_MESSAGE",
        "payload": {
            "message": "Delighted to speak with you, %%USERNAME%%."
        },
        "next": 5095
    }

Expected Response

No response is needed.

WAIT_ACK

User confirmation is needed. May be used to ensure that a user has read previous messages. The payload is used to build a button for the necessary confirmation.

Payload

FieldTypeDescription
messageStringText to show
ackStringButton text
colorAckStringButton color Hex code
textColorAckStringText color Hex code
    {
        "id": 5040,
        "type": "WAIT_ACK",
        "payload": {
            "message": "Ready to begin?",
            "ack": "Yes, let's begin",
            "colorAck": "",
            "textColorAck": ""
        },
        "next": 5060
    }

Expected Response

An empty JSON object.

{}

WAIT_INPUT

User input is needed.

Payload

FieldTypeDescription
messageStringText to show
parameterStringName for the requested input data
preferenceStringPreferred name to be set
defaultValueStringDefault value for the input
validationList<String>List of regular expressions to check if the value is valid
    {
        "id": 5060,
        "type": "WAIT_INPUT",
        "payload": {
            "message": "First of all, tap 'Send' if you’d like me to continue calling you %%USERNAME%%. If not, please tell me what you’d like to be called.",
            "parameter": "name",
            "preference": "USERNAME",
            "defaultValue": "seat",
            "validation": {
                "retries": 2,
                "regExps": []
            }
        },
        "next": null
    }

Expected Response

FieldTypeDescription
GETFROMSTEP_PAYLOADStringInput from user
{"name": "your name"}

WAIT_SELECTION

The user has to choose between various options.

Payload

FieldTypeDescription
messageStringText to show to the user
parameterStringName for the requested input data
optionsListSee Option object definition below

Option

FieldTypeDescription
keyStringOption key
textStringOption text to show
colorAckStringOption color
textColorAckStringOption text color
    {
        "id": 5080,
        "type": "WAIT_SELECTION",
        "payload": {
            "message": "%%USERNAME%%, Are you sure that's what you'd like me to call you?",
            "parameter": "response",
            "options": [
                {
                    "key": "NO",
                    "text": "No",
                    "colorAck": "#26262F",
                    "textColorAck": "#FFFFFF"
                },
                {
                    "key": "YES",
                    "text": "Yes",
                    "colorAck": "",
                    "textColorAck": ""
                }
            ]
        },
        "next": null
    }

Expected Response

FieldTypeDescription
responseStringThe key of the selected response
{"response": "YES"}

WAIT_PERMISSION

Used for setting permissions.

Payload

FieldTypeDescription
messageStringText to show to the user
permissionsStringPermissions needed
   {
        "id": 5095,
        "type": "WAIT_PERMISSION",
        "payload": {
            "message": "I’m checking to see what permissions I have in order to do my job as best I can. I might need you to give me another permission or two, though.",
            "permissions": [
                "NOTIFICATIONS",
                "LOCATION",
                "CONTACTS",
                "CALENDAR"
            ]
        },
        "next": null
    }

Expected Response

An empty JSON Object.

{}

SHOW_SURVEY

The user has to complete a survey.

Payload

FieldTypeDescription
survey_idStringID of the completed survey
itemsList<Items>IDs of the selected items, separated by commas

Item

FieldTypeDescription
idStringID of the item
textStringRelated text
imageStringURL of the related image
selectedbooleanState of the selection
    {
        "id": 5110,
        "type": "SHOW_SURVEY",
        "payload": {
            "surveyId": 2513,
            "items": [
                {
                    "id": 2000,
                    "text": "International",
                    "image": "https://s3-eu-west-1.amazonaws.com/sherpa-cdn/survey/interest/Gustos/2000.png",
                    "selected": false
                },
                {
                    "id": 2002,
                    "text": "Technology",
                    "image": "https://s3-eu-west-1.amazonaws.com/sherpa-cdn/survey/interest/Gustos/2002.png",
                    "selected": false
                },
                {
                    "id": 2003,
                    "text": "Finance",
                    "image": "https://s3-eu-west-1.amazonaws.com/sherpa-cdn/survey/interest/Gustos/2003.png",
                    "selected": false
                },
                ...
            ],
            "minOptions": 2,
            "parameter": "survey_id,item_id_list"
        }
    }

Expected Response

FieldTypeDescription
survey_idStringID of the completed survey
itemidlistStringIDs of the selected items, separated by commas
{"survey_id":"2510", "item_id_list": "2000,2002" }

END

There are no more steps.