{"__v":10,"_id":"544a5de2f1aefa08006efc3d","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":1,"slug":"inboundxml","title":"InboundXML"},"is_link":false,"parentDoc":null,"project":"542dbe0ecb19820800c1f4d7","user":"544a586d27b7fc140078db12","version":{"__v":29,"_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"],"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-24T14:10:42.228Z","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":11,"body":"The `<Play>` element plays an audio file for the caller. The content nested within the `<Play>` element should be the URL of an audio file. Valid audio file formats are: mp3, wav, wma, gsm, ogg, aif, aac. \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Attribute\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"loop\",\n    \"0-1\": \"The amount of times the `<Play>` should be repeated. 0 indicates an infinite loop. The default value is 1. Allowed values are integers greater than or equal to 0.\"\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 `<Play>` element can also be nested within the `<Gather>` verb. The `<Play>` element cannot nest any other elements within itself. It must only nest the URL or tone stream which will be played to the caller.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Tone Stream\"\n}\n[/block]\nIn addition to URLs, the `<Play>` element can also nest tone_stream for producing different tonal values. After a required syntax of “://%”, tone_stream takes a few parameters to define the tone in the following order: (tone duration, pause duration, tone frequency, [additional frequencies to be combined]).\n\nAll durations are in milliseconds, so if a 1 second tone with a 2 second pause between is desired, the first and second parameter values would have to be 1000 and 2000. All tone frequencies are in Hz. For the frequency in Hz of common tones used in current phone systems, see this ITU document.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Examples\"\n}\n[/block]\nThe following plays a dial tone:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<Response>\\n    <Play loop='100'>tone_stream://%(10000,0,350,440)</Play>\\n</Response>\",\n      \"language\": \"xml\"\n    }\n  ]\n}\n[/block]\nThe following plays a busy signal:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<Response>\\n    <Play loop='100'>tone_stream://%(500,500,480,620)</Play>\\n</Response>\",\n      \"language\": \"xml\"\n    }\n  ]\n}\n[/block]\nThe following plays a ringback tone:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<Response>\\n    <Play loop='100'>tone_stream://%(2000,4000,440,480)</Play>\\n</Response>\",\n      \"language\": \"xml\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Tips\"\n}\n[/block]\nSetting the loop value to 0 indicates an infinite loop. This will cause the audio to repeat to the caller until the call is hung up. Quality of the audio may change so it is playable over the telephone network. Higher quality audio files will take longer to play and may even sound worse than lower quality files that degrade less when transcoded to the required format. Additional tone stream frequencies are additive so some knowledge of ring modulation may be useful when creating combinations. Looping of tones can also be achieved alternatively by adding L=; before the % or ;loops= after the parameters. Note that indefinite looping using these nested formats can only be specified by setting loops= -1, rather than 0 as when using the Play loop attribute.","excerpt":"","slug":"play","type":"basic","title":"<Play>"}
The `<Play>` element plays an audio file for the caller. The content nested within the `<Play>` element should be the URL of an audio file. Valid audio file formats are: mp3, wav, wma, gsm, ogg, aif, aac. [block:parameters] { "data": { "h-0": "Attribute", "h-1": "Description", "0-0": "loop", "0-1": "The amount of times the `<Play>` should be repeated. 0 indicates an infinite loop. The default value is 1. Allowed values are integers greater than or equal to 0." }, "cols": 2, "rows": 1 } [/block] [block:callout] { "type": "info", "title": "Nesting", "body": "In addition to the default `<Response>` element, the `<Play>` element can also be nested within the `<Gather>` verb. The `<Play>` element cannot nest any other elements within itself. It must only nest the URL or tone stream which will be played to the caller." } [/block] [block:api-header] { "type": "basic", "title": "Tone Stream" } [/block] In addition to URLs, the `<Play>` element can also nest tone_stream for producing different tonal values. After a required syntax of “://%”, tone_stream takes a few parameters to define the tone in the following order: (tone duration, pause duration, tone frequency, [additional frequencies to be combined]). All durations are in milliseconds, so if a 1 second tone with a 2 second pause between is desired, the first and second parameter values would have to be 1000 and 2000. All tone frequencies are in Hz. For the frequency in Hz of common tones used in current phone systems, see this ITU document. [block:api-header] { "type": "basic", "title": "Examples" } [/block] The following plays a dial tone: [block:code] { "codes": [ { "code": "<Response>\n <Play loop='100'>tone_stream://%(10000,0,350,440)</Play>\n</Response>", "language": "xml" } ] } [/block] The following plays a busy signal: [block:code] { "codes": [ { "code": "<Response>\n <Play loop='100'>tone_stream://%(500,500,480,620)</Play>\n</Response>", "language": "xml" } ] } [/block] The following plays a ringback tone: [block:code] { "codes": [ { "code": "<Response>\n <Play loop='100'>tone_stream://%(2000,4000,440,480)</Play>\n</Response>", "language": "xml" } ] } [/block] [block:api-header] { "type": "basic", "title": "Tips" } [/block] Setting the loop value to 0 indicates an infinite loop. This will cause the audio to repeat to the caller until the call is hung up. Quality of the audio may change so it is playable over the telephone network. Higher quality audio files will take longer to play and may even sound worse than lower quality files that degrade less when transcoded to the required format. Additional tone stream frequencies are additive so some knowledge of ring modulation may be useful when creating combinations. Looping of tones can also be achieved alternatively by adding L=; before the % or ;loops= after the parameters. Note that indefinite looping using these nested formats can only be specified by setting loops= -1, rather than 0 as when using the Play loop attribute.