# 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 [Media Upload Precheck](media_precheck.md) 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 [Media Reference Send](media_ref_send.md) web service. To implement receiving of media messages via web services, you will need to implement [Fetch Messages](fetch_messages.md) 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 [global](../reporting/intro.md#global-params) and [account](../reporting/intro.md#account-params) scopes. There are also additional, service-specific parameters for this service: ### `to` { .reference-entry } 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](../account/account.md) for more details. ### `description` { .reference-entry } The optional description of the media to be uploaded. The string will be encoded in UTF-8. ### `media_size` { .reference-entry } The size in bytes of the binary representation of the media. ### `content_type` { .reference-entry } Content type of the media. Either *image/jpeg* or *video/mp4*. ## Configuration The following [Account XML](../account/account.md) keys are relevant for Send Message web service configuration: ### `genericMediaUploadUrl` { .reference-entry } Contains the URL, including URL scheme, of the web service, possibly also with query string. ``` https://example.com/upload_message?from=%account[username]%&password=%account[password]%&to=%sms_to%&media_size=456000 ``` ### `genericMediaUploadMethod` { .reference-entry } You can use either POST or PUT methods to upload the media. The default is POST. ```xml put ``` ### `genericMediaUploadMultipartData` { .reference-entry } 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. ``` from=%account[username]%&password=%account[password]%&to=%sms_to%&file=%media_content% ``` It will result in the following multipart body: ``` --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` { .reference-entry } 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. ```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: ```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: ```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: ```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: ```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: ```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: ```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" } ```