FamilyWall API

{{>toc}}

h1. Messaging - msg

The messaging API is used to access the messaging section, retrieve the message list, add a new message, edit or delete a conversation... In order to access the messaging API, 

the client shall be already logged and authenticated with a valid session using the log method detailed above. 

h2. Messaging thread list- _msglistThread_

The method msglistThread enables a logged user to retrieve all the conversation threads lists of his account. To date the method returns the entire list without any limit. In 

next version of the method, the client will be able to limit the number of threads returns in the list by sending the number of threads present in the list.

The method returns the list of thread sorted by date, the most recent being the first of the date.

By sending an HTTP request http://yourserver/api?a01call=msglistThread

*Parameters*:

_No parameters_ for this method

*Response*:

<pre><code class="javascript">

{

  "a01":{

    "r":{

      "r":[

        {

          "nbMessage":"2",

          "lastMessage":{

            "mediaIds":[],

            "fromId":"130",

            "creationDate":"2011-07-07T08:40:01.00Z",

            "text":"Kid",

            "toIdsArray":[

              "131",

              "133"

            ],

            "read":"true",

            "threadToken":"1310004700795",

            "messageId":"800"

          }

        },{

          "nbMessage":"2",

          "lastMessage":{

            "mediaIds":[],

            "fromId":"130",

            "creationDate":"2011-07-07T07:50:34.00Z",

            "text":"",

            "toIdsArray":[

              "131",

              "130",

              "133"

            ],

            "read":"true",

            "threadToken":"1310025034708",

            "messageId":"793"

          }

        }

      ]

    },

    "cn":"msglistThread"

  }

}

</code></pre>

The Method response returns the list of thread conversations separated by a _','_ structured as followed:

<pre>

         {

          "nbMessage":"2",    _(number of messages in the thread)_

          "lastMessage":{     _(last message)_

            "mediaIds":[],     _(message url)_

            "fromId":"130",    _(sender profileid, to get name retreive in prfgetprofile)_

            "creationDate":"2011-07-07T07:50:34.00Z", _(message creation date in UTC format - offset shall be calculated with offset)_

            "text":"My message text here", _(Text message)_

            "toIdsArray":[ _(list of recipient profile id to get name retreive in prfgetprofile)_

              "131",

              "130",

              "133"

            ],

            "read":"true", _(boolean read=true, unread=false)_

            "threadToken":"1310025034708", _(thread tokenid, parameters for getthread)_

            "messageId":"793" _(id of the last message)_

          }

</pre>

In case, the method encounter any error, the response is an exeception with specific parameters detailed below.

*Error*:

|*Error Code*|*Type*|*Value*|*Description*|

|FiZClassId|un|501|User is not logged|

h2. Messaging threadview- _msggetthread_

The method _msggetthread_ allows the client to display the content of the conversation

The method returns the list of message sorted by date, the most recent being the first of the date.

By sending an HTTP request http://yourserver/api/msg/getthread?threadToken=1310004700795

*Parameters*:

|*Name*|*Type*|*Description*|

|threadToken|String|threadToken Information|

|Read|Boolean|optional value (default false) to set as read or not the thread|

*Response*:

<pre><code class="javascript">

parseResponse({

  "cn":"msggetthread",

  "feed":[

    {

      "mediaIds":[],

      "fromId":"130",

      "creationDate":"2011-07-07T08:40:01.00Z",

      "text":"Kid",

      "toIdsArray":[

        "131",

        "133"

      ],

      "read":"true",

      "threadToken":"1310004700795",

      "messageId":"800"

    },{

      "mediaIds":[],

      "fromId":"131",

      "creationDate":"2011-07-07T02:11:40.00Z",

      "text":"Keshui",

      "toIdsArray":[

        "131",

        "130",

        "133"

      ],

      "read":"false",

      "threadToken":"1310004700795",

      "messageId":"787"

    }

  ]

});

</code></pre>

The Method response returns the list of messages in a conversation separated by a _','_ structured as followed:

In case, the method encounter any error, the response is an exeception with specific parameters detailed below.

*Error*:

|*Error Code*|*Type*|*Value*|*Description*|

|FizAccountNotFoundInSessionException|un|501|Session is invalid|

|FizApiInvalidParameterException|un|502|invalid token|

|FizApiModelDoesNotExistException|un|503|Object does not exists|

|FizApiModelRightException|un|504|Right exception to use this method|

h2. Messaging thread list- _msglistThread_

The method msglistThread enables a logged user to retrieve all the conversation threads lists of his account. To date the method returns the entire list without any limit. In 

next version of the method, the client will be able to limit the number of threads returns in the list by sending the number of threads present in the list.

The method returns the list of thread sorted by date, the most recent being the first of the date.

By sending an HTTP request http://yourserver/api?a01call=msglistThread

*Parameters*:

_No parameters_ for this method

*Response*:

<pre><code class="javascript">

{

  "a01":{

    "r":{

      "r":[

        {

          "nbMessage":"2",

          "lastMessage":{

            "mediaIds":[],

            "fromId":"130",

            "creationDate":"2011-07-07T08:40:01.00Z",

            "text":"Kid",

            "toIdsArray":[

              "131",

              "133"

            ],

            "read":"true",

            "threadToken":"1310004700795",

            "messageId":"800"

          }

        },{

          "nbMessage":"2",

          "lastMessage":{

            "mediaIds":[],

            "fromId":"130",

            "creationDate":"2011-07-07T07:50:34.00Z",

            "text":"",

            "toIdsArray":[

              "131",

              "130",

              "133"

            ],

            "read":"true",

            "threadToken":"1310025034708",

            "messageId":"793"

          }

        }

      ]

    },

    "cn":"msglistThread"

  }

}

</code></pre>

The Method response returns the list of thread conversations separated by a _','_ structured as followed:

<pre>

         {

          "nbMessage":"2",    _(number of messages in the thread)_

          "lastMessage":{     _(last message)_

            "mediaIds":[],     _(message url)_

            "fromId":"130",    _(sender profileid, to get name retreive in prfgetprofile)_

            "creationDate":"2011-07-07T07:50:34.00Z", _(message creation date in UTC format - offset shall be calculated with offset)_

            "text":"My message text here", _(Text message)_

            "toIdsArray":[ _(list of recipient profile id to get name retreive in prfgetprofile)_

              "131",

              "130",

              "133"

            ],

            "read":"true", _(boolean read=true, unread=false)_

            "threadToken":"1310025034708", _(thread tokenid, parameters for getthread)_

            "messageId":"793" _(id of the last message)_

          }

</pre>

In case, the method encounter any error, the response is an exeception with specific parameters detailed below.

*Error*:

|*Error Code*|*Type*|*Value*|*Description*|

|FiZClassId|un|501|User is not logged|

h2. Messaging count- _msgcount_

The method _msgcount_ allows the client to display the number of messages  after a certain date (by default the last login date)

The method returns the total number of messages received after a date, the number of new messages as well as the number of unread messages. 

By sending an HTTP request http://yourserver/api/msg/count?

*Parameters*:

|*Name*|*Type*|*Description*|

|date|date|date to calculate the message received after the date YYYY-MM-DDThh:mm:ss|

*Response*:

<pre><code class="javascript">

parseResponse({

  "cn":"msgcount",

  "feed":{

    "total":"38",/*total number of messages*/

    "newUnread":"0",/*total number of new messages*/

    "unread":"30",/*total number of unread messages*/

    "date":"2011-07-07T14:51:17.29Z"/*date of the last login*/

  }

});

</code></pre>

The Method response returns the list of messages in a conversation separated by a _','_ structured as followed:

In case, the method encounter any error, the response is an exeception with specific parameters detailed below.

*Error*:

|*Error Code*|*Type*|*Value*|*Description*|

|FizAccountNotFoundInSessionException|un|501|Session is invalid|

|FizApiInvalidParameterException|un|502|invalid token|

|FizApiModelDoesNotExistException|un|503|Object does not exists|

|FizApiModelRightException|un|504|Right exception to use this method|

h2. Messaging count by user- _msgcountbyUser_

The method _msgcountbyUser_ calculates the number of messages of different type sorted by userId (by default the last login date)

The method returns the total number of messages received after a date, the number of new messages as well as the number of unread messages. 

By sending an HTTP request http://yourserver/api/msg/countByUser?

*Parameters*:

|*Name*|*Type*|*Description*|

|date|date|date from which starts the messages count - format 8601 |

*Response*:

<pre><code class="javascript">

parseResponse({

  "cn":"msgcountByUser",

  "feed":{

    "133":{/*ProfileId*/

      "total":"22",

      "newUnread":"0",

      "unread":"19",

      "date":"2011-07-07T15:28:32.22Z"

    },

    "131":{/*ProfileId*/

      "total":"16",

      "newUnread":"0",

      "unread":"11",

      "date":"2011-07-07T15:28:32.22Z"

    }

  }

});

</code></pre>

The Method response returns the list of messages in a conversation separated by a _','_ structured as followed:

In case, the method encounter any error, the response is an exeception with specific parameters detailed below.

*Error*:

|*Error Code*|*Type*|*Value*|*Description*|

|FizAccountNotFoundInSessionException|un|501|Session is invalid|

|FizApiInvalidParameterException|un|502|invalid token|

|FizApiModelDoesNotExistException|un|503|Object does not exists|

|FizApiModelRightException|un|504|Right exception to use this method|

h2. Deleting a message- _msgdelete_

The method enables to delete a message of certain id.

By sending an HTTP request http://yourserver/api/msg/delete?messageId=123244

*Parameters*:

|*Name*|*Type*|*Description*|

|messageid|string|message id number|

*Response*:

<pre><code class="javascript">

TBD

</code></pre>

The Method response returns a boolean *True* (in case of success).

In case, the method encounter any error, the response is an exeception with specific parameters detailed below.

*Error*:

|*Error Code*|*Type*|*Value*|*Description*|

|FizAccountNotFoundInSessionException|un|501|Session is invalid|

|FizApiInvalidParameterException|un|502|invalid token|

|FizApiModelDoesNotExistException|un|503|Object does not exists|

|FizApiModelRightException|un|504|Right exception to use this method|

h2. Deleting a message thread- _msgdeleteThread_

The method enables to delete a thread of messages of certain id.

By sending an HTTP request http://yourserver/api/msg/deleteThread?threadToken=threadtokenid

*Parameters*:

|*Name*|*Type*|*Description*|

|threadtokenid|string|tokenid number|

*Response*:

<pre><code class="javascript">

TBD

</code></pre>

The Method response returns a boolean *True* (in case of success).

In case, the method encounter any error, the response is an exeception with specific parameters detailed below.

*Error*:

|*Error Code*|*Type*|*Value*|*Description*|

|FizAccountNotFoundInSessionException|un|501|Session is invalid|

|FizApiInvalidParameterException|un|502|invalid token|

|FizApiModelDoesNotExistException|un|503|Object does not exists|

|FizApiModelRightException|un|504|Right exception to use this method|

h2. Reading a message- _msgget_

The method enables to read a message of certain id.

By sending an HTTP request http://yourserver/api/msg/get?messageId=messageid

*Parameters*:

|*Name*|*Type*|*Description*|

|messageid|string|messageid number|

*Response*:

<pre><code class="javascript">

parseResponse({

  "cn":"msgget",

  "feed":{

    "mediaIds":[],

    "fromId":"130",

    "creationDate":"2011-07-08T17:26:59.00Z",

    "text":"text here",

    "toIdsArray":[

      "782"

    ],

    "read":"true",

    "threadToken":"1310146015861",

    "messageId":"130_926"

  }

});

</code></pre>

The Method response returns the message content .

In case, the method encounter any error, the response is an exeception with specific parameters detailed below.

*Error*:

|*Error Code*|*Type*|*Value*|*Description*|

|FizAccountNotFoundInSessionException|un|501|Session is invalid|

|FizApiInvalidParameterException|un|502|invalid token|

|FizApiModelDoesNotExistException|un|503|Object does not exists|

|FizApiModelRightException|un|504|Right exception to use this method|

h2. Last Send Message- _msggetlastbysender_

The method returns the last message sent to the logged-in account by the given accountId.

By sending an HTTP request http://yourserver/api/msg/getlastbysender?accountId=accountid

*Parameters*:

|*Name*|*Type*|*Description*|

|accountid|string|accountid number|

*Response*:

<pre><code class="javascript">

parseResponse({

  "cn":"msggetlastbysender",

  "feed":{

    "mediaIds":[],

    "fromId":"130",

    "creationDate":"2011-07-08T17:26:59.00Z",

    "text":"text here",

    "toIdsArray":[

      "782"

    ],

    "read":"true",

    "threadToken":"1310146015861",

    "messageId":"130_926"

  }

});

</code></pre>

The Method response returns the last message (may be null) sent by the given accountId.

In case, the method encounter any error, the response is an exeception with specific parameters detailed below.

*Error*:

|*Error Code*|*Type*|*Value*|*Description*|

|FizAccountNotFoundInSessionException|un|501|Session is invalid|

|FizApiInvalidParameterException|un|502|invalid token|

|FizApiModelDoesNotExistException|un|503|Object does not exists|

|FizApiModelRightException|un|504|Right exception to use this method|

h2. Change Read status of a specific thread- _msgmarkThread_

The method change a thread as read or as unread.

By sending an HTTP request http://yourserver/api/msg/markThread?threadToken=1310146015861&read=true

*Parameters*:

|*Name*|*Type*|*Description*|

|threadToken|String|threadToken Information|

|Read|Boolean|value to set as read or not the thread|

*Response*:

<pre><code class="javascript">

parseResponse({

  "cn":"msgmarkThread",

  "feed":"true"

});

</code></pre>

The Method response returns a Boolean (always true).

In case, the method encounter any error, the response is an exeception with specific parameters detailed below.

*Error*:

|*Error Code*|*Type*|*Value*|*Description*|

|FizAccountNotFoundInSessionException|un|501|Session is invalid|

|FizApiInvalidParameterException|un|502|invalid token|

|FizApiModelDoesNotExistException|un|503|Object does not exists|

|FizApiModelRightException|un|504|Right exception to use this method|

h2. Sending a message- _msgsend_

The method send a new message to a recipient user as well as reply or forward an existing thread.

By sending an HTTP request http://yourserver/api/send?to=accountid&toName=dad&text=test%20%20message

*Parameters*:

|*Name*|*Type*|*Description*|

|to|String|Recipient Account Id may be multiple separated by "," or ";". may be empty|

|toName|String|Recipient Account Id may be multiple separated by "," or ";" may be empty|

|threadToken|String|associate a thread messageid in case of a forward or a reply|

|text|string|text of the message|

|file|binary or url|value to set as read or not the thread|

*Response*:

<pre><code class="javascript">

{

  "cn":"msgsend",

  "feed":{

    "mediaIds":[],

    "fromId":"130",

    "creationDate":"2011-07-27T14:57:28.52Z",

    "text":"test message",

    "toIdsArray":[

      "131"

    ],

    "read":"true",

    "threadToken":"1311778648525",

    "pictureURIs":[],

    "messageId":"130_4486"

  }

}

</code></pre>

The Method response returns a Imessage

The displayName of targets separated by "," or ";" (may be empty)

The accountIds of the target of the message (may be empty)

The threadtoken of the message we are replying, forwarding, null if simple new message. In case, the method encounter any error, the response is an exeception with specific 

parameters detailed below.

*Error*:

|*Error Code*|*Type*|*Value*|*Description*|

|FizMediaQuotaExceededException|ex|601|Media Quota exceedded|

|FizMessageInvalidRecipient|ex|100|Invalid recipient|

|FizAccountNotFoundInSessionException|un|501|Session is invalid|

|FizApiInvalidParameterException|un|502|invalid token|

|FizApiModelDoesNotExistException|un|503|Object does not exists|

|FizApiModelRightException|un|504|Right exception to use this method|

h2. Sending a message to the family- _msgsendfamily_

The method send a message to whole the family.

By sending an HTTP request http://yourserver/api/msg/sendfamily?threadToken=1311778737613&text=helloworld

*Parameters*:

|*Name*|*Type*|*Description*|

|threadToken|String|associate a thread messageid in case of a forward or a reply|

|text|string|text of the message|

|file|binary or url|value to set as read or not the thread|

*Response*:

<pre><code class="javascript">

{

  "cn":"msgsendfamily",

  "feed":{

    "mediaIds":[],

    "fromId":"130",

    "creationDate":"2011-07-27T15:03:03.63Z",

    "text":"text here",

    "toIdsArray":[

      "133",

      "131",

      "1704",

      "1705",

      "1706"

    ],

    "read":"true",

    "threadToken":"1311778737613",

    "pictureURIs":[],

    "messageId":"130_4490"

  }

}

</code></pre>

The Method response returns a Imessage

*Error*:

|*Error Code*|*Type*|*Value*|*Description*|

|FizMediaQuotaExceededException|ex|601|Media Quota exceedded|

|FizAccountNotFoundInSessionException|un|501|Session is invalid|

|FizApiInvalidParameterException|un|502|invalid token|

|FizApiModelDoesNotExistException|un|503|Object does not exists|

|FizApiModelRightException|un|504|Right exception to use this method|