Channel Lifecycle

Create a Channel

Create a new Channel.

Send a JSON document that matches the Channel schema with an HTTP header of Content-Type: application/json. Currently, the only keys we use from your JSON will be readers, writers, annotations, and type. The owner will be auto-subscribed to this channel.

Creating a PM Channel

PM Channels (channels of type net.app.core.pm) cannot be directly created. Instead they are created for you as necessary when sending a Message using pm as a channel_id. For more information, see the Create a Message endpoint.

This endpoint responds to general Channel parameters.

Endpoint

Method URL Token Scope
POST https://api.app.net/channels User public_messages or messages

Example

to see more complete examples.

curl -X POST -H "Authorization: Bearer <YOUR ACCESS TOKEN>" -H "X-ADN-Pretty-JSON: 1" \
    -H "Content-Type: application/json" -d "{
  \"type\": \"com.example.channel\",
  \"writers\": {
    \"user_ids\": [
      \"@berg\",
      \"1\"
    ]
  }
}" \
    "https://api.app.net/channels"
{
  "data": {
    "counts": {
      "messages": 42,
      "subscribers": 43
    },
    "has_unread": false,
    "id": "2",
    "owner": "...user object...",
    "is_inactive": false,
    "readers": {
      "any_user": false,
      "immutable": false,
      "public": false,
      "user_ids": [

      ],
      "you": true
    },
    "editors": {
      "any_user": false,
      "immutable": false,
      "public": false,
      "user_ids": [

      ],
      "you": true
    },
    "type": "com.example.channel",
    "writers": {
      "any_user": false,
      "immutable": false,
      "public": false,
      "user_ids": [
        "1",
        "2"
      ],
      "you": true
    },
    "you_can_edit": true,
    "you_subscribed": true,
    "you_muted": false
  },
  "meta": {
    "code": 200
  }
}

Update a Channel

Updates a specific Channel object. You can update a channel by PUTing an object that matches the Channel schema with an HTTP header of Content-Type: application/json. The only keys that can be updated are annotations, readers, and writers (and the ACLs can only be updated if immutable=false). The you_can_edit property tells you if you are allowed to update a channel. Currently, only the Channel owner can edit a channel.

If you want to add or update a Channel’s annotations, you may include the optional annotations key and pass in the annotations that are changing.

This endpoint currently works identically for the PUT and PATCH HTTP methods.

This endpoint responds to general Channel parameters.

Endpoint

Method URL Token Scope
PUT https://api.app.net/channels/{channel_id} User public_messages or messages

URL Parameters

Name Description
channel_id The id of the Channel to update.

Example

to see more complete examples.

curl -X PUT -H "Authorization: Bearer <YOUR ACCESS TOKEN>" -H "X-ADN-Pretty-JSON: 1" \
    -H "Content-Type: application/json" -d "{
  \"readers\": {
    \"public\": true
  }
}" \
    "https://api.app.net/channels/1"
{
  "data": {
    "counts": {
      "messages": 42,
      "subscribers": 43
    },
    "has_unread": false,
    "id": "1",
    "owner": "...user object...",
    "is_inactive": false,
    "readers": {
      "any_user": false,
      "immutable": false,
      "public": true,
      "user_ids": [

      ],
      "you": true
    },
    "editors": {
      "any_user": false,
      "immutable": false,
      "public": false,
      "user_ids": [

      ],
      "you": true
    },
    "recent_message_id": "231",
    "recent_message": "...message object...",
    "type": "com.example.channel",
    "writers": {
      "any_user": false,
      "immutable": false,
      "public": false,
      "user_ids": [

      ],
      "you": true
    },
    "you_can_edit": true,
    "you_subscribed": true,
    "you_muted": false
  },
  "meta": {
    "code": 200
  }
}

Deactivate a Channel

Mark a channel as inactive. This does not delete the contents of the Channel. It prevents new messages from being added to the channel and unsubscribes all users from the Channel. This channel will be hidden unless it is explicitly requested by id or the include_inactive=1 parameter is used. This is irreversible.

The current user must be the same user who created the Channel. Editors cannot delete a channel

net.app.core.pm channels cannot be marked as inactive.

Remember, access tokens can not be passed in a HTTP body for DELETE requests. Please refer to the authentication documentation.

This endpoint responds to general Channel parameters.

Endpoint

Method URL Token
DELETE https://api.app.net/channels/{channel_id} User

URL Parameters

Name Description
channel_id The id of the Channel to delete.

Example

to see more complete examples.

curl -X DELETE -H "Authorization: Bearer <YOUR ACCESS TOKEN>" -H "X-ADN-Pretty-JSON: 1" \
    "https://api.app.net/channels/1"
{
  "data": {
    "counts": {
      "messages": 42,
      "subscribers": 0
    },
    "has_unread": false,
    "id": "1",
    "owner": "...user object...",
    "is_inactive": true,
    "readers": {
      "any_user": false,
      "immutable": false,
      "public": true,
      "user_ids": [

      ],
      "you": true
    },
    "editors": {
      "any_user": false,
      "immutable": false,
      "public": false,
      "user_ids": [

      ],
      "you": true
    },
    "recent_message_id": "231",
    "recent_message": "...message object...",
    "type": "com.example.channel",
    "writers": {
      "any_user": false,
      "immutable": false,
      "public": false,
      "user_ids": [

      ],
      "you": true
    },
    "you_can_edit": true,
    "you_subscribed": true,
    "you_muted": false
  },
  "meta": {
    "code": 200
  },
  "you_subscribed": false
}