.. _media_ref_send_webservice: 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 sending of the message with media reference and preview only. You also need to implement :ref:`media_upload_webservice` web service. To implement receiving of media messages via web services, you will need to implement :ref:`fetch_messages_webservice` web service and be sure to include media related fields. .. attention:: media related fields to be specified in :ref:`fetch_messages_webservice` web service soon Parameters ---------- Parameter templates for Media Reference Send web service can use any variables from :ref:`global-params` and :ref:`account-params` 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 :ref:`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 :ref:`account-xml` keys are relevant for Send Message web service configuration: ``genericMediaRefSendUrl`` ~~~~~~~~~~~~~~~~~~~~~~~~~~ This webservice follows the successful completion of :ref:`media_upload_webservice`. If this web service is not defined the message is delivered as a multipart message via SIP. .. code-block:: none 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. .. code-block:: xml 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): .. code-block:: none 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 ): .. code-block:: 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. .. code-block:: xml 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: .. code-block:: http 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: .. code-block:: http 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: .. code-block:: http 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 Not enough credit POST method, JSON ~~~~~~~~~~~~~~~~~ request: .. code-block:: http 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: .. code-block:: http 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: .. code-block:: http 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" }