.. _media_upload_precheck_webservice:

Media Upload Precheck
=====================

.. warning::
    Not supported by the client yet

Overview
--------

This optional web service can be used to verify that the server is likely to accept the subsequent media upload without actually uploading any media. This can be useful to verify user credentials, user balance, media content type and media size.

.. note::

    This web service is optional. If not specified, the media will be uploaded directly using :ref:`media_upload_webservice` web service. This can be frustrating to the user though to upload a 300MB video to the server just to find out that the size limit is 100MB. 


Parameters
----------

Parameter templates for Media Upload Precheck 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:

``genericMediaUploadPrecheckUrl``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    Contains the URL, including URL scheme, of the web service, possibly also with query string. 

    .. code-block:: none

        https://example.com/upload_message_precheck?from=%account[username]%&password=%account[password]%&to=%sms_to%&media_size=456000
    
``genericMediaUploadPrecheckMethod``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

    .. code-block:: xml

        get

``genericMediaUploadPrecheckPostData``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    If filled in, and the ``genericMediaUploadPrecheckMethod`` 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%&size=%media_size%

    Example ( for  application/json ):

    .. code-block:: json

        { "from" : "%account[username]%", "password" : "%account[password]%", "to" : "%sms_to%", "size" : "%media_size%" }

``genericMediaUploadPrecheckContentType``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    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``

``genericMediaUploadPrecheckCustomHeaders``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    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.

    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
--------

GET method, XML
~~~~~~~~~~~~~~~

request:

 .. code-block:: http

    GET /upload_media_precheck/?from=johndow&password=12345678&sms_to=%2B15551231234&size=50000 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 413 Request Too Large
    Date: Sun, 15 Mar 2015 00:46:17 GMT
    Server: Apache/2.4.7 (Ubuntu)
    Vary: Accept-Encoding
    Content-Length: 77
    Keep-Alive: timeout=5, max=100
    Connection: Keep-Alive
    Content-Type: text/xml

    <response><message>Too big a file. The limit is 200000.</message></response>

POST method, JSON
~~~~~~~~~~~~~~~~~

request:

 .. code-block:: http

    POST /upload_media_precheck/ 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: 153


    {
        "from"        : "johndow",
        "password"    : "12345678",
        "sms_to"      : "+1(555)123-1234",
        "size"        : "50000"
    }

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"
    }