How To Use Private Messages

Private messages are created in special channels with the restricted channel type. This is a list of ways they are different from normal channels:

  • They cannot be directly created or deactivated
  • They're always immutable (you cannot change who is included in the channel)
  • There is no user/owner, only users with write access
  • Any user can "sticky" a message

Channel Creation

Pnut automatically creates the channel when a private message is sent. If there has already been a message between the same parties previously, Pnut reuses the existing channel.

Sending a Message

To send a message to other users, you need to know all of the users you will be sending the message to, or the ID of an already-created channel. If you know the channel ID, you may create a message in it just like you would any other channel. If you do not, or it has not been created yet, you can create an application/json-encoded message with the channel_id of pm, and a special list in the JSON of destinations, listing all users by "@username" or their user ID.

Here, the destinations are for user IDs 1 and 5, and username @ericd:

curl "" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "Content-Type: application/json" \
    -d "{
  \"text\":\"We should make great things.\",
}" \
    -X POST

This is what the example's channel permissions would look like if User ID 2 created the message:


The creating user's ID will be in the write-access ACL, just like everyone else.

In every other way, they can be treated like other channels and messages.

Existing PM Channels

If you want to see a PM channel between specific users without sending a message, you can use the Existing PM endpoint to find the channel ID.