Skip to content

Media reference send

Warning

Not supported by the client yet

Overview

This web service can be used to send message containing a reference to the uploaded media and also include a small jpeg preview of the media.

Note

This web service handles sending of the message with media reference and preview only. You also need to implement Media Upload web service. To implement receiving of media messages via web services, you will need to implement Fetch Messages web service and be sure to include media related fields.

Attention

Media related fields to be specified in Fetch Messages web service soon.

Parameters

Parameter templates for Media Reference Send web service can use any variables from global and account scopes. There are also additional, service-specific parameters for this service:

sms_to

This parameter will be replaced with the address of desired recipient. It will be a phone number or SIP address where the message is to be delivered. The exact format of this address can be tweaked using Number Rewriting. See Account XML for more details.

Note

Acrobits apps support sending messages to multiple recipients. In this case, the web service will be called for every recipient separately.

description

The optional description of the media to be uploaded. The string will be encoded in UTF-8.

preview_width

The width of the preview image in pixels.

preview_height

The height of the preview image in pixels.

preview_content_type

The content-type of the preview. Always image/jpeg.

preview_content

Base64 encoded preview image data.

media_url

The URL returned from the media upload web service from where the actual media can be downloaded.

media_content_type

The content-type of the media.

Note

We currently upload either image/jpeg or video/mp4.

Configuration

The following Account XML keys are relevant for Send Message web service configuration:

genericMediaRefSendUrl

This webservice follows the successful completion of Media Upload. If this web service is not defined the message is delivered as a multipart message via SIP.

https://example.com/send_media_message?from=%account[username]%&password=%account[password]%&to=%sms_to%

genericMediaRefSendMethod

You can use either GET, HEAD, POST or PUT methods. The default is GET if genericMediaRefSendPostData is empty and POST if genericMediaRefSendPostData is non-empty.

post

genericMediaRefSendPostData

If filled in, and the genericMediaRefSendMethod is unspecified, the app will use POST request to send the message. If the method is PUT, the app will do the PUT request with this data. If the method is either GET or HEAD, this parameter is not used.

Example (for application/x-www-form-urlencoded):

from=%account[username]%&password=%account[password]%&to=%sms_to%&description=%description%&w=%preview_width%&h=%preview_height%&pct=%preview_content_type%&pc=%preview_content%&ct=%media_content_type%&url=%media_url%

Example (for application/json):

{   "from"          : "%account[username]%",
    "password"      : "%account[password]%",
    "to"            : "%sms_to%",
    "description"   : "%description%",
    "w"             : "%preview_width%",
    "h"             : "%preview_height%",
    "pct"           : "preview_content_type",
    "pc"            : "preview_content",
    "ct"            : "media_content_type",
    "url"           : "media_url"
}

genericMediaRefSendContentType

Specifies the value of Content-Type header to be sent in the request. If not specified, the app will default to application/x-www-form-urlencoded

genericMediaRefSendCustomHeaders

You can define any custom header you want to send along with the request. If you want to include multiple headers, they need to be newline \n separated.

X-Preview-Width:180
X-Preview-Height:120

Response

The response will be considered successful if the HTTP response code is 2xx.

In case of non-2xx response, the app will check for a "message" field in response body. If present, it will show this string as error message to the user, otherwise some generic error message is shown.

Examples

GET method, XML

request:

GET /send_media_message/?from=johndow&password=12345678&sms_to=%2B15551231234&description=Hello%20World&w=180&h=120&pct=image/jpeg&pc=A64FBB8....7237%3D%3D&ct=video/mp4&url=http%3A%2F%2Fmedia.server.com%2Fvideo_1234567890.mp4 HTTP/1.1
Host: example.com
Connection: close
Cache-Control: max-age=0
User-Agent: CloudSoftphone/1.5.6

success response:

HTTP/1.1 200 OK
Date: Sun, 15 Mar 2015 00:46:17 GMT
Server: Apache/2.4.7 (Ubuntu)
Vary: Accept-Encoding
Content-Length: 0
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive

error response:

HTTP/1.1 402 Payment Required
Date: Sun, 15 Mar 2015 00:46:17 GMT
Server: Apache/2.4.7 (Ubuntu)
Vary: Accept-Encoding
Content-Length: 123
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Content-Type: text/xml

<response><message>Not enough credit</message></response>

POST method, JSON

request:

POST /send_message/ HTTP/1.1
Host: example.com
Connection: close
Cache-Control: max-age=0
User-Agent: CloudSoftphone/1.5.6
Content-Type: application/json
Content-Length: 183


{
    "from"        : "johndow",
    "password"    : "12345678",
    "sms_to"      : "+1(555)123-1234",
    "description" : "Hello World",
    "w"           : 180,
    "h"           : 120,
    "pct"         : "image/jpeg",
    "pc"          : "A64FBB8....7237%3D%3D=="
    "ct"          : "video/mp4"
    "url"         : "http://media.server.com/video_1234567890.mp4"

}

success response:

HTTP/1.1 200 OK
Date: Sun, 15 Mar 2015 00:46:17 GMT
Server: Apache/2.4.7 (Ubuntu)
Vary: Accept-Encoding
Content-Length: 0
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive

error response:

HTTP/1.1 406 Not Acceptable
Date: Sun, 15 Mar 2015 00:46:17 GMT
Server: Apache/2.4.7 (Ubuntu)
Vary: Accept-Encoding
Content-Type: application/json
Content-Length: 123
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive

{
    "message"        : "Invalid recipient"
}