メニュー

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

プロパティ 概要 必須
name

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

はい
questions

An array of questions to ask the user.

はい
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).

はい

Question properties

プロパティ 概要 必須
question

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

はい
name

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

はい
タイプ

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 概要 初期値
allowd_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 data type. For example, if the field is Twilio.DATE, Validate will verify that the provided value is a valid date.
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.

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"
				}
			}
		}
	]
}
Rate this page:

ヘルプが必要ですか?

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.