Cast's Messages
===============

This part of documentation cover all methods related with Cast's messages.

* :ref:`Create-cast-message`
* :ref:`Update-cast-message`
* :ref:`List-cast-messages-from-topic`
* :ref:`Cast-messages-detail`
* :ref:`Cast-messages-follow`
* :ref:`Cast-messages-delete`


.. _Create-cast-message:

Create new Cast's Message or comment
------------------------------------

+-----------+-------------------------------------------------------------------+--------+
| OPERATION | URL                                                               | METHOD |
+===========+===================================================================+========+
|    ADD    | | [1] http://URL/<container>/<cast-topic>                         |  POST  |
+-----------+-------------------------------------------------------------------+--------+

This is method which you shoudl use to add new massege or comment to already
existed message.

Arguments - you need send them POST parameters:
 * *body*: message/comment body *OPTIONAL*
 * *topic_uid*: one topic UID or list of topic UIDs, where message should be
   added. *It's ignored, when you send also uid argument!*
 * *uid*: message UID - ONLY IF YOU WANT TO ADD MESSAGE AS COMMENT TO THIS
   MESSAGE! *OPTIONAL*
 * *people*: list of people IDs - for sharing/visibility set *OPTIONAL*
 * *eff_date*: visibility date "from" *OPTIONAL*
 * *exp_date*: visibility date "to" *OPTIONAL*
 * *files*: uid of files wich you want attach to message. *OPTIONAL*
 * *references*: uid of objects wich you want attach to message *OPTIONAL*
 * *with_comments*: true/1 - show messgaes with comments *OPTIONAL*

.. note::

    Parameter *uid* is required if you want to add comment to already existed
    message.

.. note::

    Files and references, shoudl be send just as list (separated by coma) of
    objects UIDs. So first you need add file/object by basic JsonAPI, and then
    add UIDs in *files* (like: 8907106efd954d91b6f9f08b187d18dc,ca6bd7483a104f2ebd790b3a3a778fd6,...).


How to call:
* Send in header: Accept: application/json
* POST request to: http://127.0.0.1:8080/Plone/<container>/<cast-topic>
* BODY (content):

.. code-block:: json

    {
        "body": "Content of your message",
        ...  // rest of yor parameters
    }



.. _Update-cast-message:

Update Cast's Message or comment
--------------------------------

+-----------+----------------------------------------------------------------------------+--------+
| OPERATION | URL                                                                        | METHOD |
+===========+============================================================================+========+
|    ADD    | | [1] http://URL/<container>/<cast-topic>/message                          | PATCH  |
+-----------+----------------------------------------------------------------------------+--------+

This is method which you shoudl use to add new massege or comment to already
existed message.

POST Arguments - you need send them POST parameters:
 * *uid*: message UID *REQUIRED*
 * *body*: message/comment body *OPTIONAL*
 * *eff_date*: visibility date "from" *OPTIONAL*
 * *exp_date*: visibility date "to" *OPTIONAL*
 * *files*: uid of files wich you want attach to message. *OPTIONAL*
 * *references*: uid of objects wich you want attach to message *OPTIONAL*
 * *with_comments*: true/1 - show messgaes with comments *OPTIONAL*

How to call:
* Send in header: Accept: application/json
* PATCH request to: http://127.0.0.1:8080/Plone/<container>/<cast-topic>/message
* BODY (content):

.. code-block:: json

    {
        "body": "Content of your message",
        ...  // rest of yor parameters
    }

.. _List-cast-messages-from-topic:

List of Cast's Messages from topic
----------------------------------

+-----------+---------------------------------------------------------------+--------+
| OPERATION | URL                                                           | METHOD |
+===========+===============================================================+========+
|   VIEW    | | [1] http://URL/<container>/<cast-topic>                     |  GET   |
+-----------+---------------------------------------------------------------+--------+

GET Arguments:

 * *text*: text for search in message content *OPTIONAL*
 * creator*: creator fullname or ID for grep messages only of this
   member *OPTIONAL*
 * *to_member*: fullname or ID, for search only messages in which this member
   is mentioned (via @...:) *OPTIONAL*
 * *tag*: tage name *OPTIONAL*
 * *content_filter*: for filtering via content. available values: *file*,
   *links*, *images*, *videos*. *OPTIONAL*
 * *date_from*: search messages from date. Timestamp! *OPTIONAL*
 * *date_from*: search messages to date. Timestamp! *OPTIONAL*
 * *added_after*: return messages added after. Timestamp! *OPTIONAL*
 * *readed*: show readed (1, true) or not readed (0, flase) messages *OPTIONAL*
 * *with_comments*: true/1 - show messgaes with comments *OPTIONAL*
 * *offset*: offest - default 0 *OPTIONAL*
 * *limit*: limit - default 20 *OPTIONAL*
 * *top_comments*: only top level of comments (1, true, 0, false) *OPTIONAL*


This method return items in dictionary:

.. code-block:: json

      ...
      "items": {
          "messages": []
          "new_messages": null,
          "modified_messages": null
       },
      ...

In typical way, *new_messages* and *modified_messages* are empty (`null`),
and messages contain messages dicts. If you send in request *added_after*, then
*messages* will be none, and in *new_messages* and *modified_messages* will
contain messages added after *added_after*.
In this case, messages are not returned in tree structure, but as plain list.
You should care about that, how and where you need add messages on frontend
side. If message have *parent_uid* set as `null`, this mean it's just new message.
If *parent_uid* is not `null`, that means, you shoudl add this message as comment
to message with UID *parent_uid*.

.. code-block:: json

    {
       "count": {
          "messages": 4,
          "new_messages": 0,
          "modified_messages": 0
       },
       "pagesize": 20,
       "items": {
          "messages": [
             {
                "raw_text": "foo bar bar foo",
                "uid": "ad8e44dfab2a4e628c35174adb143a36",
                "effective": "1969-12-31T00:00:00+01:00",
                "title": "foo bar bar foo",
                "read": true,
                "text": "foo bar bar foo",
                "portal_type": "Cast Update",
                "created": "2015-12-07T17:02:02+01:00",
                "modified": "2015-12-07T17:02:02+01:00",
                "comments": [],
                "id": "1449504122397463",
                "parent_id": "0",
                "tags": [],
                "images": [],
                "creator": {
                   "fullname": "admin",
                   "UID": "admin",
                   "image": {
                      "URL": "http://127.0.0.1:8080/Plone/portal_memberdata/portraits/admin",
                      "alt": "admin"
                   }
                },
                "parent_uid": null,
                "refs": []
             },
             ...
          ],
          "new_messages": null,
          "modified_messages": null
       },
       "pages": 1,
       "next": null,
       "_runtime": 0.10978913,
       "page": 1,
       "previous": null
    }


.. _Cast-messages-detail:

Cast Message details
--------------------

+-----------+-------------------------------------------------------------------------------------+--------+
| OPERATION | URL                                                                                 | METHOD |
+===========+=====================================================================================+========+
|   VIEW    | | [1] http://URL/<container>/<cast-topic>/message/<MESSAGE_UID>                     |  GET   |
+-----------+-------------------------------------------------------------------------------------+--------+

This method returing details about message with UID define by MESSAGE_UID in URL.

Arguments
 * MESSAGE_UID - message uid *REQUIRED*
 * *with_comments*: true/1 - show messgaes with comments *OPTIONAL*

Result:

.. code-block:: json

    {
       "raw_text": "foo bar bar foo",
       "uid": "ad8e44dfab2a4e628c35174adb143a36",
       "effective": "1969-12-31T00:00:00+01:00",
       "title": "foo bar bar foo",
       "read": true,
       "text": "foo bar bar foo",
       "portal_type": "Cast Update",
       "created": "2015-12-07T17:02:02+01:00",
       "modified": "2015-12-07T17:02:02+01:00",
       "comments": [],
       "id": "1449504122397463",
       "parent_id": "0",
       "tags": [],
       "images": [],
       "_runtime": 0.026704073,
       "creator": {
          "fullname": "admin",
          "UID": "admin",
          "image": {
             "URL": "http://127.0.0.1:8080/Plone/portal_memberdata/portraits/admin",
             "alt": "admin"
          }
       },
       "parent_uid": null,
       "refs": []
    }


.. _Cast-messages-follow:

Following of cast message
--------------------------


+-----------+-----------------------------------------------------------------------------+--------+
| OPERATION | URL                                                                         | METHOD |
+===========+=============================================================================+========+
|   VIEW    | | [1] http://URL/<container>/<cast-topic>/toggle_follow                     |  POST  |
+-----------+-----------------------------------------------------------------------------+--------+

Method for enabling/disabling following message by current loggedin member. FOLLOW shoudl be 1 or 0. 1 means follow, 0 means unfollow.

How to call:
* Send in header: Accept: application/json
* POST request to: http://127.0.0.1:8080/Plone/<container>/<cast-topic>/toggle_follow
* BODY (content):

.. code-block:: json

    {
        "uid": "<message-uid>",
        "follow": 1,
    }


Result:

.. code-block:: json

    {
        "text": "Stop following replies",
        "_runtime": 0.07516098022460938,
        "result": "success",
        "class": "stopFollowMessageAction"
    }


.. code-block:: json

    {
        "text": "You are not following this message.",
        "result": "error",
        "_runtime": 0.017998933792114258
    }

.. code-block:: json

    {
        "text": "Follow message replies",
        "_runtime": 0.07190203666687012,
        "result": "success",
        "class": "startFollowMessageAction"
    }


.. _Cast-messages-delete:

Delete cast message
-------------------

+-----------+-----------------------------------------------------------------------+----------+
| OPERATION | URL                                                                   |  METHOD  |
+===========+=======================================================================+==========+
|   VIEW    | | [1] http://URL/<container>/<cast-topic>/message                     |  DELETE  |
+-----------+-----------------------------------------------------------------------+----------+

Method for deleting cast's messages.

How to call:
* Send in header: Accept: application/json
* DELETE request to: http://127.0.0.1:8080/Plone/<container>/<cast-topic>/message
* BODY (content):

.. code-block:: json

    {
        "uid": "<message-uid>",
    }

Result:

.. code-block:: json

    {
        "_runtime": 0.2651090621948242,
        "success": "Message was successfully removed."
    }
