Creating Public/Private Channels

The following section discusses Magnet Max REST APIs to send message to Channels. This enables key functionalities to manage and send messages to public/private forums. To make requests to these APIs, an access token is needed.

For details on how to obtain recipientUserIds and access token to make the request, please refer to Authentication and User Management.

• Create public/private channels

• Search for public channels

• Delete a public/private channel (channel owner only)

• Get public/private channel by name

• Get summary of a public/private channel

• Subscribe to a public/private channel

• Unsubscribe from a public/private channel

• Get a list of subscribers of a public/private channel

• Add tags to a public/private channel

• Get all tags of a public/private channel

• Delete a tag of a public/private channel

• Delete all tags of a public/private channel

• Publish an item to a public/private channel

• Get a list of published items from a public/private channel by item ids

• Fetch a list of published items from a public/private channel by date range

• Delete items from a public/private channel by item ids

• Delete all items from a public/private channel (channel owner only)

A channel name in the URL path refers to three types of channels: public channel, private channel and my private channel. A private channel name will be preceded by a user ID and #; for example, ff80808150d46ba80150d47491250004#blogs refers to the private channel blogs of a user whose user ID is ff80808150d46ba80150d47491250004. Otherwise, the channel name in the URL refers to a public channel or my private channel (for example, query parameter personal used in deleting a channel).

Create Public/Private Channels

* Path
```  
POST http://<server>/message/api/v2/channels
```

* Sample Request
```
curl -i -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer access_token" \
  -d '{"maxItems": -1, "channelName": "TEST_PRIVATE_CHANNEL", "privateChannel": true, "description": "description", "subscribeOnCreate": true, "publishPermission": "anyone"}' \
  'https://<server>/message/api/v2/channels'
```

* Sample Response
```
{"code":0,"message":"Channel created"}
```

* Parameters
    <table >
       <tbody >
          <tr >
             <td >maxItems(optional)</td>
             <td >Maximum number of published items to be saved on server.  
                Default to -1 for unlimited
             </td>
          </tr>
          <tr >
             <td >channelName</td>
             <td >name of the channel to be created</td>
          </tr>
          <tr >
             <td >privateChannel(optional)</td>
             <td >Set to true to make channel private, false to make public.  
                Default to false
             </td>
          </tr>
          <tr >
             <td >description(optional)</td>
             <td >discription of the channel</td>
          </tr>
          <tr >
             <td >subscribeOneCreate(optinal)</td>
             <td >Set to true to automatically subsribe creator to the channel.  
                Default to true
             </td>
          </tr>
          <tr >
             <td >publishPermission(optional)</td>
             <td >Who can publish to the channels.
                <ul>
                <li> anyone ( default)</li>
                <li> owner</li>
                <li> subscribers</li>
                <ul>
             </td>
          </tr>
       </tbody>
    </table>

Search for Public Channels

* Path
```
GET http://<server>/message/api/v2/channels?channelName={channel_name}&description={description}&offset={offset}&size={size}&tag={tag1}&tag={tag2}
```

* Sample Request
```
curl -i -X GET \
  -H "Authorization: Bearer access_token" \
  'https://<server>/message/api/v2/channels?channelName=TEST&offset;=0&size;=10'
```            

* Sample Response
```
HTTP/1.1 200 OK
Content-Type: application/json

{  
   "total":1,
   "results":[  
      {  
         "persistent":true,
         "creationDate":"2015-11-04T22:47:16.236+0000",
         "description":"description",
         "creator":"ff80808150d46ba80150d47491250004%ppiglbr160@mmx/1111-2222-3333-4444",
         "maxPayloadSize":2097152,
         "subscriptionEnabled":true,
         "publishPermission":"anyone",
         "maxItems":-1,
         "collection":false,
         "modifiedDate":"2015-11-04T22:47:16.238+0000",
         "name":"TEST_PUBLIC_CHANNEL",
         "privateChannel":false,
      }
   ]
}
```            

* Parameters
<table >
   <tbody >
      <tr >
         <td >channelName</td>
         <td >Any search string</td>
      </tr>
      <tr >
         <td >offset (optional)</td>
         <td >number of search result server should skip starting from first result</td>
      </tr>
      <tr >
         <td >size (optional)</td>
         <td >number of search result requested</td>
      </tr>
      <tr >
         <td >total</td>
         <td >total number of search result returned from server</td>
      </tr>
      <tr >
         <td >results</td>
         <td >
            dictionary list of channels returned from server
            <ul>
            <li> <b>persistent:</b>  boollean indicating if published items are persited on server</li>
            <li> <b>creationDate:</b> time of date in which the channel was created</li>
            <li> <b>description:</b> description of the channel</li>
            <li> <b>creator:</b> user id of the channel owner</li>
            <li> <b>maxPayloadSize:</b> maximum payload in size</li>
            <li> <b>subscriptionEnabled:</b> boolean indicating if channel allow subscription</li>
            <li> <b>publishPermission:</b> indicating who can publish to this channel</li>
            <li> <b>maxItems:</b> maximum number of items to be persisted on channel</li>
            <li> <b>modifiedDate:</b> the last time and date of modification to the channel</li>
            <li> <b>name:</b> name of the channel</li>
            <ul>
         </td>
      </tr>
   </tbody>
</table>        

Delete Public/Private Channels

Note that the channel owner is the only person who may delete a channel.

* Path
```
DELETE http://<server>/message/api/v2/channels/{channel_name}?personal={boolean}
```

* Sample Request
```
curl -i -X DELETE \
  -H "Authorization: Bearer access_token" \
  'https://<server>/message/api/v2/channels/TEST_PRIVATE_CHANNEL?personal=true'
```

* Sample Response
```
HTTP/1.1 200 OK
```            

* Parameters
<table>
    <tbody >
        <tr >
            <td >channel_name</td>
            <td >{path param} name of channel</td>
        </tr>
        <tr >
            <td >personal</td>
            <td>a boolean value, default to false (public channel) if not specified</td>
        </tr>
    </tbody>
</table>  

Get Public/Private Channel by Name

* Path
```
GET http://<server>/message/api/v2/channels/{channel_name}
```

* Sample Request
```
curl -i -X GET \
  -H "Authorization: Bearer access_token" \
  'http://<server>/message/api/v2/channels/TEST_PUBLIC_CHANNEL'
```            

* Sample Response
```
HTTP/1.1 200 OK
Content-Type: application/json

{  
   "persistent":true,
   "creationDate":"2015-11-04T22:47:16.236+0000",
   "description":"description",
   "creator":"ff80808150d46ba80150d47491250004%ppiglbr160@mmx/1111-2222-3333-4444",
   "maxPayloadSize":2097152,
   "subscriptionEnabled":true,
   "publisherPermission":"anyone",
   "maxItems":-1,
   "collection":false,
   "modifiedDate":"2015-11-04T22:47:16.238+0000",
   "name":"TEST_PUBLIC_CHANNEL",
   "userId":null,
   "privateChannel":false
}
```           

* Parameters

Get Summary of a Public/Private Channel

* Path
```       
GET http://<server>/message/api/v2/channels/{channel_name}/summary
```

* Sample Request
```
curl -i -X GET \
  -H "Authorization: Bearer access_token" \
   'http://<server>/message/api/v2/channels/TEST_PUBLIC_CHANNEL/summary'
```

* Sample Response

```
HTTP/1.1 200 OK
{  
    "userId":null,
    "channelName":"TEST_PUBLIC_CHANNEL",
    "publishedItemCount":0,
    "lastPublishedTime":"2015-11-04T23:33:18.604Z"
}
```            

* Parameters

Subscribe to a Public/Private Channel

* Path
```
PUT http://<server>/message/api/v2/channels/{channel_name}/subscribe
```

* Sample Request

```
curl -i -X PUT \
  -H "Authorization: Bearer dnmKoeKRY33fhSIW0lUG8Kz7jUdluEsvkff0SaPGL6w0LYRhV9CyGehPOt3caEXJh69C3257lPYbh_YnpRwy36DHt74PkC-mMjoS45kXSHSm0ZAQ1whQZvBWC_CVx80klTf-TsnAQ8eo-74NuJpGANVJjSkroBkOh3k5mZZG-nNFUSzO2-sHPrPk7TGXbp7u_eCVd_B-r2hYhX_odVHJvwvNUobFhLpjMVaU4qkZ--qEfRX0Z2r4AozmrPsEUR3DazgzVw_iE_OthzgFdnPYwaJQFd9PhNA7iz64SaL4tS8" \
  'http://localhost:5220/mmxmgmt/api/v2/channels/TEST_PUBLIC_CHANNEL/subscribe'
```

*  Sample Response

```
HTTP/1.1 200 OK
Content-Type: application/json

{  
   "code":200,
   "subId":"TzpC34l3TcXSYNY1W312UxEPRgay5XHwrAgu0JQi",
   "msg":"Success"
}
```      

• Parameters

Unsubscribe from a Public/Private Channel

* Path
```   
PUT http://<server>/message/api/v2/channels/{channel_name}/unsubscribe
```

*  Sample Request

```
curl -i -X PUT \
  -H "Authorization: Bearer access_token" \
  http://localhost:5220/mmxmgmt/api/v2/channels/TEST_PUBLIC_CHANNEL/unsubscribe
 ```           

* Sample Response

```
HTTP/1.1 200 OK
{"message":"1 subscription is cancelled","code":200}
 ```           

* Parameters

Get Subscribers List for a Public/Private Channel

* Path
```        
GET http://<server>/message/api/v2/channels/{channel_name}/subscriptions
```

* Sample Request
```
curl -i -X GET \
  -H "Authorization: Bearer dnmKoeKRY33fhSIW0lUG8Kz7jUdluEsvkff0SaPGL6w0LYRhV9CyGehPOt3caEXJh69C3257lPYbh_YnpRwy36DHt74PkC-mMjoS45kXSHSm0ZAQ1whQZvBWC_CVx80klTf-TsnAQ8eo-74NuJpGANVJjSkroBkOh3k5mZZG-nNFUSzO2-sHPrPk7TGXbp7u_eCVd_B-r2hYhX_odVHJvwvNUobFhLpjMVaU4qkZ--qEfRX0Z2r4AozmrPsEUR3DazgzVw_iE_OthzgFdnPYwaJQFd9PhNA7iz64SaL4tS8" \
  'http://<server>/message/api/v2/channels/TEST_PUBLIC_CHANNEL/subscriptions'
```            

* Sample Response
```
HTTP/1.1 200 OK
Content-Type: application/json

[  
   {  
      "userId":"ff80808150d46ba80150d47491250004",
      "channelName":"test_public_channel",
      "subscriptionId":"TzpC34l3TcXSYNY1W312UxEPRgay5XHwrAgu0JQi",
      "deviceId":null
   }
]
```            

* Parameters

Add Tags to a Public/Private Channel

* Path
```        
POST http://<server>/message/api/v2/channels/{channel_name}/tags</code>
```
*  Sample Request

```
curl -i -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer access_token" \
  -d '{"personal": false, "tags": ["tag1", "tag2"]}' \
  'http://<server>/message/api/v2/channels/TEST_PUBLIC_CHANNEL/tags'
```            

* Sample Response
```
HTTP/1.1 200 OK
Content-Type: application/json

{"message":"Success","code":200}
```            
* Parameters

Get All Tags from a Public/Private Channel

* Path
```        
GET http://<server>/message/api/v2/channels/{channel_name}/tags```

* Sample Request
```
curl -i -X GET \
  -H "Authorization: Bearer access_token" \
  'http://<server>/message/api/v2/channels/TEST_PUBLIC_CHANNEL/tags'
```            

* Sample Response

    ```
    HTTP/1.1 200 OK
    Content-Type: application/json

    {  
       "channelName":"TEST_PUBLIC_CHANNEL",
       "tags":[  
          "tag1",
          "tag2"
       ]
    }
    ```           

* Parameters

Delete a Public/Private Channel Tag

* Path
```        
DELETE http://<server>/message/api/v2/channels/{channel_name}/tags/{tag}?personal={boolean}
```
* Sample Request
```
curl -i -X DELETE \
  -H "Authorization: Bearer access_token" \
  'http://<server>/message/api/v2/channels/TEST_PUBLIC_CHANNEL/tags/tag1?personal=false'
```            

* Sample Response
```
HTTP/1.1 200 OK
```

* Parameters

Delete All Tags from a Public/Private Channel

* Path
```        
DELETE http://<server>/message/api/v2/channels/{channel_name}/tags?personal={boolean}
```

* Sample Request
```
curl -i -X DELETE \
  -H "Authorization: Bearer access_token" \
  'http://<server>/message/api/v2/channels/TEST_PUBLIC_CHANNEL/tags?personal=false'
```            

* Sample Response
```
HTTP/1.1 200 OK
```

* Parameters

Publish an Item to a Public/Private Channel

* Path
```       
POST http://<server>/message/api/v2/channels/{channel_name}/items
```

* Sample Request
```
curl -X POST \
  -H 'Authorization: Bearer access_token' \
  -H 'Content-Type: application/json' \
  -d '{ "content": { "message": "purchase invoice", "amont":"$10,000", "date":"10-10-2015" } }' \
  http://<server>/message/api/v2/channels/TEST_PUBLIC_CHANNEL/items
```            
* Sample Response
```
HTTP/1.1 201 Created
{  
    "message":"Successfully published message",
    "status":"OK",
    "messageId":"eacbd7024a4a6e3406ce4a0918de5ccb"
}
```            

* Parameters
<table >
    <tbody >
       <tr >
          <td >messageType</td>
          <td >any string specifying the type of message</td>
       </tr>
       <tr >
          <td >contentType</td>
          <td >mime-type</td>
       </tr>
       <tr >
          <td >content</td>
          <td >dictionary list of key/value pair of the actual message content</td>
       </tr>
    </tbody>
</table>

Get a List of Published Items from a Public/Private Channel by Item IDs

* Path
```        
>GET http://<server>/message/api/v2/channels/{channel_name}/items?id={id1}&id={id2}&...
```

* Sample Request
```        
curl -X GET \
  -H 'Authorization: Bearer access_token' \
  -H 'Content-Type: application/json' \
  'http://<server>/message/api/v2/channels/TEST_PUBLIC_CHANNEL/items/?id=eacbd7024a4a6e3406ce4a0918de5ccb&id;=3700373451fa4f1639b01b490e2d283d'
```

* Sample Response
```
{  
   "totalCount":1,
   "items":[  
      {  
         "itemId":"eacbd7024a4a6e3406ce4a0918de5ccb",
         "channelName":"TEST_PUBLIC_CHANNEL",
         "publisher":{  
            "userId":"ff80808150d46ba80150d47491250004",
            "deviceId":null
         },
         "content":{  
            "message":"Get this done!",
            "data":"10-11-2015"
         },
      },
      {  
         "itemId":"eacbg7024a4a6e7406ce4a0918de5ccc",
         "channelName":"TEST_PUBLIC_CHANNEL",
         "publisher":{  
            "userId":"ff80808150d46ba80150d47491250004",
            "deviceId":null
         },
         "content":{  
            "message":"Another Test!",
            "data":"10-11-2015"
         }
      }
   ]
}
```            

* Parameters

Fetch a List of Published Items from a Public/Private Channel by Date Range

* Path
```
GET http://<server>/message/api/v2/channels/{channel_name}/items/fetch?since={iso-datetime}&until={iso-datetime}&sort_order={ASC|DESC}&offset={offset}&size={maxsize}
```

* Sample Request
```
curl -X GET \
  -H 'Authorization: Bearer access_token' \
  -H 'Content-Type: application/json' \
  http://<server>/message/api/v2/channels/TEST_PUBLIC_CHANNEL/items/fetch?since=2015-11-01T08:50Z&until;=2015-11-05T07:20Z&sort;_order=ASC&offset;=0&size;=100
```            

* Sample Response
```
{  
   "totalCount":2,
   "items":[  
      {  
         "itemId":"05c666f0dbdbdb35ae437fb874bef131",
         "channelName":"TEST_PUBLIC_CHANNEL",
         "publisher":{  
            "userId":"ff80808150d46ba80150d47491250004",
            "deviceId":null
         },
         "content":{  
            "message":"Get this done!",
            "data":"10-11-2015"
         }
      },
      {  
         "itemId":"eacbd7024a4a6e3406ce4a0918de5ccb",
         "channelName":"TEST_PUBLIC_CHANNEL",
         "publisher":{  
            "userId":"ff80808150d46ba80150d47491250004",
            "deviceId":null
         },
         "content":{  
            "message":"Get this done!",
            "data":"10-11-2015"
         }
      }
   ]
}
```

* Parameters

Delete Items from a Public/Private Channel by Item IDs

* Path
```        
DELETE http://<server>/message/api/v2/channels/{channel_name}/items?id={id1}&id={id2}&...
```

* Sample Request
```    
curl -X DELETE \
    -H 'Authorization: Bearer F1IW8LHyPPpSU_2dLgckOyv0qyNtxUlTMz4wcMxGImiFh9RU_KG8AJuawtmHJ8fQu635_V6VZO0k-oIV7a5jyBaih6HN6ctwMXOSrUAbiFlEfJIsGIxmXk7ddIKaweHwYHfGxyagwHDs9Ta7JJ8UoGPBTqtbrY2NHDNT2lYGDFWXizU_BZqxEpGJyU1_PWrVpJND0-px5tqMiudQvW78otFKit3DRALa9Xxje3JnzRXQyJiI6isMBope4Ea8Xr2hpUj2-h4z9j4wL4ZmM0M6jRuZw0xpqSrVQUYDKvswTMY' \
    -H 'Content-Type: application/json' \
    http://<server>/message/api/v2/channels/TEST_PUBLIC_CHANNEL/items?id=eacbd7024a4a6e3406ce4a0918de5ccb
```            

* Sample Response
```
{"eacbd7024a4a6e3406ce4a0918de5ccb":200}
```

* Parameters

Delete All Items from a Public/Private Channel

Note that only a channel owner can delete items from a channel.

* Path
```        
DELETE http://<server>/message/api/v2/channels/{channel_name}/items/all?personal=boolean
```

* Sample Request
```
curl -X DELETE \
  -H 'Authorization: Bearer F1IW8LHyPPpSU_2dLgckOyv0qyNtxUlTMz4wcMxGImiFh9RU_KG8AJuawtmHJ8fQu635_V6VZO0k-oIV7a5jyBaih6HN6ctwMXOSrUAbiFlEfJIsGIxmXk7ddIKaweHwYHfGxyagwHDs9Ta7JJ8UoGPBTqtbrY2NHDNT2lYGDFWXizU_BZqxEpGJyU1_PWrVpJND0-px5tqMiudQvW78otFKit3DRALa9Xxje3JnzRXQyJiI6isMBope4Ea8Xr2hpUj2-h4z9j4wL4ZmM0M6jRuZw0xpqSrVQUYDKvswTMY' \
  -H 'Content-Type: application/json' \
  http://<server>/message/api/v2/channels/TEST_PUBLIC_CHANNEL/items/all?personal=false
```            

* Sample Response
```
HTTP/1.1 200 OK
```

* Parameters