HTTP API scripts
Outbound calling
Outbound video and voice calls can be initiated by an HTTP GET request to
http://gateway.vivatel.com.au/api/callOutbound.php
with the following parameters.
| account |
The name of the calling account, e.g. megacorp01
|
| password |
The password of the calling account.
|
| remotePhone |
The phone number of the landline or mobile being called,
e.g. 0401234567 or 0291234567, or an internet address
such as sip:600@us.voxalot.com or
http://livestream.org/camera.asf. Note that if no area
code is provided for a landline number, it defaults to 03.
Note also that full international format numbers can be used, e.g.
61401234567, but international numbers will only be called
if there is a prior arrangement with Vivatel. Internet addresses must
refer to either a SIP address or a streaming audio or video URL.
|
| localPhone |
The phone number to call from. This is an optional parameter. If
specified, the number must be in the range 03991093xx and,
apart from 0399109300, must be owned by the sending account.
If this parameter is not specified or is left blank, the calling
number's caller-ID information will be withheld..
|
| type |
The type of call to make, either V (video) or A
(audio/voice). This is an optional parameter that defaults to V.
|
| contentURL |
The URL of a VIXML document that will be displayed when the
call is answered, e.g. http://gateway/megacorp01/home.php
Note that this parameter cannot be specified at the same time as the
conferenceId parameter, since the two behaviours are mutually
exclusive, nor can it be used when remotePhone refers to an
internet address.
|
| conferenceId |
The ID of the conference that this call will be connected to after
it is answered. Note that this parameter cannot be specified at the
same time as the contentURL parameter, since the two behaviours
are mutually exclusive. Note also that this parameter is mandatory when
remotePhone refers to an internet address.
|
| delay |
The delay, in seconds, before the call is made, allowing calls
to be prescheduled. This is an optional parameter that defaults to 0.
|
| id |
An ID that will be assigned to the call. When the call is completed,
this ID will be passed to the notification URL below. This is an
optional parameter that defaults to 0.
|
| notificationURL |
The URL that will be called when a call is completed, with the
parameters described below. If no notification URL is specified and
the call fails, an e-mail will be sent to the account's technical
contact. This is an optional parameter.
|
Calls to the API return a single line of status information, as follows.
| 00 OK |
| 01 Invalid password |
| 02 Invalid content URL |
| 03 Invalid remote phone number |
| 04 Invalid local phone number |
| 05 Invalid call type |
| 06 Invalid notification URL |
| 07 Invalid conference ID |
| 99 Internal database error |
When the notificationURL parameter above is specified, the
URL is called when the call is completed. The following HTTP GET
variables are passed through.
| account |
The name of the calling account. |
| remotePhone |
The phone number that was called, in international format, e.g.
61401234567
|
| localPhone |
The calling phone number, in international format, e.g.
61399109300
|
| type |
The type of call, either V (video) or A (audio/voice).
|
| contentURL |
The URL of the VIXML content, or the conference ID if that was
used instead.
|
| id |
The ID that was assigned to the outbound call.
|
| status
|
One of OK, RJ, EN, NA, SO,
FA, NV, or SY. Details below.
|
| duration
|
The duration of the call, in seconds, when the status is OK
e.g. 31.5
|
The status variable passed to the notification URL can be one of
the following.
| OK |
The call was successfully completed. |
| RJ |
The call was rejected. Sometimes calls are rejected by the recipient
because they don't want to answer the call, and sometimes they are
rejected by the network because the phone is not able to accept
video calls. The safest response is to call back later in voice mode.
|
| NA |
There was no answer. The phone rang but there was no answer within
the network's default answering period.
|
| SO |
The phone was switched off or out of range of the network.
|
| EN |
The phone number was engaged.
|
| FA |
The call failed because the phone number could not be dialled.
Possible reasons include a non-existent or unreachable phone number.
Very occasionally the network will respond with an unallocated
(unassigned) number when the number is actually correct, so if
the FA code is returned for a number that has worked in the
past, assume that its a temporary network problem and try again.
|
| NV |
The call was rejected because the recipient is not able to accept
video calls. The typical response is to call back in voice mode.
|
| SY |
An internal system error occurred. Please notify Vivatel if these
occur.
|
Transcoding video clips
For the best quality, video files should be transcoded into separate audio
and video files encoded specifically for 3G handsets. Normally this is
carried out manually via the Content Management System (CMS), but
sometimes it is necessary to perform the conversion automatically.
A video file can be transcoded with an HTTP POST to
http://gateway.vivatel.com.au/api/batchTranscode.php
with the following parameters.
| body |
The contents of the video file, encoded in base64 format.
|
| contentType |
The content type of the video file, e.g. video/quicktime
|
| fps |
The target frame rate of the transcoded video, in frames per second.
This is an optional parameter that defaults to 10.
|
| bps |
The target bit rate of the transcoded video, in bits per second.
This is an optional parameter that defaults to 47000.
|
The first line of output from the URL is either OK, or
ERROR: followed by the reason it failed.
If the first line is OK, the second line will contain a single
number specifying the playback rate of the converted video file, in
bytes per second. The third and fourth lines will contain the contents
of the converted video and audio files, respectively, encoded in base64
format. The audio will be encoded in mp3 format.
An example using this script to convert captured video clips can
be found here.
Get the list of active calls
The list of all active calls for an account can be retrieved with
an HTTP GET to
http://gateway.vivatel.com.au/api/getActiveCalls.php
with the following parameters.
| account |
The name of the account, e.g. megacorp01
|
| password |
The password of the account.
|
The output contains a list of all the account's calls in progress in
XML format, as shown below.
<calls>
<call>
<id>767351</id>
<type>VO</type>
<localNumber>61394132424</localNumber>
<remoteNumber>61438932345</remoteNumber>
</call>
<call>
<id>767353</id>
<type>VI</type>
<localNumber>61394136111</localNumber>
<remoteNumber>61284234321</remoteNumber>
</call>
</calls>
Terminate active call
A call in progress belonging to an account can be terminated with an
HTTP GET to
http://gateway.vivatel.com.au/api/terminateCall.php
with the following parameters.
| account |
The name of the account, e.g. megacorp01
|
| password |
The password of the account.
|
| id |
The ID of the call to terminate. This corresponds to the id
parameter of <call> items returned by the
getActiveCalls.php call.
|
Calls to the API return a single line of status information, as follows.
| 00 OK |
| 01 Invalid password |
| 02 No such call |
| 99 Internal database error |
|
