Menu

Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Collect

Data collection is one of the most common tasks that virtual assistants perform. The Collect action enables you to ask questions to users and efficiently collect answers.

Collect is similar to using web forms. You define the field name and the type for each question and Collect will render conversational flow to ask the user the questions.

The answers are collected in the Assistant's memory and sent in the request parameters on every Autopilot webhook.

  • Collect Properties
  • Questions
  • Validate

Collect properties

Property Description Required
name

A unique string that describes the data being collected. No spaces are allowed.

Yes
questions

An array of questions to ask the user.

Yes
on_complete

The action to execute when the questionnaire is successfully completed.

It can take a redirect action with a task or a URL (see request params).

Yes

Question properties

Property Description Required
question

The question to ask. It can be a { say } action.

Yes
name

The name of the field collected. This must be unique within the questionnaire. No spaces are allowed.

Yes
type

The field type of the questions being collected. This can be a built-in field type or a custom field type.

See built-in field types for more information.

No. If no type is provided free-form input will be collected.

Questions

Example 1: Single free-form question

Free-form questions that are going to receive any type of input, do not need to specify any Type.

{
	"actions": [
		{
			"collect": {
				"name": "collect_comments",
				"questions": [
					{
						"question": "Please let us know any comments or feedback on your recent purchase",
						"name": "comments"
					}
				],
				"on_complete": {
					"redirect": "https://myapp.com/collect"
				}
			}
		}
	]
}

The answers come in the Memory parameter with a JSON containing:

{
	"twilio": {
		"collected_data": {
			"collect_comments": {
				"status": "complete",
				"date_started": "2018-09-10T10:42:00Z",
				"date_completed": "2018-09-10T10:42:00Z",
				"answers": {
					"comments": {
						"answer": "I love the product! thanks so much!",
						"filled": true,
						"attempts": 1,
						"confirmed": false
					}
				}
			}
		}
	}
}

Example 2: Single question: what's your name?

{
	"actions": [
		{
			"collect": {
				"name": "ask_first_name",
				"questions": [
					{
						"question": "Hi! What's your name",
						"name": "first_name",
						"type": "Twilio.FIRST_NAME"
					}
				],
				"on_complete": {
					"redirect": "https://myapp.com/collect"
				}
			}
		}
	]
}

The answers come in the Memory parameter with a JSON containing:

{
	"twilio": {
		"collected_data": {
			"ask_first_name": {
				"status": "complete",
				"date_started": "2018-09-10T10:42:00Z",
				"date_completed": "2018-09-10T10:42:00Z",
				"answers": {
					"first_name": {
						"answer": "Robert",
						"type": "Twilio.FIRST_NAME",
						"filled": true,
						"attempts": 1,
						"confirmed": false
					}
				}
			}
		}
	}
}

Example 3: Multiple questions

The questions will be asked sequentially.

{
	"actions": [
		{
			"collect": {
				"name": "travel_questions",
				"questions": [
					{
						"question": "Do you like traveling?",
						"name": "likes_traveling",
						"type": "Twilio.YES_NO"
					},
					{
						"question":"What's your favorite city?",
						"name": "favorite_city",
						"type": "Twilio.CITY"
					}
				],
				"on_complete": {
					"redirect": "https://myapp.com/collect"
				}
			}
		}
	]
}

The answers come in the Memory parameter with a JSON containing:

{
	"twilio": {
		"collected_data": {
			"travel_questions": {
				"status": "complete",
				"date_started": "2018-09-10T10:42:00Z",
				"date_completed": "2018-09-10T10:42:00Z",
				"answers": {
					"likes_traveling": {
						"type": "Twilio.YES_NO",
						"answer": "Yes",
						"filled": true,
						"attempts": 1,
						"confirmed": false
					},
					"favorite_city": {
						"answer": "San Francisco",
						"type": "Twilio.CITY",
						"filled": true,
						"attempts": 1,
						"confirmed": false
					}
				}
			}
		}
	}
}

Validate

Collect enables you to validate the user input with the Validate instruction.

Validate property Description Default
allowed_values A list of allowed values

If no list of values is specified, Validate will verify that the value is a valid type for the specified field type.

For example, if the field is Twilio.DATE, Validate will verify that the provided value is a valid date.

webhook A webhook to validate the value being collected. Useful when validating fields like order numbers or available dates that can only be validated against your business logic

If no webhook is specified, Validate will verify that the value is a valid type for the specified field type.

If both allowed values and webhook are specified, only allowed values is considered.

See Example 6.

on_failure The messages when the input is invalid.

By default, the on_failure messages are defined in the Stylesheet. It can be overridden by defining on_failure messages in the collect.

The on_failure action is defined in the Defaults. It can be overridden by defining the on_failure message in the collect.

on_success The message when the question is answered successfully. By default, the on_success message is defined in the Stylesheet. It can be overridden by defining on_success message in the collect.
max_attempts The max attempts property instruct Autopilot how many times it should as the user By default, max_attempts is defined in the Stylesheet. It can be overridden by defining max_attempts in the collect.

Collect Validate Webhook

The request parameters

The Collect Validate webhook has all the Standard Autopilot Parameters except the two parameters Field_{field-name}_Value and Field_{field-name}_Type and the Collect Validate specific parameters defined below:

Parameter

Description

Example

CollectName

The name of the Collect

CollectName=travel_questions

CollectDateStarted

The timestamp when the Collect was started.

CollectDateStarted=2018-09-10T10:42:00Z

CollectStatus

The status of the Collect

CollectStatus=in-progress

ValidateFieldName

The name of the field to be validated

ValidateFieldName=trip_start

ValidateFieldType

The type of the field to be validated

ValidateFieldType=Twilio.CITY

ValidateFieldAnswer

The value to be validated

ValidateFieldAnswer=San Francisco

Expected response

Autopilot expects the following JSON response when the value is valid:

{
   "valid" : true
}

Autopilot expects the following JSON response when the value is not valid:

{
   "valid" : false
}

Example 4: Multiple questions with validate

{
	"actions": [
		{
			"collect": {
				"name": "travel_questions",
				"questions": [
					{
						"question": "Where would you like to start your Trip? New York or San Francisco",
						"name": "trip_start",
						"type": "Twilio.CITY",
						"validate": {
							"allowed_values": {
								"list": [
									"New York",
									"San Francisco"
								]
							},
							"on_failure": {
								"messages": [
									{
										"say": "Sorry, that's not a valid start city."
									},
									{
										"say": "Hmm, I'm not understanding. It can be San Francisco or New york."
									}
								],
								"repeat_question": true
							},
							"on_success": {
								"say": "Great, we've got your starting city"
							},
							"max_attempts": {
								"redirect": "task://having-trouble",
								"num_attempts": 3
							}
						}
					},
					{
						"question": "Would you like to be on our January, June or September trip?",
						"name": "trip_month",
						"type": "Twilio.Month",
						"validate": {
							"allowed_values": {
								"list": [
									"January",
									"June",
									"September"
								]
							},
							"on_failure": {
								"messages": [
									{
										"say": "Sorry, that's valid month"
									},
									{
										"say": "Hmm, I'm not understanding. It can be January, June, and September"
									}
								],
								"repeat_question": true
							},
							"on_success": {
								"say": "Great, we've got your month"
							},
							"max_attempts": {
								"redirect": "task://having-trouble",
								"num_attempts": 3
							}
						}
					}
				],
				"on_complete": {
					"redirect": "https://myapp.com/collect"
				}
			}
		}
	]
}

Valid answers come in the Memory parameter with a JSON containing:

{
	"twilio": {
		"collected_data": {
			"travel_questions": {
				"status": "complete",
				"date_started": "2018-09-10T10:42:00Z",
				"date_completed": "2018-09-10T10:42:00Z",
				"answers": {
					"trip_start": {
						"type": "Twilio.CITY",
						"answer": "San Francisco",
						"filled": true,
						"attempts": 1,
						"confirmed": false
					},
					"trip_month": {
						"answer": "January",
						"type": "Twilio.MONTH",
						"filled": true,
						"attempts": 1,
						"confirmed": false
					}
				}
			}
		}
	}
}

Invalid answers would look like this:

{
	"twilio": {
		"collected_data": {
			"travel_questions": {
				"status": "complete",
				"date_started": "2018-09-10T10:42:00Z",
				"date_completed": "2018-09-10T10:42:00Z",
				"answers": {
					"trip_start": {
						"type": "Twilio.CITY",
						"error":{
                          "error_message":"Invalid Value",
                          "value":"donuts"
                       }
,
						"filled": true,
						"attempts": 1,
						"confirmed": false
					},
					"trip_month": {
						"error":{
                          "error_message":"Invalid Value",
                          "value":"I habe no idea"
                       },
						"type": "Twilio.MONTH",
						"filled": true,
						"attempts": 1,
						"confirmed": false
					}
				}
			}
		}
	}
}

Example 5: Single question without validation or optional

{
	"actions": [
		{
			"collect": {
				"name": "ask_first_name",
				"questions": [
					{
						"question": "Hi! What's your name",
						"name": "first_name",
						"type": "Twilio.FIRST_NAME",
						"validate": false,
					}
				],
				"on_complete": {
					"redirect": "https://myapp.com/collect"
				}
			}
		}
	]
}

Example 6: Single question validation webhook

{
    "actions": [
        {
            "collect": {
                "name": "travel_questions",
                "questions": [
                    {
                        "question": "Where would you like to start your Trip?",
                        "name": "trip_start",
                        "type": "Twilio.CITY",
                        "validate": {
                            "on_failure": {
                                "messages": [
                                    {
                                        "say": "Sorry, that's not a valid start city."
                                    },
                                    {
                                        "say": "Hmm, I'm not understanding. It can be San Francisco or New york."
                                    }
                                ],
                                "repeat_question": true
                            },
                            "webhook": {
                                "url":"https://myapp.com/validateTripStart",
                                "method":"POST"
                            },
                            "on_success": {
                                "say": "Great, we've got your starting city"
                            },
                            "max_attempts": {
                                "redirect": "task://say",
                                "num_attempts": 3
                            }
                        }
                    }
                ],
                "on_complete": {
                    "redirect": "https://myapp.com/fullfill"
                }
            }
        }
    ]
}
Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.