.. _media_upload_webservice: Media Upload ============ .. warning:: Not supported by the client yet Overview -------- This web service can be used to upload media onto the media server of the Service Provider. .. note:: This web service handles media upload only. You can also optionally implement :ref:`media_upload_precheck_webservice` web service. If you want to also implement sending of the message with the reference to the uploaded media via a web service (as opposed to using SIMPLE), you need to implement :ref:`media_ref_send_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 nodes. The content type of the request can be either POST or PUT, the content type is always multipart/form-data. Parameters ---------- Parameter templates for Media Upload 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: 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. description ~~~~~~~~~~~ The optional description of the media to be uploaded. The string will be encoded in UTF-8. media_size ~~~~~~~~~~ The size in bytes of the binary representation of the media. content_type ~~~~~~~~~~~~ Content type of the media. Either *image/jpeg* or *video/mp4*. Configuration ------------- The following :ref:`account-xml` keys are relevant for Send Message web service configuration: ``genericMediaUploadUrl`` ~~~~~~~~~~~~~~~~~~~~~~~~~ Contains the URL, including URL scheme, of the web service, possibly also with query string. .. code-block:: none https://example.com/upload_message?from=%account[username]%&password=%account[password]%&to=%sms_to%&media_size=456000 ``genericMediaUploadMethod`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can use either POST or PUT methods to upload the media. The default is POST. .. code-block:: xml put ``genericMediaUploadMultipartData`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can define the individual parts of the multipart data in **application/x-www-form-urlencoded** style. The parts are separated by **&**. The part containing **%media_content%** parameter is special. It will also contain **filename=** in **Content-Disposition** header, **Content-Type** header with actual media content type and binary representation of the media. .. code-block:: none from=%account[username]%&password=%account[password]%&to=%sms_to%&file=%media_content% It will result in the following multipart body: .. code-block:: none --boundary Content-Disposition: form-data; name=from johndow --boundary Content-Disposition: form-data; name=password 12345678 --boundary Content-Disposition: form-data; name=description johndow --boundary Content-Disposition: form-data; name=file; filename=helloworld.mp4 Content-Type: video/mp4 ....binary...data...here... --boundary-- ``genericMediaUploadCustomHeaders`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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-Media-Size:875000 X-Description:Hello World! Response -------- The response will be considered successful if the HTTP response code is 2xx and it contains "media_url" field in the response body. In case of non-2xx response, the app will check for a "message" field in the response body. If present, it will show this string as error message to the user, otherwise some generic error message is shown. Examples -------- POST method, XML response ~~~~~~~~~~~~~~~~~~~~~~~~~ request: .. code-block:: http POST /upload_media HTTP/1.1 Host: example.com Connection: close Cache-Control: max-age=0 User-Agent: CloudSoftphone/1.5.6 Content-Type: multipart/form-data; charset=utf-8; boundary="boundary" Content-Length: 456789 --boundary Content-Disposition: form-data; name=from johndow --boundary Content-Disposition: form-data; name=password 12345678 --boundary Content-Disposition: form-data; name=description johndow --boundary Content-Disposition: form-data; name=file; filename=helloworld.mp4 Content-Type: video/mp4 ....binary...data...here... --boundary-- 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: 88 Keep-Alive: timeout=5, max=100 Connection: Keep-Alive Content-Type: text/xml http://media.server.com/video_1234567890.mp4 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 PUT method, JSON response ~~~~~~~~~~~~~~~~~~~~~~~~~ request: .. code-block:: http PUT /upload_media HTTP/1.1 Host: example.com Connection: close Cache-Control: max-age=0 User-Agent: CloudSoftphone/1.5.6 Content-Type: multipart/form-data; charset=utf-8; boundary="boundary" Content-Length: 456789 --boundary Content-Disposition: form-data; name=from johndow --boundary Content-Disposition: form-data; name=password 12345678 --boundary Content-Disposition: form-data; name=description johndow --boundary Content-Disposition: form-data; name=file; filename=helloworld.mp4 Content-Type: video/mp4 ....binary...data...here... --boundary-- 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-Type: application/json Content-Length: 76 Keep-Alive: timeout=5, max=100 Connection: Keep-Alive { "media_url" : "http://media.server.com/video_1234567890.mp4" } 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: 54 Keep-Alive: timeout=5, max=100 Connection: Keep-Alive { "message" : "Invalid recipient" }