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, 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, sometimes they are rejected
by the network because the phone is switched off or the recipient is
not able to accept video calls. The safest response is to call back
later in voice mode.
|
| EN |
The phone number was engaged. The typical response is to call back later.
|
| FA |
The call failed because the phone number could not be dialled.
Possible reasons include a non-existent or unreachable phone number.
|
| 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.
|
