{"__v":11,"_id":"544cbbf211845f0e001ed908","category":{"__v":21,"_id":"543bf3e22a30961a00b66eb3","pages":["5489d5e61ea5330b007b5a51","5489e243d8dec60b00034297","5489e318aefb240b00d197ef","56cdf622e538330b0021ab5a"],"project":"542dbe0ecb19820800c1f4d7","version":"542ecc0a6b0eb6080066ca77","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-10-13T15:46:42.097Z","from_sync":false,"order":0,"slug":"inboundxml","title":"InboundXML"},"is_link":false,"parentDoc":null,"project":"542dbe0ecb19820800c1f4d7","user":"544a586d27b7fc140078db12","version":{"__v":31,"_id":"542ecc0a6b0eb6080066ca77","forked_from":"542dbe0fcb19820800c1f4da","project":"542dbe0ecb19820800c1f4d7","createdAt":"2014-10-03T16:17:14.165Z","releaseDate":"2014-10-03T16:17:14.165Z","categories":["542ecc0a6b0eb6080066ca78","542ef44f6b0eb6080066cb24","543bf3e22a30961a00b66eb3","5446952b82bd7e08002768a0","544821ae8d7af31a00dd41ce","544a7885f1aefa08006efc69","544c758e11845f0e001ed8de","544e5565b80812080035be55","544e558dbd51b9080037f8ca","5450b045a66f020800dba73d","5450eb6aa66f020800dba945","5450f39ea66f020800dba989","5450f877a66f020800dba9cf","54510356a66f020800dbaa17","5451274514af501a00b50c99","54513345a66f020800dbab24","54513cc014af501a00b50d24","54515eec14af501a00b50db9","54519b1d14af501a00b50ea9","54519b2aa66f020800dbacb4","54524f9704160008005b1d27","54538d2308d1800800473d95","54538d420c09721000a06a03","54538e5608d1800800473d9a","5453ea9547c30114004fb375","5453eb12b077c31c00067bcb","5453eb27b077c31c00067bcd","5453ed5db077c31c00067bde","548075cbe291c51a00e7e096","5922fa475c48c70f00f21453","59244fd41e32eb190028ad8d"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"2.0.0","version":"2"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2014-10-26T09:16:34.238Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"basic_auth":false,"results":{"codes":[]},"settings":"","try":true,"auth":"never","params":[],"url":""},"isReference":false,"order":5,"body":"The `<Gather>` element allows callers to input digits to the call using their keypads which are then sent via POST or GET to a URL for further processing. There are many ways to get creative with `<Gather>` but its most common use case is in creating IVR menus. This is accomplished by nesting prompts for input from the caller using the `<Say>` or `<Play>` elements.\n\nBy default, an unlimited number of digits can be gathered. `<Gather>` will timeout after 5 seconds or once the ‘#’ key is pressed. The gathered digits will then be submitted to the current InboundXML document. This default behavior of `<Gather>` can be altered using the provided element attributes.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Attribute\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"action\",\n    \"0-1\": \"URL where the flow of the call and the gathered digits will be forwarded to (if digits are input).\",\n    \"1-0\": \"method\",\n    \"1-1\": \"Method used to request the action URL. Default value is POST. Available methods are GET and POST.\",\n    \"2-0\": \"timeout\",\n    \"2-1\": \"The number of seconds `<Gather>` should wait for digits to be entered before requesting the action URL. Timeout resets with each new digit input. Default value is 5 seconds. Timeout accepts any integer greater than or equal to 0.\",\n    \"3-0\": \"finishOnKey\",\n    \"3-1\": \"The key a caller can press to end the `<Gather>`. Default value is #. Acceptable values are digits from 0 to 9, # or *\",\n    \"4-0\": \"numDigits\",\n    \"4-1\": \"The maximum number of digits to `<Gather>`. Default value is set to no limit. Acceptable value is any integer greater than or equal to 0.\"\n  },\n  \"cols\": 2,\n  \"rows\": 5\n}\n[/block]\nIn addition to the default voice request parameters, the following gather-specific parameter is also forwarded to the action URL.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"Digits\",\n    \"0-1\": \"All gathered digits, not including finishOnKey.\"\n  },\n  \"cols\": 2,\n  \"rows\": 1\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Nesting\",\n  \"body\": \"In addition to the default `<Response>` element, the `<Gather>` element cannot be nested within any other verbs besides the default element. The `<Say>`, `<Play>`, and `<Pause>` elements can all be nested within the `<Gather>` element.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Tips\"\n}\n[/block]\nIf nested `<Say>` or `<Play>` elements are present, the timeout attribute starts after either the first key to be gathered is pressed or say/play prompt completes. If the `<Gather>` fails to execute, the very next verb will be executed.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Examples\"\n}\n[/block]\nThe InboundXML below will prompt the caller to enter a four digit pin and then forward the input digits to the action URL using the GET method.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<Response>\\n  <Gather method=\\\"GET\\\" numDigits=\\\"4\\\" finishOnKey=\\\"#\\\" action=\\\"http://example.com/example-callback-url/say?example=simple.xml\\\">\\n    <Say>Please enter your 4 digit pin.</Say>\\n  </Gather>\\n</Response>\",\n      \"language\": \"xml\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"gather","type":"basic","title":"<Gather>"}
The `<Gather>` element allows callers to input digits to the call using their keypads which are then sent via POST or GET to a URL for further processing. There are many ways to get creative with `<Gather>` but its most common use case is in creating IVR menus. This is accomplished by nesting prompts for input from the caller using the `<Say>` or `<Play>` elements. By default, an unlimited number of digits can be gathered. `<Gather>` will timeout after 5 seconds or once the ‘#’ key is pressed. The gathered digits will then be submitted to the current InboundXML document. This default behavior of `<Gather>` can be altered using the provided element attributes. [block:parameters] { "data": { "h-0": "Attribute", "h-1": "Description", "0-0": "action", "0-1": "URL where the flow of the call and the gathered digits will be forwarded to (if digits are input).", "1-0": "method", "1-1": "Method used to request the action URL. Default value is POST. Available methods are GET and POST.", "2-0": "timeout", "2-1": "The number of seconds `<Gather>` should wait for digits to be entered before requesting the action URL. Timeout resets with each new digit input. Default value is 5 seconds. Timeout accepts any integer greater than or equal to 0.", "3-0": "finishOnKey", "3-1": "The key a caller can press to end the `<Gather>`. Default value is #. Acceptable values are digits from 0 to 9, # or *", "4-0": "numDigits", "4-1": "The maximum number of digits to `<Gather>`. Default value is set to no limit. Acceptable value is any integer greater than or equal to 0." }, "cols": 2, "rows": 5 } [/block] In addition to the default voice request parameters, the following gather-specific parameter is also forwarded to the action URL. [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Description", "0-0": "Digits", "0-1": "All gathered digits, not including finishOnKey." }, "cols": 2, "rows": 1 } [/block] [block:callout] { "type": "info", "title": "Nesting", "body": "In addition to the default `<Response>` element, the `<Gather>` element cannot be nested within any other verbs besides the default element. The `<Say>`, `<Play>`, and `<Pause>` elements can all be nested within the `<Gather>` element." } [/block] [block:api-header] { "type": "basic", "title": "Tips" } [/block] If nested `<Say>` or `<Play>` elements are present, the timeout attribute starts after either the first key to be gathered is pressed or say/play prompt completes. If the `<Gather>` fails to execute, the very next verb will be executed. [block:api-header] { "type": "basic", "title": "Examples" } [/block] The InboundXML below will prompt the caller to enter a four digit pin and then forward the input digits to the action URL using the GET method. [block:code] { "codes": [ { "code": "<Response>\n <Gather method=\"GET\" numDigits=\"4\" finishOnKey=\"#\" action=\"http://example.com/example-callback-url/say?example=simple.xml\">\n <Say>Please enter your 4 digit pin.</Say>\n </Gather>\n</Response>", "language": "xml" } ] } [/block]