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.