Personal tools

switchvox.call

From SwitchvoxExtendAPI

Jump to: navigation, search

Contents

Description

Allows external applications to originate phone calls via the PBX. These phone calls can be from extension to extension, extension to an outside phone number, or even connecting two external phone numbers together.

Arguments

See the Constructing Requests page to learn how to use arguments in requests.
Name Required Type Default Description
dial_first required number This is the number you want to ring first.
dial_second required number After the dial_first number had been called and answered this number will then be called. If the dial_first number is not answered then this number will not be called.
dial_as_account_id required number This defines which account's outgoing call rules and call api settings should be used when placing the calls.
caller_id_name optional string PBX Sets the name of the caller ID on the call to the dial_first number. If you are originating the call to your extension is is helpful to set the caller id to remind you who is calling. The caller id number is automatically set to the dialed number. Can only be 20 characters max. Changing the caller id may not be supported on outgoing calls
variables
variable
optional string Allows you to set the value of a variable in your IVR. First, define a variable in your IVR and name it something like "balance". Then set a variable parameter with the name or the variable equal to the new value. Example: balance=300. Then if you dial an IVR that uses that variable it will be set with the value from your api call.
timeout optional integer 30 Determines how long in seconds to ring the first number before timing out the call. Possible values : 0-999.
ignore_user_api_settings optional boolean 0 Set this parameters if you don't want your dial_first and dial_second numbers to be modified by the user's call api settings. Example: Don't prefix a 9 when the calling number is 10 digits. Possible values : 0 or 1.
ignore_user_call_rules optional boolean 0 Set this variable if do not want the ringing call to follow the extension's call rules. By default, if the dial_first number is an extension it will follow whatever call rules the extension has setup (ie: go to voicemail, cascade, etc).
timeout_second_call optional integer 30 Determines how long in seconds to ring the second number before timing out the call. Possible values : 0-999.
auto_answer optional boolean 0 Set auto_answer on the first call. This call will go directly to speaker phone.


Example Requests & Responses

Please see the API Request and Response Format section for more information on various request encodings.

Example One

Request

Originates a call to an external number, then dials extension 800 with a caller_id_name and a variable.

<request method="switchvox.call">
	<parameters>
		<dial_first>5551112222</dial_first>
		<dial_second>800</dial_second>
		<dial_as_account_id>1106</dial_as_account_id>
		<variables>
			<variable>balance=300</variable>
		</variables>
		<caller_id_name>David Podolsky</caller_id_name>
		<ignore_user_call_rules>1</ignore_user_call_rules>
	        <timeout_second_call>15</timeout_second_call>
	        <auto_answer>1</auto_answer>
	</parameters>
</request>

Response

Returned information with the success of the call.

<response method="switchvox.call">
	<result>
		<call_info dialed_first="915551112222" dialed_second="800" >
			<variables>
				<ivr_variable id="3" name="balance" status="exists" />
			</variables>
		</call_info>
	</result>
</response>


Error Codes

See the Error Code Formatting section to see the xml structure when an error is returned.
See the Generic Error Codes section to see a list of general fault codes that may be returned.
Code Description
17769 Invalid ignore_user_api_settings. Value must be either a 1 or a 0.
10014 Invalid account_id (%s). Account_ids may only contain digits.
54222 Invalid phone number or extension for parameter dial_second. Number must only contain digits,*,or #.
35561 Invalid caller id name. Caller id name may only contain alphanumeric characters,spaces,_,or &.
17769 Invalid ignore_user_call_rules. Value must be either a 1 or a 0.
84904 Invalid variable format for parameter (%s). Variable format must be VARIABLE_NAME=VARIABLE_VALUE.
54222 Invalid phone number or extension for parameter dial_first. Number must only contain digits,*,or #.
75233 Invalid timeout. Must be a number between 0 and 999.
77427 Invalid dial as extension. That extension does not exist in the system or is an invalid type. Please choose a valid SIP,Analog,or Virtual extension.
41591 Your call failed to connect (Originate failed). This fault is usually caused by entering an invalid extension or phone number that can't be reached.