{"__v":17,"_id":"544e4b9fbd51b9080037f874","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":["588a969f9864881b00189fe6"],"next":{"pages":[],"description":""},"createdAt":"2014-10-27T13:41:51.248Z","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":4,"body":"The `<Dial>` element starts an outgoing dial from the current call. Once the dial is complete, the next element in the InboundXML document will be processed unless the action attribute is set. If the action attribute is set, the result of the dial is submitted as a GET or POST (depending on the method attribute) to the action URL, and the call will continue using the InboundXML in said URL.\n\nBy default, the outgoing call will timeout after 30 seconds if it is not answered. However, the timeout attribute can be used to set a custom time. The length of the call is limited by the timeLimit attribute, which is 4 hours (14400 seconds) by default.\n\nSetting the hangupOnStar attribute to ‘true’ will allow the original call to terminate the outgoing call without having to hangup by dialing ‘*’. The original call then continues with the current InboundXML document, or if a URL was passed, the response from the action attribute.\n\nThe callerId attribute can be set to any number, and will default to the caller id of the original caller. The number to be dialed should be nested within the `<Dial>` element. For more options, use the `<Number>`, `<Sip>` or `<Conference>` elements instead of a simple phone number.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Attribute\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"action\",\n    \"0-1\": \"URL where some parameters specific to `<Dial>` will be sent for further processing. The calling party can be redirected here upon the hangup of the B leg caller.\",\n    \"1-0\": \"method\",\n    \"1-1\": \"Method used to request the action URL. Default Value: POST. Allowed Value: POST or GET.\",\n    \"2-0\": \"timeLimit\",\n    \"2-1\": \"The duration in seconds a call made through `<Dial>` should occur for before ending. Default Value: 14400. Allowed Value: integer greater than or equal to 1.\",\n    \"3-0\": \"callerId\",\n    \"3-1\": \"Number to display as calling. Defaults to the ID of phone being used.\",\n    \"4-0\": \"hideCallerId\",\n    \"4-1\": \"Boolean value specifying if the caller ID should be hidden or not. Default Value: false. Allowed Value: true or false.\",\n    \"5-0\": \"dialMusic\",\n    \"5-1\": \"URL to an InboundXML document to be executed in place of the call ringtone (a `<Say>` or `<Play>` would be appropriate in this document).\",\n    \"6-0\": \"callbackUrl\",\n    \"6-1\": \"URL requested when the dialed call connects and ends. Note that this URL only receives parameters containing information about the call, the call does not execute XML given as a callbackUrl.\",\n    \"7-0\": \"callbackMethod\",\n    \"7-1\": \"Method used to request the callback URL. Default Value: POST. Allowed Value: POST or GET.\",\n    \"8-0\": \"confirmSound\",\n    \"8-1\": \"The URL that Zang should reach out to when the called party answers. The URL should return InboundXML containing `<Play>`, `<Pause>`, and/or `<Say>` elements only. Any other elements will be ignored.\",\n    \"9-0\": \"digitsMatch\",\n    \"9-1\": \"Specifies digits that Zang should listen for and send to the callbackUrl if a caller inputs them. Separate additional digits or digit patterns with a comma. Allowed Value: Pattern made up of the digits 0-9, #, or *.\",\n    \"10-0\": \"straightToVm\",\n    \"10-1\": \"Boolean value specifying if call should be redirected to voicemail immediately. Note: only works if dialing TO a mobile number. Default Value: false. Allowed Value: true or false.\",\n    \"11-0\": \"heartbeatUrl\",\n    \"11-1\": \"A URL Zang can request every 60 seconds during the call to notify of elapsed time and pass other general information.\",\n    \"12-0\": \"heartbeatMethod\",\n    \"12-1\": \"Method used to request the heartbeatUrl. Default Value: POST. Allowed Value: POST or GET.\",\n    \"13-0\": \"forwardedFrom\",\n    \"13-1\": \"Specifies the number to list the call as forwarded from.\",\n    \"14-0\": \"ifMachine\",\n    \"14-1\": \"Specifies how Zang should handle this dial if the receiving phone number is unanswered and goes to voicemail. “continue” to proceed as normal, “redirect” to redirect the call to the ifMachineUrl, or “hangup” to hangup the call. Please note: ifMachine could detect an answering machine via the tone stream. Therefore, the accuracy is around 90% and may not work in all countries. Default Value: continue. Allowed Value: continue, redirect, hangup.\",\n    \"15-0\": \"ifMachineUrl\",\n    \"15-1\": \"The URL Zang will redirect to if a voicemail machine is detected while the ifMachine=“redirect” attribute is set.\",\n    \"16-0\": \"ifMachineMethod\",\n    \"16-1\": \"The method used to request the ifMachineUrl. Default Value: POST. Allowed Value: POST or GET.\",\n    \"17-0\": \"record\",\n    \"18-0\": \"recordDirection\",\n    \"19-0\": \"recordCallbackUrl\",\n    \"17-1\": \"Specifies if this call should be recorded. Allowed positive values are \\\"true\\\" - any other value will default to \\\"false\\\".\",\n    \"18-1\": \"Specifies which stream of call audio to record. “in” to record the incoming caller audio, “out” to record the outgoing caller audio, or “both” to record all audio on the call. “out” audio can only be captured if an outbound `<Dial>` is performed during the call. “in” blocks any subsequent InboundXML elements until the inbound audio recording is finished (via finishOnKey or timeout). Default Value: both. Allowed Value: in, out, both.\",\n    \"19-1\": \"URL where some parameters specific to the recording will be sent for further processing.\"\n  },\n  \"cols\": 2,\n  \"rows\": 20\n}\n[/block]\nThe following `<Dial>` specific parameters are also forwarded to the callbackUrl and action URL.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Attribute\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"DialCallStatus\",\n    \"0-1\": \"Status of the dial. May be completed, busy, no-answer, failed, or canceled.\",\n    \"1-0\": \"DialCallSid\",\n    \"1-1\": \"The call sid of the outgoing dial.\",\n    \"2-0\": \"DialCallDuration\",\n    \"2-1\": \"The length of the dialed call in seconds.\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\nThe following parameters are also forwarded to the heartbeatUrl.\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"ElapsedTime\",\n    \"0-1\": \"The elapsed time of the dialed call in seconds.\",\n    \"1-0\": \"AnsweredTime\",\n    \"1-1\": \"The date and time the call was answered.\",\n    \"h-0\": \"Attribute\",\n    \"h-1\": \"Description\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"An Error Has Occurred\",\n  \"body\": \"If for any reason you hear \\\"An Application Error Has Occurred\\\" message playing to you while you are on the call that means that your InboundXML document contains issues. In order to resolve issues, please visit _Notifications > Developers_ located in your Zang dashboard.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Nesting\",\n  \"body\": \"In addition to the default `<Response>` element, the `<Dial>` element cannot be nested within any other verbs besides the default `<Response>` element. The `<Number>`, `<Conference>`, `<User>` and `<Sip>` elements can be nested within the `<Dial>` element.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Examples\"\n}\n[/block]\nThe InboundXML below will dial the nested number and send the action parameters to the given URL.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<Response>\\n    <Dial action=\\\"http://webhookr.com/zang-inbound-dial-example\\\" method=\\\"GET\\\">(555)555-5555</Dial>\\n</Response>\",\n      \"language\": \"xml\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"dial","type":"basic","title":"<Dial>"}
The `<Dial>` element starts an outgoing dial from the current call. Once the dial is complete, the next element in the InboundXML document will be processed unless the action attribute is set. If the action attribute is set, the result of the dial is submitted as a GET or POST (depending on the method attribute) to the action URL, and the call will continue using the InboundXML in said URL. By default, the outgoing call will timeout after 30 seconds if it is not answered. However, the timeout attribute can be used to set a custom time. The length of the call is limited by the timeLimit attribute, which is 4 hours (14400 seconds) by default. Setting the hangupOnStar attribute to ‘true’ will allow the original call to terminate the outgoing call without having to hangup by dialing ‘*’. The original call then continues with the current InboundXML document, or if a URL was passed, the response from the action attribute. The callerId attribute can be set to any number, and will default to the caller id of the original caller. The number to be dialed should be nested within the `<Dial>` element. For more options, use the `<Number>`, `<Sip>` or `<Conference>` elements instead of a simple phone number. [block:parameters] { "data": { "h-0": "Attribute", "h-1": "Description", "0-0": "action", "0-1": "URL where some parameters specific to `<Dial>` will be sent for further processing. The calling party can be redirected here upon the hangup of the B leg caller.", "1-0": "method", "1-1": "Method used to request the action URL. Default Value: POST. Allowed Value: POST or GET.", "2-0": "timeLimit", "2-1": "The duration in seconds a call made through `<Dial>` should occur for before ending. Default Value: 14400. Allowed Value: integer greater than or equal to 1.", "3-0": "callerId", "3-1": "Number to display as calling. Defaults to the ID of phone being used.", "4-0": "hideCallerId", "4-1": "Boolean value specifying if the caller ID should be hidden or not. Default Value: false. Allowed Value: true or false.", "5-0": "dialMusic", "5-1": "URL to an InboundXML document to be executed in place of the call ringtone (a `<Say>` or `<Play>` would be appropriate in this document).", "6-0": "callbackUrl", "6-1": "URL requested when the dialed call connects and ends. Note that this URL only receives parameters containing information about the call, the call does not execute XML given as a callbackUrl.", "7-0": "callbackMethod", "7-1": "Method used to request the callback URL. Default Value: POST. Allowed Value: POST or GET.", "8-0": "confirmSound", "8-1": "The URL that Zang should reach out to when the called party answers. The URL should return InboundXML containing `<Play>`, `<Pause>`, and/or `<Say>` elements only. Any other elements will be ignored.", "9-0": "digitsMatch", "9-1": "Specifies digits that Zang should listen for and send to the callbackUrl if a caller inputs them. Separate additional digits or digit patterns with a comma. Allowed Value: Pattern made up of the digits 0-9, #, or *.", "10-0": "straightToVm", "10-1": "Boolean value specifying if call should be redirected to voicemail immediately. Note: only works if dialing TO a mobile number. Default Value: false. Allowed Value: true or false.", "11-0": "heartbeatUrl", "11-1": "A URL Zang can request every 60 seconds during the call to notify of elapsed time and pass other general information.", "12-0": "heartbeatMethod", "12-1": "Method used to request the heartbeatUrl. Default Value: POST. Allowed Value: POST or GET.", "13-0": "forwardedFrom", "13-1": "Specifies the number to list the call as forwarded from.", "14-0": "ifMachine", "14-1": "Specifies how Zang should handle this dial if the receiving phone number is unanswered and goes to voicemail. “continue” to proceed as normal, “redirect” to redirect the call to the ifMachineUrl, or “hangup” to hangup the call. Please note: ifMachine could detect an answering machine via the tone stream. Therefore, the accuracy is around 90% and may not work in all countries. Default Value: continue. Allowed Value: continue, redirect, hangup.", "15-0": "ifMachineUrl", "15-1": "The URL Zang will redirect to if a voicemail machine is detected while the ifMachine=“redirect” attribute is set.", "16-0": "ifMachineMethod", "16-1": "The method used to request the ifMachineUrl. Default Value: POST. Allowed Value: POST or GET.", "17-0": "record", "18-0": "recordDirection", "19-0": "recordCallbackUrl", "17-1": "Specifies if this call should be recorded. Allowed positive values are \"true\" - any other value will default to \"false\".", "18-1": "Specifies which stream of call audio to record. “in” to record the incoming caller audio, “out” to record the outgoing caller audio, or “both” to record all audio on the call. “out” audio can only be captured if an outbound `<Dial>` is performed during the call. “in” blocks any subsequent InboundXML elements until the inbound audio recording is finished (via finishOnKey or timeout). Default Value: both. Allowed Value: in, out, both.", "19-1": "URL where some parameters specific to the recording will be sent for further processing." }, "cols": 2, "rows": 20 } [/block] The following `<Dial>` specific parameters are also forwarded to the callbackUrl and action URL. [block:parameters] { "data": { "h-0": "Attribute", "h-1": "Description", "0-0": "DialCallStatus", "0-1": "Status of the dial. May be completed, busy, no-answer, failed, or canceled.", "1-0": "DialCallSid", "1-1": "The call sid of the outgoing dial.", "2-0": "DialCallDuration", "2-1": "The length of the dialed call in seconds." }, "cols": 2, "rows": 3 } [/block] The following parameters are also forwarded to the heartbeatUrl. [block:parameters] { "data": { "0-0": "ElapsedTime", "0-1": "The elapsed time of the dialed call in seconds.", "1-0": "AnsweredTime", "1-1": "The date and time the call was answered.", "h-0": "Attribute", "h-1": "Description" }, "cols": 2, "rows": 2 } [/block] [block:callout] { "type": "danger", "title": "An Error Has Occurred", "body": "If for any reason you hear \"An Application Error Has Occurred\" message playing to you while you are on the call that means that your InboundXML document contains issues. In order to resolve issues, please visit _Notifications > Developers_ located in your Zang dashboard." } [/block] [block:callout] { "type": "info", "title": "Nesting", "body": "In addition to the default `<Response>` element, the `<Dial>` element cannot be nested within any other verbs besides the default `<Response>` element. The `<Number>`, `<Conference>`, `<User>` and `<Sip>` elements can be nested within the `<Dial>` element." } [/block] [block:api-header] { "type": "basic", "title": "Examples" } [/block] The InboundXML below will dial the nested number and send the action parameters to the given URL. [block:code] { "codes": [ { "code": "<Response>\n <Dial action=\"http://webhookr.com/zang-inbound-dial-example\" method=\"GET\">(555)555-5555</Dial>\n</Response>", "language": "xml" } ] } [/block]