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

Code	Name
200	OK
401	Unauthorized
500	Internal Server Error
503	Service Unavailable

First steps

Field	Type	Description
id	String	Current step ID
type	String	Current step type
payload	String	Needed information for the step. Each step type has its own payload schema.
next	String	Next 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

Field	Type	Description
data	String	JSON field with the response to the step. Each type of step has an expected response format.

Response

Code	Name
200	OK
400	Bad Request
401	Unauthorized
500	Internal 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

Field	Type	Description
message	String	Text 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

Field	Type	Description
message	String	Text to show
ack	String	Button text
colorAck	String	Button color Hex code
textColorAck	String	Text 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

Field	Type	Description
message	String	Text to show
parameter	String	Name for the requested input data
preference	String	Preferred name to be set
defaultValue	String	Default value for the input
validation	`List<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

Field	Type	Description
GETFROMSTEP_PAYLOAD	String	Input from user

{"name": "your name"}

WAIT_SELECTION

The user has to choose between various options.

Payload

Field	Type	Description
message	String	Text to show to the user
parameter	String	Name for the requested input data
options	List	See Option object definition below

Option

Field	Type	Description
key	String	Option key
text	String	Option text to show
colorAck	String	Option color
textColorAck	String	Option 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

Field	Type	Description
response	String	The key of the selected response

{"response": "YES"}

WAIT_PERMISSION

Used for setting permissions.

Payload

Field	Type	Description
message	String	Text to show to the user
permissions	String	Permissions 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

Field	Type	Description
survey_id	String	ID of the completed survey
items	`List<Items>`	IDs of the selected items, separated by commas

Item

Field	Type	Description
id	String	ID of the item
text	String	Related text
image	String	URL of the related image
selected	boolean	State 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

Field	Type	Description
survey_id	String	ID of the completed survey
itemidlist	String	IDs of the selected items, separated by commas

{"survey_id":"2510", "item_id_list": "2000,2002" }

END

There are no more steps.

Start

Step Response

Onboarding Step Types, Payloads and Expected Response to Steps

SHOW_MESSAGE

WAIT_ACK

WAIT_INPUT

WAIT_SELECTION

WAIT_PERMISSION

SHOW_SURVEY

Onboarding Step Types, Payloads
and Expected Response to Steps