This guide quickly brings you up to speed on Stream’s Chat API. The API is flexible and allows you to build any type of chat or messaging. Be sure to try the API tour, the React Chat tutorial and the Chat UI Kit before diving into these docs.

Chat Client

Let’s get started by initializing the client and setting the current user.

const client = new StreamChat('YOUR_API_KEY');
await client.setUser(
    {
        id: 'jlahey',
        name: 'Jim Lahey',
        image: 'https://i.imgur.com/fR9Jz14.png',
    },
    'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiamxhaGV5In0.OkDbpbujWJ-XIVHaf00Dnqt3v8Yp_nQ6CGzm-Z4QUVc',
);

// typically done in your BaseApplication class
StreamChat.init("qk4nn7rpcn75", new ApiClientOptions.Builder().Timeout(6666).build(), getApplicationContext());

// set the user to establish the websocket connection
// usually done when you open the chat interface
Client client = StreamChat.getInstance(getApplication());

// this hashmap allows you to add any custom fields you want to store about your user
// the UI components will pick up name and image by default
HashMap<String, Object> extraData = new HashMap<>();
extraData.put("name", "Bender");
extraData.put("image", "https://bit.ly/321RmWb");
User user = new User(USER_ID, extraData);
client.setUser(user, "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiamxhaGV5In0.OkDbpbujWJ-XIVHaf00Dnqt3v8Yp_nQ6CGzm-Z4QUVc", new ClientConnectionCallback() {
    @Override
    public void onSuccess(User user) {
        Log.i(TAG, String.format("Connection established for user %s", user.getName()));
    }

    @Override
    public void onError(String errMsg, int errCode) {
        Log.e(TAG, String.format("Failed to establish websocket connection. Code %d message %s", errCode, errMsg));
    }
});

// In your AppDelegate:
// Import Stream chat core framework.
import StreamChatCore

// Setup the Stream Chat Client with your API key 
// in func application(_ application:didFinishLaunchingWithOptions:).
Client.config = .init(apiKey: "<#API_KEY#>")

// Create a user, when he/she was logged in.
let user = User(id: "bender", name: "Bender", avatarURL: URL(string: "https://bit.ly/321RmWb")!)

// Setup the current user and token.
Client.shared.set(user: user, token: token)

The above snippet is for an in-browser or mobile integration. Server side API calls are a little different, but we will cover them in detail later in the docs.

Channels

Let’s continue by initializing your first channel. A Channel contains messages, a list of people that are watching the Channel and optionally a list of members (for private conversations). The example below shows how to set up a Channel to support chat for a group conversation:

const channel = client.channel('messaging', 'travel', {
    name: 'Awesome channel about traveling',
});
// fetch the channel state, subscribe to future updates
let state = await channel.watch();

// initialize a channel object with an extra data hashmap
HashMap<String, Object> extraData = new HashMap<>();
extraData.put("name", "Talking about life");

Channel channel = client.channel(channelType, channelID, extraData);

// watching a channel's state
ChannelQueryRequest request = new ChannelQueryRequest().
          withMessages(Constant.DEFAULT_LIMIT).withWatch();

// note how the withWatch() argument ensures that we are watching the channel for any changes/new messages
channel.query(
  request,
  new QueryChannelCallback() {
      @Override
      public void onSuccess(ChannelState response) {          
      }

      @Override
      public void onError(String errMsg, int errCode) {          
      }
  }
);

// Create an extra data for a channel.
struct ChannelInfo: Codable {
    let info: String
}

// Register once your extra data types for the decoding.
ExtraData.decodableTypes = [.channel(ChannelInfo.self)]

let info = ChannelInfo(info: "Awesome channel about traveling")
let channel = Channel(type: .messaging, id: "travel", name: "Travel", extraData: info)

The first two arguments are the Channel Type and the Channel ID (messaging and travel in this case). The Channel ID is optional, if you leave it out the ID will be automatically determined based on the list of members. The Channel type controls the settings we’re using for this Channel.

There are 5 default types of channels:

• livestream
• messaging
• team
• gaming
• commerce

The third argument is an object containing the channel data. You can add as many custom fields as you want as long as the total size of the object is less than 5KB.

Messages

Now that we have the Channel setup, let's send our first chat message:

const text = 'I’m mowing the air Rand, I’m mowing the air.';
const response = await channel.sendMessage({
    text,
    customfield: '123',
});

// prepare the message
Message message = new Message();
message.setText("hello world");

// send the message to the channel
channel.sendMessage(message,
  new MessageCallback() {
      @Override
      public void onSuccess(MessageResponse response) {        
      }

      @Override
      public void onError(String errMsg, int errCode) {
      }
  });

// The Stream Chat based on RxSwift framework.
import RxSwift

// Create an instance variable for the disposeBag in your view controller.
// It needs for the memory management of RxSwift subscriptions.
let disposeBag = DisposeBag()

// Create and send a message.
let message = Message(text: "Hello world!")

channel.send(message: message)
    .subscribe(onNext: { messageResponse in
        print(messageResponse)
    })
    .disposed(by: disposeBag)

Similar to users and Channels, the sendMessage method allows you to add custom fields. When you send a message to a Channel it will automatically broadcast to all the people that are watching this Channel and update in real time.

Events

This is how you can listen to events on the client side:

channel.on('message.new', event => {
    console.log('received a new message', event.message.text);
    console.log(`Now have ${channel.state.messages.length} stored in local state`);
});

Integer channelSubscriptionId = channel.addEventHandler(new ChatChannelEventHandler() {
  @Override
  public void onMessageNew(Event event) {
      event.getMessage();
  }
}
// channel.removeEventHandler(channelSubscriptionId) to remove it

channel.onEvent(.messageNew)
    .subscribe(onNext: { event in
        print(event)
    })
    .disposed(by: disposeBag)

Note how you receive the event and can access the full Channel state via channel.state.

Conclusion

Now that you understand the building blocks of a fully functional chat integration, let’s move on to the next sections of the documentation where we will go into more details on each API endpoint.

Initialization for browser/mobile

const chatClient = new StreamChat('YOUR_API_KEY', {
    timeout: 3000,
    httpAgent: new http.Agent({ keepAlive: 3000 }),
    httpsAgent: new http.Agent({ keepAlive: 3000 }),
});

// typically done in your BaseApplication class
StreamChat.init("qk4nn7rpcn75", new ApiClientOptions.Builder().Timeout(6666).build(), getApplicationContext());

// set the user to establish the websocket connection
// usually done when you open the chat interface
Client client = StreamChat.getInstance(getApplication());

import StreamChatCore

// In your AppDelegate:

// Setup the Stream Chat Client.
Client.config = .init(apiKey: "<#API_KEY#>")

// Note: If you want to enable logs for requests and events you can enable them with extra parameter:  `logOptions`.

// typically done in your BaseApplication class
StreamChat.init(
    "qk4nn7rpcn75", ApiClientOptions.Builder().Timeout(6666).build(),
    applicationContext
)

// set the user to establish the websocket connection
// usually done when you open the chat interface
val client = StreamChat.getInstance(application)

The code above creates a Chat client instance for browser/mobile usage. Additional options such as API base URL and request timeouts can be provided to the client.

Setting the user

Once initialized, you must specify the current user with setUser:

await chatClient.setUser(
    {
        id: 'john',
        name: 'John Doe',
        image: 'https://getstream.io/random_svg/?name=John',
    },
    'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiam9obiJ9.TxsU2JMbx7UXQ166lRabT6h7pAf415tLLKhJEZO_Kbg',
);

// this hashmap allows you to add any custom fields you want to store about your user
// the UI components will pick up name and image by default

HashMap<String, Object> extraData = new HashMap<>();
extraData.put("name", "Bender");
extraData.put("image", "https://bit.ly/321RmWb");

User user = new User(USER_ID, extraData);
client.setUser(user, "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiam9obiJ9.TxsU2JMbx7UXQ166lRabT6h7pAf415tLLKhJEZO_Kbg", new ClientConnectionCallback() {
    @Override
    public void onSuccess(User user) {
        Log.i(TAG, String.format("Connection established for user %s", user.getName()));
    }

    @Override
    public void onError(String errMsg, int errCode) {
        Log.e(TAG, String.format("Failed to establish websocket connection: %s", errMsg));
    }
});

// Create a user, when he/she was logged in.
let user = User(id: "bender", name: "Bender", avatarURL: URL(string: "https://bit.ly/321RmWb")!)

// You can setup a user token in 2 ways.

// 1. Setup the current user with a token.
Client.shared.set(user: user, token: token)

// 2. Setup the current user with a token provider.
Client.shared.set(user: user) { tokenProvider in
    // Make a request here to your backend to get a token for the current user.
    tokenProvider(token)
}

// this hashmap allows you to add any custom fields you want to store about your user
// the UI components will pick up name and image by default
val extraData = HashMap<String, Any>()
extraData.put("name", "Bender")
extraData.put("image", "https://bit.ly/321RmWb")
val user = User("USER_ID", extraData)
client.setUser(user, "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiam9obiJ9.TxsU2JMbx7UXQ166lRabT6h7pAf415tLLKhJEZO_Kbg", object : ClientConnectionCallback {
    override fun onSuccess(user: User) {
        Log.i(TAG,String.format("Connection established for user %s", user.name) )
    }

    override fun onError(errMsg: String, errCode: Int) {
        Log.e(TAG,
            String.format("Failed to establish websocket connection: message %s",
                errMsg
            )
        )
    }
})

Note how we are waiting for the setUser API call to be completed before moving forward. You should always make sure to have the user set before making any more call. All SDKs make this very easy and wait or queue requests until then.

User fields

The id field is the only required field for the user. There are a few other fields you should know about though:

Tokens

Tokens are used to authenticate the user. Typically, you send this token from your backend to the client side when a user registers or logs in.

You can generate tokens server side with the following syntax:

• JS/Node
• Python
• Ruby
• PHP
• Java
• Go
• Swift
• C#

const serverSideClient = new StreamChat('YOUR_API_KEY', 'API_KEY_SECRET');
const token = serverSideClient.createToken('john');

# pip install stream-chat

import stream_chat

chat_client = stream_chat.StreamChat(api_key="STREAM_KEY", api_secret="STREAM_SECRET")
token = chat_client.create_token('john')

# gem install stream-chat-ruby

require 'stream-chat'

client = StreamChat::Client.new(api_key='STREAM_KEY', api_secret='STREAM_SECRET')
client.create_token('john')

// composer require get-stream/stream-chat

$client = new GetStream\StreamChat\Client("STREAM_API_KEY", "STREAM_API_SECRET");
$token = $client->createToken("john");

// at the moment we don't have a Java client for server side usage

// go get github.com/GetStream/stream-chat-go

client, _ := stream.NewClient(APIKey, []byte(APISecret))
token := client.CreateToken("john", null)

// at the moment we don't have a Swift client for server side usage

// nuget install stream-chat-net

using StreamChat;

var client = new Client("API KEY", "API SECRET");
var token = client.CreateUserToken("john");

By default user tokens are valid indefinitely. You can set an expiration to tokens by passing it as second parameter. The expiration should contain the number of seconds since the epoch.

• JS/Node
• Python
• Ruby
• PHP
• Java
• Go
• Swift
• C#

// creates a token that expires in 1 hour using moment.js
const expirationTimestamp = moment().add('1h').format('X');
const token = serverSideClient.createToken('john', expirationTimestamp);

// the same can be done with plain JS
const token2 = serverSideClient.createToken('john', Math.floor(Date.now()/1000) + (60 * 60));

# creates a token valid for 1 hour
token = chat_client.create_token(
    'john',
    exp=datetime.datetime.utcnow() + datetime.timedelta(hours=1)
)

# creates a token valid for 1 hour
client.create_token('john', exp=Time.now.to_i + 3600)

// creates a token valid for 1 hour
$expiration = (new DateTime())->getTimestamp() + 3600;
$token = $client->createToken("john", $expiration);

// at the moment we don't have a Java SDK for server side integrations

// creates a token valid for 1 hour
token := client.CreateToken("john", time.Now().UTC().Add(time.Hour))

// at the moment we don't have a Swift client for server side usage

// creates a token valid for 1 hour
var token = client.CreateUserToken("john", DateTime.Now.AddHours(1));

Development tokens

For development apps it is possible to disable token authentication and use client-side generated tokens. Disabling auth checks is not suitable for a production application and should only done for proof-of-concepts and applications in early development stage. To enable development tokens you need to change your application config.

await chatClient.setUser(
    {
        id: 'john',
        name: 'John Doe',
        image: 'https://getstream.io/random_svg/?name=John',
    },
   chatClient.devToken('john'),
);

User user = new User(USER_ID, extraData);
client.setUser(user, client.devToken(USER_ID), new ClientConnectionCallback() {
    @Override
    public void onSuccess(User user) {
        Log.i(TAG, String.format("Connection established for user %s", user.getName()));
    }

    @Override
    public void onError(String errMsg, int errCode) {
        Log.e(TAG, String.format("Failed to establish websocket connection: %s", errMsg));
    }
});

// Create a user, when he/she was logged in.
let user = User(id: "bender", name: "Bender", avatarURL: URL(string: "https://bit.ly/321RmWb")!)

// Setup the current user with a development token.
Client.shared.set(user: user, token: .development)

val user = User("USER_ID", extraData)
client.setUser(user, client.devToken(USER_ID), object : ClientConnectionCallback {
    override fun onSuccess(user: User) {
        Log.i(TAG,String.format("Connection established for user %s", user.name) )
    }

    override fun onError(errMsg: String, errCode: Int) {
        Log.e(TAG,
            String.format("Failed to establish websocket connection: %s", errMsg
            )
        )
    }
})

Guest sessions can be created client side and do not require any server-side authentication.

Guest users have a limited set of permissions. You can read more about how to configure permissions here. You can create a guest user session by using setGuestUser instead of setUser.

await client.setGuestUser({ id: 'tommaso' });

// Not supported yet

// Create a user, when he/she was logged in.
let user = User(id: "bender", name: "Bender", avatarURL: URL(string: "https://bit.ly/321RmWb")!)

// Setup the current user and guest token.
Client.shared.set(user: user, token: .guest)

// Not supported yet

    
    # the guest endpoint returns a user object and a token:
    curl -i -X POST -d "{\"user\":{\"id\":\"tommaso\"}}"\
    -H "Content-Type: application/json" \
    -H "Stream-Auth-Type: anonymous" \
    "https://chat-us-east-c1.stream-io-api.com/guest?api_key=YOUR_API_KEY"
    
    

If a user is not logged in you can call setAnonymous. While you’re anonymous you can’t do much, but for the livestream channel type you’re still allowed to read the chat conversation.

await client.setAnonymousUser();

// not supported yet

// not supported yet

// not supported yet

To disconnect a user (say that you’re for instance logging out and logging in as someone new) you can call the disconnect method and repeat the setUser call as someone else:

client.disconnect();
client.setUser(
    {
        id: 'jack',
        name: 'Jack Doe',
    },
    'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiamFjayJ9.eljgjcOSorcR01nrYxcQtRUrHxT3ZyJlpu05Iv-3rd4',
);

client.disconnect();

Client.shared.disconnect()

client.disconnect()

The Query Users endpoint allows you to search for users and see if they are online/offline. The example below shows how you can retrieve the details for 3 users in one API call:

const response = await client.queryUsers({ id: { $in: ['john', 'jack', 'jessie'] } });

ArrayList<String> searchUsersList = new ArrayList<>();
searchUsersList.add("john");
searchUsersList.add("jack");
searchUsersList.add("jessie");

FilterObject filter = Filters.in("id", searchUsersList);
client.queryUsers(new QueryUserRequest(filter, new QuerySort()), new QueryUserListCallback() {
    @Override
    public void onSuccess(QueryUserListResponse response) {

    }

    @Override
    public void onError(String errMsg, int errCode) {

    }
});

Client.shared.users(query: UsersQuery(filter: .key("id", .in(["john", "jack", "jessie"]))))
    .subscribe()
    .disposed(by: disposeBag)

client.queryUsers(QueryUserRequest(
    Filters.`in`("id", listOf("john", "jack", "jessie")),
    QuerySort()
), object : QueryUserListCallback {
    override fun onSuccess(response: QueryUserListResponse?) {
        println(response)
    }

    override fun onError(errMsg: String?, errCode: Int) {
        println("$errMsg: $errCode")
    }
})

The first argument is the filter object, the second the sorting and the third any additional options. Here's a more extensive example:

const response = await client.queryUsers(
    { id: { $in: ['jessica'] } },
    { last_active: -1},
    { presence: true },
);

ArrayList<String> searchUsersList = new ArrayList<>();
searchUsersList.add("jessica");

QueryUserRequest request = new QueryUserRequest(filter, sort).withPresence();
FilterObject filter = Filters.in("id", searchUsersList);
QuerySort sort = new QuerySort().desc("last_active");

client.queryUsers(request, new QueryUserListCallback() {
    @Override
    public void onSuccess(QueryUserListResponse response) {

    }

    @Override
    public void onError(String errMsg, int errCode) {

    }
});

// Create a user query.
let query = UsersQuery(filter: .key("id", .in(["john", "jack", "jessie"])),
                       sort: [Sorting("last_active")],
                       options: .presence)

Client.shared.users(query: query)
    .subscribe()
    .disposed(by: disposeBag)

client.queryUsers(QueryUserRequest(
        Filters.`in`("id", listOf("jessica")),
        QuerySort().desc("last_active")
    ).withPresence(), 
    object : QueryUserListCallback {
        override fun onSuccess(response: QueryUserListResponse?) {
            println(response)
        }

        override fun onError(errMsg: String?, errCode: Int) {
            println("$errMsg: $errCode")
        }
})

The filter syntax uses Mongoose style queries. Note that we don't run Mongo on the background so you can only use a subset of queries.

You can filter and sort on the custom fields you've set for your user, the user id and when the user was last active

The options for the queryUser endpoint are "presence", "limit" and "offset". If presence is true this makes sure you receive the "user.presence.changed" event when a user goes online/offline.

Note that you can subscribe to presence status of at most 30 users via this API call

To simplify the integration with Stream the setUser call automatically creates and updates the user. Note that the setUser call has some limitations:

1. You can only update 1 user per API call
2. The user's role isn't editable
3. You can only add custom fields, you can't remove them
4. At most 100 users can be updated within the same API call

If you're looking to sync your userbase you'll want to use the updateUser(s) method instead. It will also remove fields from the user if you don't send them in this update call. The updateUser endpoint is allowed to change a user's role and make them an admin. Have a look at the following example:

• JS/Node
• Python
• Ruby
• PHP
• Java
• Go
• Swift
• C#

const response = await client.setUser(
    { id: userID, role: 'admin', favorite_color: 'green'},
    token
);
// user object is now {id: userID, role: 'user', favorite_color: 'green'}
// note how you are not allowed to make the user admin via this endpoint
const updateResponse = await serverClient.updateUsers([{ id: userID, role: 'admin', book: 'dune'}]);
// user object is now {id: userID, role: 'admin', book: 'dune'}
// note how the user became admin and how the favorite_color field was removed

# user object is now {id: userID, role: 'admin', book: 'dune'}
client.update_users([{"id": user_id, "role": "admin", "book": "dune"}])

# user object is now {id: userID, role: 'admin', book: 'dune'}
client.update_users([{ id => userID, role => 'admin', book => 'dune'}])

// user object is now {id: userID, role: 'admin', book: 'dune'}
$client->updateUsers(['id' => userID, 'role' => 'admin', 'book' => 'dune']);

// at the moment we don't have a Java client for server side usage

// user object is now {id: userID, role: 'admin', book: 'dune'}
client.UpdateUsers([]User{
    {ID: userID, Role: "admin", ExtraData: map[string]interface{}{"book": "dune"}},
})

let user = User(id: "bob", name: "Bob")

Client.shared.update(user: user)
    .subscribe()
    .disposed(by: disposeBag)

var user = new User()
{
    ID = "bob-1",
    Role = Role.Admin,
};
user.SetData("book", "dune");

// user object is now {id: userID, role: 'admin', book: 'dune'}
await client.Users.UpdateMany(new User[] { user });

Note how the updateUser call can make the user an admin, but the setUser call is not allowed to do that. The reasons for this is that setUser is called client side, so for security reasons you can't edit a user's role client side. The second difference is that the updateUser call can remove fields. This is why the `favorite_color` field is removed after the update.

Partial update

In case if you need to update only some field for user(s), you can use partial update for that.

A set and an unset params can be provided to add, modify, or remove attributes to/from the target user(s). The set and unset params can be used separately or combined together (see below).

• JS/Node
• Python
• Ruby
• PHP
• Java
• Go
• Swift
• C#

// make partial update call for userID
// it set's user.role to "admin", sets  user.field = {'text': 'value'}
// and user.field2.subfield = 'test'.
//
// NOTE: 
// changing role is available only for server-side auth.
// field name should not contain dots or spaces, as dot is used as path separator.
const update = {
    id: "userID",
    set: {
        role: "admin",
        field: {
            text: 'value'
        },
        'field2.subfield': 'test',
    },
    unset: ['field.unset'],
};
// response will contain user object with updated users info
const response = await client.partialUpdateUser(update);

// partial update for multiple users
const updates = [{
    id: "userID",
    set: {
        field: "value"
    }
}, {
    id: "userID2",
    unset: ["field.value"],
}];

// response will contain object {userID => user} with updated users info
const response = await client.partialUpdateUsers(updates);

# make partial update call for userID
# it set's user.role to "admin", sets  user.field = {'text': 'value'}
# and user.field2.subfield = 'test'.

# NOTE: 
# changing role is available only for server-side auth.
# field name should not contain dots or spaces, as dot is used as path separator.

update = {
    "id": "userID",
    "set": {
        "role": "admin",
        "field": {
            "text": 'value'
        },
        'field2.subfield': 'test',
    },
    "unset": ['field.unset'],
};

# response will contain user object with updated users info
client.update_user_partial(update);

# partial update for multiple users
updates = [
    {
        "id": "userID",
        "set": {"field": "value"}
    },
    {
        "id": "userID2",
        "unset": ["field.value"]
    }
]

# response will contain object {userID => user} with updated users info
client.update_users_partial(updates)

# at the moment this is not supported on Ruby

// at the moment this is not supported on PHP

// at the moment we don't have a Java client for server side usage

// at the moment this is not supported on Go

// at the moment we don't have a Swift client for server side usage

// at the moment this is not supported on C#

Below is a detailed example of how to send a message using Stream Chat:

const response = await channel.sendMessage({
    text: '@Josh I told them I was pesca-pescatarian. Which is one who eats solely fish who eat other fish.',
    attachments: [
        {
            type: 'image',
            asset_url: 'https://bit.ly/2K74TaG',
            thumb_url: 'https://bit.ly/2Uumxti',
            myCustomField: 123
        }
    ],
    mentioned_users: [josh.id],
    anotherCustomField: 234
});

Message message = new Message();
message.setText("Josh I told them I was pesca-pescatarian. Which is one who eats solely fish who eat other fish.");
HashMap<String, Object>extraDataMessage = new HashMap<>();
extraDataMessage.put("anotherCustomField",234);
message.setExtraData(extraDataMessage);

// add an image attachment to the message
Attachment attachment = new Attachment();
attachment.setType("image");
attachment.setImageURL("https://bit.ly/2K74TaG");
attachment.setFallback("test image");
// add some custom data to the attachment
HashMap<String, Object> extraDataAttachment = new HashMap<>();
extraDataAttachment.put("myCustomField", 123);
attachment.setExtraData(extraDataAttachment);

message.setAttachments(Arrays.asList(attachment));

// include the user ID of the mentioned user
message.setMentionedUsersId(Arrays.asList("josh-id"));

channel.sendMessage(message,
    new MessageCallback() {
        @Override
        public void onSuccess(MessageResponse response) {

        }

        @Override
        public void onError(String errMsg, int errCode) {

        }
    }
);

// First of let's create an extra data for a channel.
struct Product: Codable {
    let id: String
    let name: String
    let price: Int
}

struct AttachmentData: Codable {
    let info: String
}

// Update your extra data types for the decoding.
ExtraData.decodableTypes = [.channel(ChannelInfo.self),
                            .message(Product.self),
                            .attachment(AttachmentData.self)]

// Create an extra data for message.
let iPhone = Product(id: "iPhone12,3", name: "iPhone 11 Pro", price: 999)

// Create an extra data for the attachment.
let fish = AttachmentData(info: "Just a fish to increase sales.")

// Create attachment.
let attachment = Attachment(type: .image,
                            title: "A fish",
                            imageURL: URL(string: "https://bit.ly/2K74TaG")!,
                            extraData: fish)

// Create a message with the extra data and attachments.
let message = Message(text: "We have a new iPhone 11 Pro. Do you want to buy it?",
                      attachments: [attachment],
                      extraData: iPhone,
                      mentionedUsers: [User(id: "josh-id", name: "Josh")])

channel.send(message: message).subscribe().disposed(by: disposeBag)

val message = Message()
message.text =
    "Josh I told them I was pesca-pescatarian. Which is one who eats solely fish who eat other fish."
val extraDataMessage = HashMap<String, Any>()
extraDataMessage.put("anotherCustomField", 234)
message.extraData = extraDataMessage

// add an image attachment to the message
val attachment = Attachment()
attachment.setType("image")
attachment.setImageURL("https://bit.ly/2K74TaG")
attachment.setFallback("test image")
// add some custom data to the attachment
val extraDataAttachment = HashMap<String, Any>()
extraDataAttachment.put("myCustomField", 123)
attachment.setExtraData(extraDataAttachment)

message.attachments = Arrays.asList(attachment)

// include the user ID of the mentioned user
message.setMentionedUsersId(Arrays.asList("josh-id"))

channel.sendMessage(message,
    object : MessageCallback {
        override fun onSuccess(response: MessageResponse) {
            println(response)
        }

        override fun onError(errMsg: String, errCode: Int) {
            println("$errMsg: $errCode")
        }
    }
)

There are 4 built-in fields for the message:

Note that both the message and the attachments can contain custom fields. By default Stream’s frontend components support the following attachment types:

• Audio
• Video
• Image
• Text

• Embedding products (photos, descriptions, outbound links, etc.)
• Sharing of a users’ location

When you post a message on a Channel, there are a few things that happen on the server:

1. The text markdown format is parsed.
2. The first URL found in message.text is enriched and additional information is added automatically. This gives you a preview of the images, videos, etc. from the open-graph data on the associated page.
3. Any slash commands such as /giphy, /imgur, /ban, /flag etc. are handled.

Messages containing URLs will have a generated attachment with the following structure:

Below is an example of URL enrichment as well as the resulting message structure:

const response = await channel.sendMessage({
    text: 'Check this bear out https://imgur.com/r/bears/4zmGbMN'
})

// response message object
{
    "id": "thierry-5e9619ec-1a0d-443b-ab26-c597ed7af3d0",
    "text": "Check this bear out https://imgur.com/r/bears/4zmGbMN",
    "html": "<p>Check this bear out <a href=\"https://imgur.com/r/bears/4zmGbMN\" rel=\"nofollow\">https://imgur.com/r/bears/4zmGbMN</a></p>\n",
    "type": "regular",
    "user": {
      "id": "thierry",
      "role": "user",
      "created_at": "2019-04-03T14:42:47.087869Z",
      "updated_at": "2019-04-16T09:20:03.982283Z",
      "last_active": "2019-04-16T11:23:51.168113408+02:00",
      "online": true
    },
    "attachments": [
      {
        "type": "image",
        "author_name": "Imgur",
        "title": "An update: Dushi made it safe to Bear Sanctuary Müritz",
        "title_link": "https://imgur.com/4zmGbMN",
        "text": "1678 views on Imgur",
        "image_url": "https://i.imgur.com/4zmGbMN.jpg?fb",
        "thumb_url": "https://i.imgur.com/4zmGbMN.jpg?fb",
        "og_scrape_url": "https://imgur.com/r/bears/4zmGbMN"
      }
    ],
    "latest_reactions": [],
    "own_reactions": [],
    "reaction_counts": null,
    "reply_count": 0,
    "created_at": "2019-04-16T09:40:04.665274Z",
    "updated_at": "2019-04-16T09:40:04.665274Z"
  }

Message message = new Message();
message.setText("Check this bear out https://imgur.com/r/bears/4zmGbMN");

// send the message to the channel
channel.sendMessage(message,
  new MessageCallback() {
      @Override
      public void onSuccess(MessageResponse response) {        
      }

      @Override
      public void onError(String errMsg, int errCode) {
      }
});

// response message object
//    {
//        "id": "thierry-5e9619ec-1a0d-443b-ab26-c597ed7af3d0",
//            "text": "Check this bear out https://imgur.com/r/bears/4zmGbMN",
//            "html": "<p>Check this bear out <a href=\"https://imgur.com/r/bears/4zmGbMN\" rel=\"nofollow\">https://imgur.com/r/bears/4zmGbMN</a></p>\n",
//            "type": "regular",
//            "user": {
//        "id": "thierry",
//                "role": "user",
//                "created_at": "2019-04-03T14:42:47.087869Z",
//                "updated_at": "2019-04-16T09:20:03.982283Z",
//                "last_active": "2019-04-16T11:23:51.168113408+02:00",
//                "online": true
//    },
//        "attachments": [
//        {
//            "type": "image",
//                "author_name": "Imgur",
//                "title": "An update: Dushi made it safe to Bear Sanctuary Müritz",
//                "title_link": "https://imgur.com/4zmGbMN",
//                "text": "1678 views on Imgur",
//                "image_url": "https://i.imgur.com/4zmGbMN.jpg?fb",
//                "thumb_url": "https://i.imgur.com/4zmGbMN.jpg?fb",
//                "og_scrape_url": "https://imgur.com/r/bears/4zmGbMN"
//        }
//    ],
//        "latest_reactions": [],
//        "own_reactions": [],
//        "reaction_counts": null,
//            "reply_count": 0,
//            "created_at": "2019-04-16T09:40:04.665274Z",
//            "updated_at": "2019-04-16T09:40:04.665274Z"
//    }

// TODO

Message message = new Message();
message.setText("Check this bear out https://imgur.com/r/bears/4zmGbMN");

// send the message to the channel
channel.sendMessage(message,
  new MessageCallback() {
      @Override
      public void onSuccess(MessageResponse response) {        
      }

      @Override
      public void onError(String errMsg, int errCode) {
      }
  });


// response message object
//    {
//        "id": "thierry-5e9619ec-1a0d-443b-ab26-c597ed7af3d0",
//            "text": "Check this bear out https://imgur.com/r/bears/4zmGbMN",
//            "html": "<p>Check this bear out <a href=\"https://imgur.com/r/bears/4zmGbMN\" rel=\"nofollow\">https://imgur.com/r/bears/4zmGbMN</a></p>\n",
//            "type": "regular",
//            "user": {
//        "id": "thierry",
//                "role": "user",
//                "created_at": "2019-04-03T14:42:47.087869Z",
//                "updated_at": "2019-04-16T09:20:03.982283Z",
//                "last_active": "2019-04-16T11:23:51.168113408+02:00",
//                "online": true
//    },
//        "attachments": [
//        {
//            "type": "image",
//                "author_name": "Imgur",
//                "title": "An update: Dushi made it safe to Bear Sanctuary Müritz",
//                "title_link": "https://imgur.com/4zmGbMN",
//                "text": "1678 views on Imgur",
//                "image_url": "https://i.imgur.com/4zmGbMN.jpg?fb",
//                "thumb_url": "https://i.imgur.com/4zmGbMN.jpg?fb",
//                "og_scrape_url": "https://imgur.com/r/bears/4zmGbMN"
//        }
//    ],
//        "latest_reactions": [],
//        "own_reactions": [],
//        "reaction_counts": null,
//            "reply_count": 0,
//            "created_at": "2019-04-16T09:40:04.665274Z",
//            "updated_at": "2019-04-16T09:40:04.665274Z"
//    }

Messages returned by the API follow this structure:

Message Types

Chat supports different types of messages. The type of the message is set by the APIs or by chat bots and custom commands.

You can get a single message by its ID using the getMessage endpoint:

await client.getMessage(messageID);

client.getMessage(messageId, new MessageCallback(){
    @Override
    public void onSuccess(MessageResponse response) {
        
    }

    @Override
    public void onError(String errMsg, int errCode) {

    }
});

Client.shared.message(with: messageId)
    .subscribe(onNext: { response in
        print(response)
    })
    .disposed(by: disposeBag)

channel.getMessage(messageID, object : MessageCallback {
    override fun onSuccess(response: MessageResponse) {}

    override fun onError(errMsg: String, errCode: Int) {}
})

You can edit a message by calling the updateMessage endpoint and including a message with an ID – the ID field is required when editing a message:

const message = { id: 123, text: 'the edited version of my text' };
const updateResponse = await client.updateMessage(message);

// update some field of the message
message.setText("my updated text");

// send the message to the channel
client.updateMessage(message, new MessageCallback(){
    @Override
    public void onSuccess(MessageResponse response) {

    }

    @Override
    public void onError(String errMsg, int errCode) {

    }
});

let editedMessage = Message(id: message.id, text: newText)
channel.send(message: editedMessage).subscribe().disposed(by: disposeBag)

// update some field of the message
message.setText("my updated text");

// send the message to the channel
channel.updateMessage(message, object : MessageCallback {
    override fun onSuccess(response: MessageResponse) {}

    override fun onError(errMsg: String, errCode: Int) {}
})

You can lete a message by calling the removeMessage endpoint and including a message with an ID:

await client.deleteMessage(messageID);

client.deleteMessage("messageID", new MessageCallback(){
    @Override
    public void onSuccess(MessageResponse response) {

    }

    @Override
    public void onError(String errMsg, int errCode) {

    }
});

// Delete a message.
channel.delete(message: message).subscribe().disposed(by: disposeBag)
// or
message.delete().subscribe().disposed(by: disposeBag)

channel.deleteMessage(messageID, object : MessageCallback {
    override fun onSuccess(response: MessageResponse) {}

    override fun onError(errMsg: String, errCode: Int) {}
})

The channel.sendImage and channel.sendFile methods make it easy to upload files. Note that this functionality defaults to using the Stream CDN. If you would like, you can easily change the logic to upload to your own CDN of choice.

const promises = [
    channel.sendImage(
        fs.createReadStream('./helloworld.jpg'),
        'hello_world1.jpg',
    ),
    channel.sendImage(
        fs.createReadStream('./helloworld.jpg'),
        'hello_world2.jpg',
    ),
];
const results = await Promise.all(promises);
const attachments = results.map(response => {
    return {
        type: 'image',
        thumb_url: response.file,
        asset_url: response.file,
    };
});
const response = await channel.sendMessage({
    text: 'Check out what I have uploaded in parallel',
    attachments,
});
expect(response.message.attachments).to.equal(attachments);

// upload an image
channel.sendImage(filePath, new UploadFileCallback() {
            @Override
            public void onSuccess(Object o) {
                
            }

            @Override
            public void onError(String errMsg, int errCode) {

            }

            @Override
            public void onProgress(Object o) {

            }
});

// upload a file
channel.sendFile(filePath new UploadFileCallback() {
            @Override
            public void onSuccess(Object o) {
                
            }

            @Override
            public void onError(String errMsg, int errCode) {

            }

            @Override
            public void onProgress(Object o) {

            }
});

// Upload UIImage.
if let imageData = image.jpegData(compressionQuality: 0.9) {
    channel.sendImage(fileName: "my_photo", 
                      mimeType: AttachmentFileType.jpeg.mimeType,
                      imageData: imageData)
        .observeOn(MainScheduler.instance)
        .subscribe(
            onNext: { response in
                print(response.progress)
            },
            onCompleted: { 
                print("The image was uploaded")
            })
        .disposed(by: disposeBag)
}

// Upload a local file with URL.
if let fileData = try? Data(contentsOf: url) {
    channel.sendFile(fileName: "my_file", 
                      mimeType: AttachmentFileType.generic.mimeType // "application/octet-stream"
                      imageData: fileData)
        .observeOn(MainScheduler.instance)
        .subscribe(
            onNext: { response in
                print(response.progress)
            },
            onCompleted: { 
                print("The file was uploaded")
            })
        .disposed(by: disposeBag)
}

// upload an image
channel.sendImage(filePath, object : UploadFileCallback {
    override fun onSuccess(o: Object) {
       
    }

    override fun onError(errMsg: String, errCode: Int) {
        
    }

    override fun onProgress(o: Object) {
        
    }
})

// upload a file
channel.sendFile(filePath, object : UploadFileCallback {
    override fun onSuccess(o: Object) {
       
    }

    override fun onError(errMsg: String, errCode: Int) {
        
    }

    override fun onProgress(o: Object) {
        
    }
})

In the example above, note how the message attachments are created after the files are uploaded. The React components support regular uploads, clipboard pasting, drag and drop, as well as URL enrichment via built-in open-graph scraping. As a bonus, the Stream CDN will automatically handle image resizing for you.

Stream Chat has built-in support for user Reactions. Common examples are likes, comments, love, etc. Reactions can be customized so that you are able to use any type of Reaction your application requires.

Similar to other objects in Stream Chat, Reactions allow you to add custom data to the Reaction. This is helpful if you want to customize the Reaction logic. Custom data for reactions can be at most 1KB.

const reaction = await channel.sendReaction(messageID, {
    type: 'love',
    myCustomField: 123,
});

Reaction reaction = new Reaction();
reaction.setMessageId("message-id-here");
reaction.setType("like");

channel.sendReaction(reaction, new MessageCallback() {
    @Override
    public void onSuccess(MessageResponse response) {
        
    }

    @Override
    public void onError(String errMsg, int errCode) {

    }
});

message.addReaction(.like).subscribe().disposed(by: disposeBag)

val reaction = new Reaction()
reaction.setMessageId("message-id-here");
reaction.setType("like");

channel.sendReaction(reaction, object : MessageCallback {
    override fun onSuccess(response: MessageResponse) {}

    override fun onError(errMsg: String, errCode: Int) {}
})

Removing a reaction

await channel.deleteReaction(messageID, 'love');

channel.deleteReaction(messageID, "like", new MessageCallback() {
    @Override
    public void onSuccess(MessageResponse response) {

    }

    @Override
    public void onError(String errMsg, int errCode) {

    }
});

message.deleteReaction(.like).subscribe().disposed(by: disposeBag)

channel.deleteReaction(messageID, "like", object : MessageCallback {
    override fun onSuccess(response: MessageResponse) {}

    override fun onError(errMsg: String, errCode: Int) {}
})

Paginate reactions

Messages returned by the APIs automatically include the 10 most recent reactions. You can also retrieve more reactions and paginate like this:

// get the first 10 reactions
const response = await channel.getReactions(messageID, { limit: 5 });

// get 3 reactions past the first 10
const response = await channel.getReactions(messageID, { limit: 3, offset: 10 });

// get the first 10 reactions
channel.getReactions(messageID, new GetReactionsCallback(){
        @Override
        public void onSuccess(GetReactionsResponse response) {
        }

        @Override
        public void onError(String errMsg, int errCode) {
        }
    }
);

// get 3 reactions past the first 10
channel.getReactions(messageID, new PaginationOptions.Builder().offset(10).limit(3).build(),
    new GetReactionsCallback(){
        @Override
        public void onSuccess(GetReactionsResponse response) {
        }

        @Override
        public void onError(String errMsg, int errCode) {
        }
    }
);

// TODO

// get the first 10 reactions
channel.getReactions(messageID, object : GetReactionsCallback {
    override fun onSuccess(response: GetReactionsResponse) {

    }

    override fun onError(errMsg: String, errCode: Int) {

    }
})

// get 3 reactions past the first 10
channel.getReactions(messageID, PaginationOptions.Builder().offset(10).limit(3).build(),
  object : GetReactionsCallback {
      fun onSuccess(response: GetReactionsResponse) {

      }

      fun onError(errMsg: String, errCode: Int) {

      }
})

Threads and replies provide your users with a way to go into more detail about a specific topic.

This can be very helpful to keep the conversation organized and reduce noise. To create a thread you simply send a message with a parent_id. Have a look at the example below:

const replyResponse = await channel.sendMessage({
    text: 'replying to a message',
    parent_id: parentID,
    show_in_channel: false,
});

// set the parent id to make sure a message shows up in a thread
Message message = new Message();
message.setText("hello world");
message.setParentId(parentMessage.getId());

// send the message to the channel
channel.sendMessage(message, new MessageCallback() {
    @Override
    public void onSuccess(MessageResponse response) {
        
    }

    @Override
    public void onError(String errMsg, int errCode) {

    }
});

let message = Message(text: "Hello world!", parentId: parentMessage.id)
channel.send(message: message).subscribe().disposed(by: disposeBag)

// set the parent id to make sure a message shows up in a thread
Message message = new Message();
message.setText("hello world");
message.setParentId(parentMessage.getId());

// send the message to the channel
channel.sendMessage(message, new MessageCallback() {
    override fun onSuccess(response: MessageResponse) {

    }

    override fun onError(errMsg: String, errCode: Int) {

    }
});

If you specify show_in_channel, the message will be visible both in a thread of replies as well as the main Channel.

Message search is built-in to the chat API. You can enable/disable the search indexing per chat type. The command shown below selects the channels in which John is a member. Next it searches the messages in those channels for the keyword “'supercalifragilisticexpialidocious'”:

const filters = { members: { $in: ['john'] } };
const response = await client.search(
   filters,
   'supercalifragilisticexpialidocious',
   { limit: 2, offset: 0 },
);

final ArrayList<String> searchUsersList = new ArrayList<>();
searchUsersList.add("john");

final FilterObject filter = Filters.in("members", searchUsersList);

SearchMessagesRequest searchMessagesRequest = new SearchMessagesRequest(filter,
        "supercalifragilisticexpialidocious")
        .withLimit(2)
        .withOffset(0);

client.searchMessages(searchMessagesRequest,
    new SearchMessagesCallback() {
        @Override
        public void onSuccess(SearchMessagesResponse response) {

        }

        @Override
        public void onError(String errMsg, int errCode) {

        }
});

// Search with default filter where the current user is a member of channels.
// Default pagination is 20 messages.
Client.shared.search(query: "supercalifragilisticexpialidocious")
    .subscribe(onNext: { messages in
        print(messages)
    })
    .disposed(by: disposeBag)

// A custom filter and the next page for the results.
Client.shared.search(filter: filter, query: "supercalifragilisticexpialidocious", pagination: .limit(20) + .offset(20))
    .subscribe(onNext: { messages in
        print(messages)
    })
    .disposed(by: disposeBag)

client.searchMessages(
  SearchMessagesRequest(
      Filters.`in`("members", listOf("john")),
      "supercalifragilisticexpialidocious")
      .withLimit(2)
      .withOffset(0),
  object : SearchMessagesCallback {
      override fun onSuccess(response: SearchMessagesResponse?) {
          
      }

      override fun onError(errMsg: String?, errCode: Int) {
     
      }
})

Pagination works via the standard limit and offset parameters. The first arguments, filters, uses a mongoose style query expression. Note that we don’t run Mongo on the backend, so only a subset of the standard filters are supported.

As soon as you call watch on a Channel or queryChannels you’ll start to listen to these events. You can hook into specific events:

channel.on('message.deleted', event => {
    console.log('event', event);
    console.log('channel.state', channel.state);
});

Integer channelSubscriptionId = channel.addEventHandler(new ChatChannelEventHandler() {
  @Override
  public void onMessageNew(Event event) {
      event.getMessage();
  }
}
// channel.removeEventHandler(channelSubscriptionId) to remove it

channel.onEvent(.messageNew)
    .subscribe(onNext: { event in
        print(event)
    })
    .disposed(by: disposeBag)

val channelSubscriptionId = client.addEventHandler(object : ChatChannelEventHandler() {
    override fun onMessageNew(event: Event) {
        event.getMessage()
    }
})
// channel.removeEventHandler(channelSubscriptionId) to remove it

You can also listen to all events at once:

channel.on(event => {
    console.log('event', event);
    console.log('channel.state', channel.state);
});

Integer channelSubscriptionId = channel.addEventHandler(new ChatChannelEventHandler() {
  @Override
  public void onAnyEvent(Event event) {
      event.getType();
  }
}

channel.onEvent()
    .subscribe(onNext: { event in
        print(event)
    })
    .disposed(by: disposeBag)

channelSubscriptionId = channel.addEventHandler(object : ChatChannelEventHandler() {
  override fun onAnyEvent(event: Event) {
      event.getType();
  }
}

Client events

Not all events are specific to channels, events like: user status has changed, users' unread count has changed and other notifications are sent as client events. These events should be registered on the client directly:

// subscribe to all client events and log the unread_count field
client.on(event => {
	if (event.total_unread_count != null) {
		console.log(`unread messages count is now: ${event.total_unread_count}`);
	}
	if (event.unread_channels != null) {
		console.log(`unread channels count is now: ${event.unread_channels}`);
	}
});

// the initial count of unread messages is returned by client.setUser
const r = await client.setUser(user, userToken);
console.log(`you have ${r.me.total_unread_count} unread messages on ${r.me.unread_channels} channels`);

// receive an event whenever any of the channels that you are watching changes
Integer subscriptionId = client.addEventHandler(new ChatEventHandler() {
    @Override
    public void onMessageNew(Channel channel, Event event) {
        event.getMessage();
    }
});

// Subscribe for user presence events.
Client.shared.onEvent(.userPresenceChanged)
    .subscribe(onNext: { event in
        print(event)
    })
    .disposed(by: disposeBag)

// Unread count globally.
Client.shared.unreadCount
    .subscribe(onNext: { unreadCount in
        print(unreadCount)
    })
    .disposed(by: disposeBag)

// Unread count for a channel.
channel.unreadCount
    .subscribe(onNext: { unreadCount in
        print(unreadCount)
    })
    .disposed(by: disposeBag)

// receive an event whenever any of the channels that you are watching changes
val subscriptionId = client.addEventHandler(object : ChatEventHandler() {
    override fun onMessageNew(channel: Channel, event: Event) {
        event.getMessage()
    }
})

Connection events

The official SDKs make sure that a connection to Stream is kept alive at all times and that chat state is recovered when the user's internet connection comes back online. Your application can subscribe to changes to the connection using client events.

client.on('connection.changed', e => {
    if (e.online) {
        console.log('the connection is up!');
    } else {
        console.log('the connection is down!');
    };
});

Integer subscriptionId = client.addEventHandler(new ChatEventHandler() {
    @Override
    public void onConnectionChanged(Event event) {
        event.getOnline();
    }
});

// Get all connection states.
Client.shared.connection
    .subscribe(onNext: { connection in
        print(connection)
    })
    .disposed(by: disposeBag)

// Get an event when only the client is connected.
Client.shared.connection.connected()
    .subscribe(onNext: {
        print("You are online")
    })
    .disposed(by: disposeBag)

val subscriptionId = client.addEventHandler(object : ChatEventHandler() {
    override fun onConnectionChanged(event: Event) {
        event.getOnline()
    }
})

Stop listening for events

It is a good practice to de-register event handlers once they are not in use any more. Doing so will save you from performance degradations coming from memory leaks or even from errors and exceptions (ie. null pointer exceptions)

// remove the handler from all client events
client.off(myClientEventHandler);

// remove the handler from all events on a channel
channel.off(myChannelEventHandler);

// remove the handler for all "message.new" events on the channel
channel.off("message.new", myChannelEventHandler);

// remove the event handler based on the subscription ID returned by `client.addEventHandler`
client.removeEventHandler(subscriptionId);

// remove the event handler based on the subscription ID returned by `channel.addEventHandler`
channel.removeEventHandler(subscriptionId);

channel.stopWatching().subscribe().disposed(by: disposeBag)

// remove the event handler based on the subscription ID returned by `client.addEventHandler`
client.removeEventHandler(subscriptionId)

// remove the event handler based on the subscription ID returned by `channel.addEventHandler`
channel.removeEventHandler(subscriptionId)

All official SDKs support typing events out of the box and are handled out of the box on all channels with the typing_events featured enabled.

There are two types of events related to user typing: "typing.start" and "typing.stop", both are sent client-side in response to user input. If you are building your own chat integration on top of an API client instead of using an SDK, we recommend following a few basic rules:

1. Send the "typing.start" only the first time a user starts typing
2. Once the user stops typing for longer than two seconds, send the "typing.stop" event

// sends an event typing.start to all channel participants
await channel.keystroke();

// sends an event typing.stop to all channel participants
await channel.stopTyping();

// sends a typing.start event if it's been more than 3000 ms since the last event
channel.keystroke(new EventCallback() {
    @Override
    public void onSuccess(EventResponse response) {
    }

    @Override
    public void onError(String errMsg, int errCode) {
    }

});

// sends an event typing.stop to all channel participants
channel.stopTyping(new EventCallback() {
    @Override
    public void onSuccess(EventResponse response) {
    }

    @Override
    public void onError(String errMsg, int errCode) {
    }

});

// Send a typing start event.
channel.send(eventType: .typingStart).subscribe().disposed(by: disposeBag)

// Send a typing stop event.
channel.send(eventType: .typingStop).subscribe().disposed(by: disposeBag)

// sends a typing.start event if it's been more than 3000 ms since the last event
channel.keystroke()

// sends an event typing.stop to all channel participants
channel.stopTyping()

Notification events help you update your UI (web+mobile, multiple tabs, ...) even if you're not watching a particular channel. Notification events are sent to channel members that are not currently watching the channel. There are 6 notification events:

1. notification.message_new
2. notification.mark_read
3. notification.invited
4. notification.invite_accepted
5. notification.added_to_channel
6. notification.removed_from_channel
7. notification.mutes_updated
8. notification.channel_deleted
9. notification.channel_truncated

Notification events are triggered at the client level. Here's an example of how you can render a new conversation when a user is added to a channel.

client.on('notification.added_to_channel', (event) => {
    console.log(`you were just added to channel ${event.channel}`)
});

Integer subscriptionId = client.addEventHandler(new ChatEventHandler() {
  @Override
  public void onNotificationAddedToChannel(Channel channel, Event event) {

  }
});

Client.shared.onEvent(.notificationAddedToChannel)
    .subscribe(onNext: { event in
        print(event)
    })
    .disposed(by: disposeBag)

val subscriptionId = client.addEventHandler(object : ChatEventHandler() {
    override fun onNotificationAddedToChannel(channel: Channel, event: Event) {
       
    }
})

Here’s how you can initialize a single channel:

const conversation = authClient.channel('messaging', 'thierry-tommaso-1', {
    name: 'Founder Chat',
    image: 'http://bit.ly/2O35mws',
    members: ['thierry', 'tommaso'],
});

List<String> memberIDs = new ArrayList<>();
memberIDs.add("john");
memberIDs.add("jack");

HashMap<String, Object> extraData = new HashMap<>();
extraData.put("name", "Bender");
extraData.put("image", "https://bit.ly/321RmWb");
extraData.put("members", memberIDs);

Channel channel = client.channel(channelType, channelID, extraData);

// Create an extra data for a channel.
struct ChannelInfo: Codable {
    let info: String
}

// Register once your extra data types for the decoding.
ExtraData.decodableTypes = [.channel(ChannelInfo.self)]

let info = ChannelInfo(info: "A general channel.")
let channel = Channel(type: .messaging, id: "general", extraData: info)

val memberIDs = ArrayList<String>()
memberIDs.add("john")
memberIDs.add("jack")

val extraData = HashMap<String, Any>()
extraData.put("name", "Bender")
extraData.put("image", "https://bit.ly/321RmWb")
extraData.put("members", memberIDs)

val channel = client.channel(channelType, channelID, extraData)

Once you watch a channel, you will start receiving events for that channel. More info on that here.

To start watching a channel:

const conversationState = await conversation.watch();

ChannelWatchRequest request = new ChannelWatchRequest().
	withMessages(Constant.DEFAULT_LIMIT);

channel.watch(request,
  new QueryWatchCallback() {
      @Override
      public void onSuccess(ChannelState response) {
      }

      @Override
      public void onError(String errMsg, int errCode) {
      }
  }
);

channel.watch().subscribe().disposed(by: disposeBag)

val request = ChannelWatchRequest().withMessages(Constant.DEFAULT_LIMIT)

channel.watch(request, object : QueryWatchCallback {
    override fun onSuccess(response: ChannelState) {
    }

    override fun onError(errMsg: String, errCode: Int) {
    }
 })

    
    curl -i -X POST -d "{\"state\":true,\"subscribe\":true}"\
    -H "Content-Type: application/json" \
    -H "Stream-Auth-Type: jwt" \
    -H "Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiamxhaGV5In0.OkDbpbujWJ-XIVHaf00Dnqt3v8Yp_nQ6CGzm-Z4QUVc" \
    "https://chat-us-east-c1.stream-io-api.com/channels/messaging/thiery-tommaso/query?api_key=YOUR_API_KEY"
    
    

Unwatching

To stop watching a channel:

await conversation.stopWatching();

channel.stopWatching(new CompletableCallback() {
    @Override
    public void onSuccess(CompletableResponse response) {
    }

    @Override
    public void onError(String errMsg, int errCode) {
    }
});

channel.stopWatching().subscribe().disposed(by: disposeBag)

channel.stopWatching(object : CompletableCallback {
    override fun onSuccess(response: CompletableResponse) {
    }

    override fun onError(errMsg: String, errCode: Int) {
    }
})

      
      curl -i -X POST -d "{\"user_id\":\"john\"}"\
      -H "Content-Type: application/json" \
      -H "Stream-Auth-Type: jwt" \
      -H "Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiam9obiJ9.TxsU2JMbx7UXQ166lRabT6h7pAf415tLLKhJEZO_Kbg" \
      "https://chat-us-east-c1.stream-io-api.com/channels/messaging/thiery-tommaso/stop-watching?api_key=YOUR_API_KEY"
      
    

If you’re building a similar application to Facebook Messenger or Intercom, you’ll want to show a list of Channels. The Chat API supports MongoDB style queries to make this easy to implement. As an example, let's say that you want to query the last conversations I participated in sorted by last_message_at.

Here’s an example of how you can query the list of Channels:

const filter = { members: { $in: ['thierry'] } };
const sort = { last_message_at: -1 };

const channels = await authClient.queryChannels(filter, sort, {
    watch: true,
    state: true,
});
for (const c of channels) {
    console.log(c.custom.name, c.cid);
}

FilterObject filter = and(eq("type", "messaging"));
QuerySort sort = new QuerySort().desc("last_message_at");

QueryChannelsRequest request = new QueryChannelsRequest(filter, sort)
  .withLimit(pageSize)
  .withWatch() // receive events about new messages or any other change to the channel
  .withPresence() // optionally observe user presence changes
  .withMessageLimit(20);

QueryChannelListCallback queryCallback = new QueryChannelListCallback() {
    @Override
    public void onSuccess(QueryChannelsResponse response) {
    }

    @Override
    public void onError(String errMsg, int errCode) {
    }
};

client().queryChannels(request, queryCallback);

// Create a filter for channels by the messaging type.
let filter = Filter.key("type", .equal(to: "messaging"))
let sorting = [Sorting("last_message_at", isAscending: false)]

// Create a channels query.
let query = ChannelsQuery(filter: filter,
                          // Sort channels by the last message date created.
                          sort: sorting,
                          // A pagination for channels.
                          pagination: .limit(25),
                          // A pagination for messages for the each channel.
                          messageLimit: .limit(20),
                          // Options for return channels with messages,
                          // start watching for the each channel,
                          // and observe user presence changes.
                          options: [.state, .watch, .presence])

// Make a request for channels.
Client.shared.channels(query: query)
    .subscribe(onNext: { channelResponses in
        print(channelResponses)
    })
    .disposed(by: disposeBag)

val filter = and(eq("type", "messaging"))
val sort = QuerySort().desc("last_message_at")

val request = QueryChannelsRequest(filter, sort)
    .withLimit(pageSize)
    .withWatch() // receive events about new messages or any other change to the channel
    .withPresence() // optionally observe user presence changes
    .withMessageLimit(20)

val queryCallback = object : QueryChannelListCallback {
    override fun onSuccess(response: QueryChannelsResponse) {
       
    }

    override fun onError(errMsg: String, errCode: Int) {
       
    }
}
client.queryChannels(request, queryCallback)

Response

The result of querying a channel is a list of ChannelStateobjects. The event system ensures that your local copy of the Channel state stays up to date. The state exposes the following information:

state.typing = Immutable({});
state.read = Immutable({});
state.messages = Immutable([]);
state.mutedUsers = Immutable([]);
state.watchers = Immutable({});
state.watcher_count = 0;
state.members = Immutable({});

// see ChannelState class

// TODO

// see ChannelState class

Paginating Channel Lists

Query channels requests can be paginated similar to how it's done for other endpoints.

// get the 20 channels with Thierry as a member and skip first 10

const filter = { members: { $in: ['thierry'] } };
const sort = { last_message_at: -1 };

const channels = await authClient.queryChannels(filter, sort, {
    limit: 20, offset: 10
});

QueryChannelsRequest request = new QueryChannelsRequest(filter, sort)
  .withLimit(pageSize)
  .withOffset(10)
  .withMessageLimit(20);

        
client.queryChannels(request, new QueryChannelListCallback() {
    @Override
    public void onSuccess(QueryChannelsResponse response) {
        //
    }

    @Override
    public void onError(String errMsg, int errCode) {
        //
    }
});

// Create a channels query with a pagination for the next page.
let query = ChannelsQuery(filter: filter,
                          sort: sorting,
                          pagination: .limit(25) + .offset(25),
                          // A pagination for messages for the each channel.
                          messageLimit: .limit(20),
                          options: .all)

// Make a request for channels.
Client.shared.channels(query: query)
    .subscribe(onNext: { channelResponses in
        print(channelResponses)
    })
    .disposed(by: disposeBag)

val request = QueryChannelsRequest(filter, sort)
            .withLimit(pageSize)
            .withOffset(10)
            .withMessageLimit(20)


client.queryChannels(request, object : QueryChannelListCallback {
    override fun onSuccess(response: QueryChannelsResponse) {    
            
    }

    override fun onError(errMsg: String, errCode: Int) {   
             
    }
})

const result = await channel.query({
    messages: { limit: 2, id_lte: 123 } ,
    members: { limit: 2, offset: 0 } ,
    watchers: { limit: 2, offset: 0 },
});

ChannelQueryRequest request = new ChannelQueryRequest()
    .withMessages(LESS_THAN_OR_EQUAL, "message-123", 2)
    .withMembers(2, 0)
    .withWatchers(2, 0);

channel.query(request, new QueryChannelCallback() {
    @Override
    public void onSuccess(ChannelState response) {

    }

    @Override
    public void onError(String errMsg, int errCode) {

    }
});

channel.query(pagination: .limit(30) + .lessThan(firstMessage.id))
    .subscribe(onNext: { response in
        print(response)
    })
    .disposed(by: disposeBag)

val request = new ChannelQueryRequest()
    .withMessages(LESS_THAN_OR_EQUAL, "message-123", 2)
    .withMembers(2, 0)
    .withWatchers(2, 0);

channel.query(request, object: QueryChannelCallback() {
    
    override fun onSuccess(response : ChannelState) {

    }

    override fun onError(errMsg : String, errCode : int) {

    }
});

As shown above, pagination for messages uses limit & id_lte parameters for pagination. The term id_lte stands for ID less than or equal. The ID-based pagination improves performance and prevents issues related to the list of messages changing while you’re paginating.

For members and watchers, we use limit and offset parameters.

    
    curl -i -X POST -d "{\"messages\":{\"limit\":2,\"id_lte\":123},\"members\":{\"limit\":2,\"offset\":0},\"watchers\":{\"limit\":2,\"offset\":0}}"\
    -H "Content-Type: application/json" \
    -H "Stream-Auth-Type: jwt" \
    -H "Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoidGhpZXJyeSJ9.3YMs1NzsGNdP6xm5i8FX4w9Sci48oDJe8VfFyo2kksM" \
    "https://chat-us-east-c1.stream-io-api.com/channels/messaging/thiery-tommaso/query?api_key=YOUR_API_KEY"
    
    

You can edit a Channel using the update method:

const response = await channel.update(
    {
        name: 'myspecialchannel',
        color: 'green',
    },
    { text: 'Thierry changed the channel color to green' },
);

channel.update(new ChannelCallback() {
    @Override
    public void onSuccess(ChannelResponse response) {
        
    }

    @Override
    public void onError(String errMsg, int errCode) {

    }
});

channel.update(name: "New name", imageURL: imageURL, extraData: channelInfo)
    .subscribe(onNext: { channelResponse in
        print(channelResponse)
    })
    .disposed(by: disposeBag)

channel.update(object : ChannelCallback{
    override fun onSuccess(response: ChannelResponse) {    
            
    }

    override fun onError(errMsg: String, errCode: Int) {   
             
    }
})

    
    curl -i -X POST -d "{\"message\":{\"text\":\"Thierry changed the channel color to green\"},\"data\":{\"name\":\"myspecialchannel\",\"color\":\"green\"}}"\
    -H "Content-Type: application/json" \
    -H "Stream-Auth-Type: jwt" \
    -H "Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoidGhpZXJyeSJ9.3YMs1NzsGNdP6xm5i8FX4w9Sci48oDJe8VfFyo2kksM" \
    "https://chat-us-east-c1.stream-io-api.com/channels/messaging/thiery-tommaso?api_key=YOUR_API_KEY"
    
    

Adding/removing channel members

await channel.addMembers(['thierry', 'josh']);
await channel.removeMembers(['tommaso']);

// adding members
List<String> memberIDs = new ArrayList<>();
memberIDs.add("john");
channel.addMembers(memberIDs, new ChannelCallback() {
    @Override
    public void onSuccess(ChannelResponse response) {

    }

    @Override
    public void onError(String errMsg, int errCode) {

    }
});


// removing members
List<String> memberIDs = new ArrayList<>();
memberIDs.add("john");
channel.removeMembers(memberIDs, new ChannelCallback() {
    @Override
    public void onSuccess(ChannelResponse response) {
        
    }

    @Override
    public void onError(String errMsg, int errCode) {

    }
});

let user = User(id: "john", name: "John")

// Add a member.
channel.add(user.asMember)
    .subscribe(onNext: { channelResponse in
        print(channelResponse)
    })
    .disposed(by: disposeBag)

// Remove a member.
channel.remove(user.asMember)
    .subscribe(onNext: { channelResponse in
        print(channelResponse)
    })
    .disposed(by: disposeBag)

// adding members
val memberIDs = ArrayList<String>()
memberIDs.add("john")
channel.addMembers(memberIDs, object : ChannelCallback{
    override fun onSuccess(response: ChannelResponse) {    
            
    }

    override fun onError(errMsg: String, errCode: Int) {   
             
    }
})

// removing members
val memberIDs = ArrayList<String>()
memberIDs.add("john")
channel.removeMembers(memberIDs, object : ChannelCallback{
    override fun onSuccess(response: ChannelResponse) {    
            
    }

    override fun onError(errMsg: String, errCode: Int) {   
             
    }
})

    
    #add thiery
    curl -i -X POST -d "{\"add_members\":[\"thierry\"]}"\
    -H "Content-Type: application/json" \
    -H "Stream-Auth-Type: jwt" \
    -H "Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoidGhpZXJyeSJ9.3YMs1NzsGNdP6xm5i8FX4w9Sci48oDJe8VfFyo2kksM" \
    "https://chat-us-east-c1.stream-io-api.com/channels/messaging/thiery-tommaso?api_key=YOUR_API_KEY"

    #remove tommaso
    curl -i -X POST -d "{\"remove_members\":[\"tommaso\"]}"\
    -H "Content-Type: application/json" \
    -H "Stream-Auth-Type: jwt" \
    -H "Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoidGhpZXJyeSJ9.3YMs1NzsGNdP6xm5i8FX4w9Sci48oDJe8VfFyo2kksM" \
    "https://chat-us-east-c1.stream-io-api.com/channels/messaging/thiery-tommaso?api_key=YOUR_API_KEY"
    
    

Adding/removing moderators to a channel

Adds users as moderators(or updates their role to moderator if already members) or removes the moderator status

• JS/Node
• Python
• Ruby
• PHP
• Java
• Go
• Swift
• C#

await channel.addModerators(['thierry', 'josh']);
await channel.demoteModerators(['tommaso']);

channel.add_moderators(["thierry", "josh"]);
channel.demote_moderators(["tommaso"]);

channel.add_moderators(["thierry", "josh"]);
channel.demote_moderators(["tommaso"]);

$channel->addModerators(["thierry", "josh"]);
$channel->demoteModerators(["tommaso"]);

// at the moment we don't have a Java client for server side usage

channel.AddModerators("thierry", "josh")
channel.DemoteModerators("tommaso")

// at the moment we don't have a Swift client for server side usage

await chan.AddModerators(new string[] { "thierry", "josh" });
await chan.DemoteModerators(new string[] { "tommaso" });

    
    #add thierry
    curl -i -X POST -d "{\"add_moderators\":[\"thierry\"]}"\
    -H "Content-Type: application/json" \
    -H "Stream-Auth-Type: jwt" \
    -H "Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzZXJ2ZXJzaWRlIjp0cnVlfQ.OYCKMIZtQ4xS9Ial_PfHcdmZgVoz0_UAjTryXpBEw44" \
    "https://chat-us-east-c1.stream-io-api.com/channels/messaging/thiery-tommaso?api_key=YOUR_API_KEY"

    #remove tommaso
    curl -i -X POST -d "{\"demote_moderators\":[\"tommaso\"]}"\
    -H "Content-Type: application/json" \
    -H "Stream-Auth-Type: jwt" \
    -H "Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzZXJ2ZXJzaWRlIjp0cnVlfQ.OYCKMIZtQ4xS9Ial_PfHcdmZgVoz0_UAjTryXpBEw44" \
    "https://chat-us-east-c1.stream-io-api.com/channels/messaging/thiery-tommaso?api_key=YOUR_API_KEY"
    
    

Inviting users

Users can be invited to a channel. When that happen, their client will receive a notification event.

const conversation = authClient.channel('messaging', 'awesome-chat', {
    name: 'Founder Chat',
    members: ['thierry', 'tommaso'],
    invites: ['nick'],
});

await conversation.create();

HashMap channelData = new HashMap<String, Object>();
channelData.put("name", "Founder Chat");
channelData.put("members", Arrays.asList("tommaso", "thierry"));
channelData.put("invites", Arrays.asList("nick"));

ChannelWatchRequest request = new ChannelWatchRequest().withData(channelData);

client.channel("messaging", "awesome-chat").watch(
    request,
    new QueryWatchCallback() {
        @Override
        public void onSuccess(ChannelState response) {
        }

        @Override
        public void onError(String errMsg, int errCode) {
        }
    }
);

// Prepare users.
let tommaso = User(id: "tommaso", name: "Tommaso").asMember
let thierry = User(id: "thierry", name: "Thierry").asMember
let nick = User(id: "nick", name: "Nick").asMember

// 1. Invite members with a creating a new channel
let channel = Channel(type: .messaging,
                      id: "awesome-chat", 
                      members: [tomasso, thierry]
                      invitedMembers: [nick])

channel.create().subscribe().disposed(by: disposeBag)

// 2. Invite user(s) to an exists channel.
channel.invite(nick).subscribe().disposed(by: disposeBag)

// TODO

Accepting an invite

// nickClient is Nick's client 
const nickChannel = nickClient.channel('messaging', 'awesome-chat');

await nickChannel.acceptInvite({
    message: { text: 'Nick accepted the chat invite.' },
});

// start watching the channel as usual
await nickChannel.watch();

nickClient.channel("messaging", "awesome-chat").acceptInvite(new ChannelCallback(){
    @Override
    public void onSuccess(ChannelResponse response) {
        
    }

    @Override
    public void onError(String errMsg, int errCode) {

    }
});

channel.acceptInvite()
    .subscribe(onNext: { channelInviteResponse in
        print(channelInviteResponse)
    })
    .disposed(by: disposeBag)

channel.acceptInvite(object : ChannelCallback{
    override fun onSuccess(response: ChannelResponse) {    
            
    }

    override fun onError(errMsg: String, errCode: Int) {   
             
    }
})

Rejecting an invite

await nickChannel.rejectInvite();

nickClient.channel("messaging", "awesome-chat").rejectInvite(new ChannelCallback(){
    @Override
    public void onSuccess(ChannelResponse response) {

    }

    @Override
    public void onError(String errMsg, int errCode) {

    }
});

channel.rejectInvite()
    .subscribe(onNext: { channelInviteResponse in
        print(channelInviteResponse)
    })
    .disposed(by: disposeBag)

channel.rejectInvite(object : ChannelCallback{
    override fun onSuccess(response: ChannelResponse) {    
            
    }

    override fun onError(errMsg: String, errCode: Int) {   
             
    }
})

You can delete a Channel using the delete method. This marks the channel as deleted and hides all the content.

const response = await myChannel.delete();

channel.delete(new ChannelCallback() {
    @Override
    public void onSuccess(ChannelResponse response) {
        //
    }

    @Override
    public void onError(String errMsg, int errCode) {
        //
    }
});

channel.delete()
    .subscribe(onNext: { channelDeletedResponse in
        print(channelDeletedResponse)
    })
    .disposed(by: disposeBag)

channel.delete(object : ChannelCallback{
    override fun onSuccess(response: ChannelResponse) {    
            
    }

    override fun onError(errMsg: String, errCode: Int) {   
             
    }
})

      
curl -i -X DELETE
-H "Content-Type: application/json" \
-H "Stream-Auth-Type: jwt" \
-H "Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoidGhpZXJyeSJ9.3YMs1NzsGNdP6xm5i8FX4w9Sci48oDJe8VfFyo2kksM" \
"https://chat-us-east-c1.stream-io-api.com/channels/messaging/thiery-tommaso?api_key=YOUR_API_KEY"
      
    

Note that if you recreate this channel it will show up empty. Recovering the old messages is currently not supported via the API.

Hiding a channel will remove it from query channel requests for that user until a new message is added.

// hides the channel until a new message is added there
await nickChannel.hide();

// shows a previously hidden channel
await nickChannel.show();

# hides the channel until a new message is added there
channel.hide(nick)

# shows a previously hidden channel
channel.show(nick)

# hides the channel until a new message is added there
channel.hide(nick)

# shows a previously hidden channel
channel.show(nick)

// hides the channel until a new message is added there
channel->hide($nick);

// shows a previously hidden channel
channel->show($nick);

// hides the channel until a new message is added there
channel.hide();

// shows a previously hidden channel
channel.show();

// Hide the channel.
channel.hide().subscribe().disposed(by: disposeBag)

// Show the channel.
channel.show().subscribe().disposed(by: disposeBag)

// hides the channel until a new message is added there
channel.hide()

// shows a previously hidden channel
channel.show()

There are 5 built-in channel types:

• livestream: Sensible defaults in case you want to build chat like YouTube or Twitch.
• messaging: Configured for apps such as Whatsapp or Messenger.
• gaming: Configured for in-game chat.
• commerce: Good defaults for building something like your own version of Intercom or Drift.
• team: If you want to build your own version of Slack or something similar start here.

As you can see in the examples below you can define your own Channel types and configure them to fit your needs. The Channel type allows you to configure these features:

• typing_events: Controls if typing indicators are shown. Enabled by default.
• read_events: Controls whether the chat shows how far you’ve read. Enabled by default.
• connect_events: Determines if events are fired for connecting and disconnecting to a chat. Enabled by default.
• search: Controls if messages should be searchable (this is a premium feature). Disabled by default.
• reactions: If users are allowed to add reactions to messages. Enabled by default.
• replies: Enables message threads and replies. Enabled by default.
• mutes: Determines if users are able to mute other users. Enabled by default.
• uploads: Allows image and file uploads within messages. Enabled by default.
• url_enrichment: When enabled messages containing URLs will be enriched automatically with image and text related to the message. Enabled by default.

It allows you to specify these settings:

Note: you need to use server side authentication to create, edit or delete a channel type.

Creating a Channel Type

• JS/Node
• Python
• Ruby
• PHP
• Java
• Go
• Swift
• C#

await client.createChannelType({
    name: 'public', 
    permissions:[
        new Permission(
            name: 'Allow reads for all',
            priority: 999,
            resources: ['ReadChannel', 'CreateMessage'],
            AnyRole,
        ),
        DenyAll
    ],
    mutes: false,
    reactions: false
});

client.create_channel_type({
    "name": "public",
    "permissions": [
        {
            "name": "Allow reads for all",
            "priority": 999,
            "resources": ["ReadChannel", "CreateMessage"],
            "action": "Allow",
        },
        {"name": "Deny all", "priority": 1, "resources": ["*"], "action": "Deny"},
    ],
    "mutes": False,
    "reactions": False,
})

client.create_channel_type({
    'name' => 'public',
    'permissions' => [
	{
	    'name' => 'Allow reads for all',
            'priority' => 999,
	    'resources' => ['ReadChannel', 'CreateMessage'],
	    'action' => 'Allow',
	},
	{'name' => 'Deny all', 'priority' => 1, 'resources' => ['*'], 'action' => 'Deny'}
    ],
    'mutes' => false,
    'reactions' => false
})

$channelConf = [
    'name' => 'public',
    'permissions' => [
	{
	    'name' => 'Allow reads for all',
            'priority' => 999,
	    'resources' => ['ReadChannel', 'CreateMessage'],
	    'action' => 'Allow',
	},
	{'name' => 'Deny all', 'priority' => 1, 'resources' => ['*'], 'action' => 'Deny'}
    ],
    'mutes' => false,
    'reactions' => false
];

$client->createChannelType($channelConf);

// at the moment we don't have a Java client for server side usage

// TODO

// at the moment we don't have a Swift client for server side usage

var c = new ChannelTypeInput()
{
    Name = "livechat",
    Automod = Autmod.Disabled,
    Commands = new List<string>() { Commands.Ban },
    Mutes = true
};

await client.CreateChannelType(c);

If not provided, the permission policies will default to the ones from the built-in team type.

List Channel Types

You can retrieve the list of all channel types defined for your application.

• JS/Node

await client.listChannelTypes();

Get a Channel Type

You can retrieve a channel type definition with this endpoint. Note: features and commands are also returned by other channel endpoints.

• JS/Node

client.getChannelType('public');

Edit a Channel Type

Channel type features, commands and permissions can be changed. Only the fields that must change need to be provided, fields that are not provided to this API will remain unchanged.

• JS/Node

client.updateChannelType('public', {
    permissions: [AllowAll, DenyAll],
    replies: false,
    commands: ["all"]
});

    
    curl -i -X PUT -d "{\"permissions\": [\"AllowAll\", \"DenyAll\"], \"replies\": false}"\
    -H "Content-Type: application/json" \
    -H "Stream-Auth-Type: jwt" \
    -H "Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzZXJ2ZXJzaWRlIjp0cnVlfQ.OYCKMIZtQ4xS9Ial_PfHcdmZgVoz0_UAjTryXpBEw44" \
    "https://chat-us-east-c1.stream-io-api.com/channeltypes/public?api_key=YOUR_API_KEY"
    
  

Features of a channel can be updated by passing the boolean flags:

• JS/Node

client.updateChannelType("public", {
  typing_events: false,
  read_events: true,
  connect_events: true,
  search: false,
  reactions: true,
  replies: false,
  mutes: true
});

Settings can also be updated by passing in the desired new values:

• JS/Node

client.updateChannelType("public", {
  automod: "disabled",
  message_retention: "7",
  max_message_length: 140,
  commands: ["imgur", "giphy", "ban"]
});

Permissions for a channel type can be updated either by using predefined values or creating new ones:

• JS/Node

client.updateChannelType("public", {
    permissions: [
        new Permission(
            name: 'Allow reads for all',
            priority: 999,
            resources: ['ReadChannel', 'CreateMessage'],
            AnyRole
        ),
        DenyAll
    ]
});

Remove a Channel Type

• JS/Node

client.deleteChannelType('public');

Note: you cannot delete a channel type if there are any active channels of that type.

The channel type also allows you to specify the permissions your chat can use. If not provided, the permissions will default to team’s channel type permissions.

The Channel object allows you to define a list of moderators and admins. The user object allows you to mark a user as a moderator or admin for your entire application.

Note that you can only modify these fields via the backend API:

• JS/Node
• Python

// editing a channel
const data = {
    image: image,
    created_by: elon,
    roles: { elon: 'admin', gwynne: 'moderator' },
};
const spacexChannel = serverClient.channel('organization', 'spacex').update(data);

data = {
    "image": "https://path/to/image",
    "created_by": "elon",
    "roles": {"elon": "admin", "gwynne": "moderator"},
}

spacex_channel = client.channel("team", "spacex")
spacex_channel.update(data)

You can edit a user like this:

• JS/Node
• Python

await serverClient.updateUser({
    id: 'tommaso',
    name: 'Tommaso Barbugli',
    role: 'admin',
});

client.update_user({"id": "tommaso", "name": "Tommaso", "role": "admin"})

Server-side, you’re allowed to do everything. For client-side integrations, the permission system kicks in. This system basically specifies a list of permissions the given user is allowed to do.

Note: changing user roles is only allowed server-side.

Permission checking is performed taking into account parameters:

• API Request: the action the user is performing (e.g. send a message, edit a message)
• User role
• Channel type
• Resource: the resource involved in the API call (e.g. a channel, a message, a user, ...)
• Ownership: whether or not the resource is owned by the user (when applicable)

Most API requests are specific to a channel (eg. add a message to channel “livestream:rockets”). Channel types have different permissions and can be configured via APIs. The 5 default channel types come with good default permission policies. You can find more information on how to manage permissions in the Channel Types section.

1. admin: This role allows users to perform more advanced actions. This role should be granted only to staff users.
2. moderator: Allows users to perform moderation (e.g. ban users, add/remove users, …).
3. user: This is the default role assigned to any user.
4. channel member: A user that is also listed as member on a channel.
5. guest: Users added using setGuestUser get this role automatically.
6. anonymous: Users added using setAnonymousUser get this role automatically.

Note: a user can have the moderator role for some specific channels and the user role for all other channels.

If applicable, ownership of the entity is taken into account. This parameter allows you to grant users the ability to edit their own message while denying editing others’ messages. Permission policies are organized as list ordered by priority. A permission policy has the following fields:

Channel Type

The channel the policy applies to.

Name

The unique name for the policy (eg. "Channel member permissions").

Resources

The list of API resources the policy applies to. Policies can match one more resources by their name (see full list below) or any resource by using the wildcard resource value “*”.

Roles

The list of roles the policy applies to. This value can be empty in that case the user role is not going to be taken into account.

Owner

Whether the policy should be applied to requested that alter an object owned by the requesting user. This field is either true or false.

Action

The action to apply to the API request once resources, roles and action fields are matching. The two allowed values are: Allow and Deny.

Priority

The priority of the policy. Policies are evaluated ordered by their priority, this field allows you to create a stable order.

The five built-in channel types ship with default permission setting.

Messaging

Livestream

Gaming

Commerce

Team

By default the following commands are supported:

• /giphy query
• /imgur query
• /ban @userid reason
• /unban @userid
• /mute @userid
• /unmute @userid
• /flag @userid

Additionally, it’s possible to add your own commands. Commands are implemented using actions and attachments. Let’s have a look what data is returned when you run /giphy rock

{
    "args": "rock",
    "attachments": [
        {
            "type": "image",
            "thumb_url": "https://media0.giphy.com/media/3o85xx69HG11jP4QI/giphy.gif",
        }
        "actions": [
            {
                "name": "image_action",
                "text": "Send",
                "style": "primary",
                "type": "button",
                "value": "send"
            },
            {
                "name": "image_action",
                "text": "Shuffle",
                "style": "default",
                "type": "button",
                "value": "shuffle"
            },
            {
                "name": "image_action",
                "text": "Cancel",
                "style": "default",
                "type": "button",
                "value": "cancel"
            }
        ]
    ],
    "command": "giphy",
    "created_at": "2018-11-30T21:25:04.147725Z",
    "html": "<p>/gihpy rock</p>\n",
    "id": "33",
    "reactions": [],
    "reply_count": 0,
    "status": "received",
    "text": "/giphy rock",
    "type": "ephemeral",
    "updated_at": "2018-11-30T21:25:04.147725Z",
    "user": {
        "id": "thierry",
        "image": "myimageurl",
        "name": "Thierry",
        "role": "admin",
        "status": "busy"
    }
}

Actions

Actions have a name, text, style, type and value attributes. These simple fields allow you to build complex interactions with your bots & slash commands. All of the available Stream UI Components know how to render these actions. So for /giphy ocean, the result will be this:

The most common use case for client level events are unread counts. Here's an example of a complete unread count integration for your chat app. As a first step we get the unread count when the user connects:

const response = await client.setUser(
     { id: 'myid' },
     token,
   );

// response.me.total_unread_count returns the unread count
// response.me.unread_channels returns the count of channels with unread messages

// when you call setUser the unread counts are initialized
client.setUser(user, USER_TOKEN, new ClientConnectionCallback() {
    @Override
    public void onSuccess(User user) {
    }

    @Override
    public void onError(String errMsg, int errCode) {
    }
});
// livedata is available on StreamChat
StreamChat.getTotalUnreadMessages().observe(this, (Number count) -> {
    Log.i(TAG, String.format("Total unread message count is now %d", count));
});
StreamChat.getUnreadChannels().observe(this, (Number count) -> {
    Log.i(TAG, String.format("There are %d channels with unread messages", count));
});

// unread counts are also available on the ClientState
client.getState().getUnreadChannels();
client.getState().getTotalUnreadCount();
// they are automatically updated when new events are received.

// Subscribe for a total unread count channels and messages.
Client.shared.unreadCount
    .drive(onNext: { unreadCount in
        print("Unread channels: \(unreadCount.channels)")
        print("Total unread messages: \(unreadCount.messages)")
    })
    .disposed(by: disposeBag)

// Subscribe for a channel unread count.
channel.unreadCount
    .drive(onNext: { unreadCount in
        print("Unread messages: \(unreadCount)")
    })
    .disposed(by: disposeBag)

// Subscribe for a channel user mentioned unread count.
channel.mentionedUnreadCount
    .drive(onNext: { unreadCount in
        print("Unread messages: \(unreadCount)")
    })
    .disposed(by: disposeBag)

// when you call setUser the unread counts are initialized
client.setUser(user, "USER_TOKEN", object : ClientConnectionCallback {
    override fun onSuccess(user: User) {}

    override fun onError(errMsg: String, errCode: Int) {}
})

StreamChat.getTotalUnreadMessages().observe(
    this, Observer<Number>{ count: Number ->
        Log.i(TAG, String.format("Total unread message count is now %d", count))
    })

StreamChat.getUnreadChannels().observe(
    this, Observer<Number>{ count: Number ->
        Log.i(TAG, String.format("There are %d channels with unread messages", count))
    })

// unread counts are also available on the ClientState
client.state.unreadChannels
client.state.totalUnreadCount
// they are automatically updated when new events are received.

By default the React components will mark the messages as read automatically. You can also make the API call manually like this:

// mark all messages on a channel as read
await channel.markRead()

channel.markRead(new EventCallback() {
    @Override
    public void onSuccess(EventResponse response) {
        Log.d(TAG, "Marked read message");
    }

    @Override
    public void onError(String errMsg, int errCode) {
        Log.e(TAG, errMsg);
    }
});

// Mark all messages as readed.
Client.shared.markAllRead().subscribe().disposed(by: disposeBag)

// Mark channel messages as readed.
channel.markRead()
    .subscribe(onNext: { event in
        print(event)
    })
    .disposed(by: disposeBag)

channel.markRead(object: EventCallback {

    override fun onSuccess(response: EventResponse) {
        Log.d(TAG, "Marked read message");
    }

    override fun onError(errMsg: String, errCode: int) {
        Log.e(TAG, errMsg);
    }
});

While you're using the app the unread count can change. A user can be added to a channel, a new message can be created or the user can mark the messages as seen on another tab/device. To support updating the unread count in realtime you can listen to these events.

1. notification.added_to_channel
2. notification.removed_from_channel
3. notification.message_new
4. notification.mark_read

All 4 of these events include the fields: total_unread_count and unread_channels. You can listen to them all at once like this:

client.on((event) => {

     if (event.total_unread_count !== undefined) {
         console.log(event.total_unread_count);
     }

     if (event.unread_channels !== undefined) {
         console.log(event.unread_channels);
     }

});

// receive an event whenever any of the channels that you are watching changes
Integer subscriptionId = client.addEventHandler(new ChatEventHandler() {
  @Override
  public void onAnyEvent(Event event) {
    if (event.getTotalUnreadCount() != null) {
        // event.getTotalUnreadCount().intValue();
    }
    if (event.getUnreadChannels() != null) {
        // event.getUnreadChannels().intValue();
    }
  }
});

Client.shared.onEvent([.notificationAddedToChannel,
                       .notificationRemovedFromChannel,
                       .notificationMessageNew,
                       .notificationMarkRead])
    .subscribe(onNext: { event in
        print(event)
    })
    .disposed(by: disposeBag)

// receive an event whenever any of the channels that you are watching changes
val subscriptionId = client().addEventHandler(object: ChatEventHandler {

  override fun onAnyEvent(event: Event) {
    if (event.getTotalUnreadCount() != null) {

    }
    if (event.getUnreadChannels() != null) {

    }
  }
});

When you retrieve a channel from the API (eg. using Query Channels), the read state for all members is included in the response. This allows you to display which messages are read by each user. For each member we include the last time he or she marked the channel as read.

const channel = client.channel('messaging', 'test');
await chan.watch();

console.log(chan.state.read);

//{ '2fe6019c-872f-482a-989e-ecf4f786501b':
//  { user: 
//    { 
//      id: '2fe6019c-872f-482a-989e-ecf4f786501b',
//      role: 'user',
//      created_at: '2019-04-24T13:09:19.664378Z',
//      updated_at: '2019-04-24T13:09:23.784642Z',
//      last_active: '2019-04-24T13:09:23.781641Z',
//      online: true
//    },
//    last_read: 2019-04-24T13:09:21.623Z
//  }
//}

// You can see the user read states like this
List<ChannelUserRead> reads = channel.getChannelState().getReads();

// Get message read states for the channel.
channel.query()
    .subscribe(onNext: { channelResponse in
        print(channelResponse.messageReads)
    })
    .disposed(by: disposeBag)

// Get the current user message read state for the channel.
channelPresenter.messageRead

// You can see the user read states like this
val reads = channel.getChannelState().getReads();

Unread messages per channel

You can retrieve the count of unread messages for the current user on a channel like this:

channel.countUnread();

// to compute the unread count for a channel (comparing message creation date to read state)
Integer count = channel.getChannelState().getCurrentUserUnreadMessageCount();

channel.currentUnreadCount

// to compute the unread count for a channel (comparing message creation date to read state)
val count = channel.getChannelState().getCurrentUserUnreadMessageCount()

Unread mentions per channel

You can retrieve the count of unread messages mentioning the current user on a channel like this:

channel.countUnreadMentions();

channel.currentMentionedUnreadCount

Mark all as read

You can mark all channels as read for a user like this:

// client-side
await client.markAllRead();

// mark all as read for one user server-side 
await serverSideClient.markAllRead({ user:  { id: 'myid' } });

client.markAllRead(new EventCallback() {
    @Override
    public void onSuccess(EventResponse response) {
        
    }

    @Override
    public void onError(String errMsg, int errCode) {

    }
});

Client.shared.markAllRead().subscribe().disposed(by: disposeBag)

client.markAllRead(object: EventCallback {
    override fun onSuccess(response: EventResponse) {
        
    }

    override fun onError(errMsg: String, errCode: int) {

    }
});

User presence allows you to show when a user was last active and if they are online right now. Whenever you read a user the data will look like this:

Data Format

{
    id: 'myuserid',
    online: true,
    status: 'eating a burger',
    last_active: '2019-01-07T13:17:42.375Z'
}

The online field indicates if the user is online. The status field just stores a text indicating the current user status.

To mark a user invisible simply set the invisible property to true. You can also set a custom status message at the same time:

// mark a user as invisible
authClient.setUser({
    id: 'myuserid',
    invisible: true
});

// set the current user to invisible, they will show as offline to other users
HashMap<String, Object> extraData = new HashMap<>();
extraData.put("invisible", true);
User user = new User(USER_ID, extraData);
client.setUser(user, USER_TOKEN, new ClientConnectionCallback() {
    @Override
    public void onSuccess(User user) {
        Log.i(TAG, String.format("Connection established for user %s", user.getName()));
    }

    @Override
    public void onError(String errMsg, int errCode) {
        Log.e(TAG, String.format("Failed to establish websocket connection. Code %d message %s", errCode, errMsg));
    }
});

let user = User(id: "john", name: "John", isInvisible: true)
Client.shared.set(user: user, token: "<#USER_TOKEN#>")

// set the current user to invisible, they will show as offline to other users
val extraData = HashMap()
extraData.put("invisible", true)
val user = User(USER_ID, extraData)
client.setUser(user, USER_TOKEN, object : ClientConnectionCallback {
    override fun onSuccess(user: User) {
        Log.i(TAG, String.format("Connection established for user %s", user.name))
    }

    override fun onError(errMsg: String, errCode: Int) {
        Log.e(TAG, String.format("Failed to establish websocket connection. Code %d message %s", errCode, errMsg))
    }
})

When invisible is set to true the current user will appear as offline to other users.

Of course, you want to listen to the user presence changes. This allows you to show a user as offline when they leave and update their status in real time. These 3 endpoints allow you to watch user presence:

// 3 ways of watching user presence

// If you pass presence: true to channel.watch it will watch the list of user presence changes.
// Note that you can listen to at most 10 users using this API call
const channel = authClient.channel('messaging', 'my-conversation-123', {
    members: ['john', 'jack'],
    color: 'green'
})
const state = await channel.watch({presence: true})

// queryChannels allows you to listen to the members of the channels that are returned
// so this does the same thing as above and listens to online status changes for john and jack
const channels = await authClient.queryChannels(
    {color: 'green'},
    {last_message_at: -1},
    {presence: true},
)

// queryUsers allows you to listen to user presence changes for john and jack
const users = await authClient.queryUsers({id: {$in: ['john', 'jack']}}, {id: -1}, {presence: true})

// 3 ways of watching user presence

// If you pass presence: true to channel.watch it will watch the list of user presence changes.
// Note that you can listen to at most 10 users using this API call
// watching a channel's state
ChannelWatchRequest request = new ChannelWatchRequest()
    .withPresence()
    .withMessages(Constant.DEFAULT_LIMIT);

channel.watch(
    request,
    new QueryWatchCallback() {
        @Override
        public void onSuccess(ChannelState response) {

        }

        @Override
        public void onError(String errMsg, int errCode) {

        }
    }
);
// queryChannels allows you to listen to the members of the channels that are returned
// so this does the same thing as above and listens to online status changes for john and jack
QueryChannelsRequest request = new QueryChannelsRequest(filter, sort)
        .withLimit(10)
        .withWatch()
        .withPresence()
        .withMessageLimit(20);

client.queryChannels(request, new QueryChannelListCallback(){
    @Override
    public void onSuccess(QueryChannelsResponse response) {
        
    }

    @Override
    public void onError(String errMsg, int errCode) {

    }
});
// queryUsers allows you to listen to user presence changes for john and jack
ArrayList<String> searchUsersList = new ArrayList<>();
searchUsersList.add("john");
searchUsersList.add("jack");

FilterObject filter = Filters.in("id", searchUsersList);
QuerySort sort = new QuerySort().desc("id");

client.queryUsers(new QueryUserRequest(filter, sort).withPresence(), new QueryUserListCallback() {
    @Override
    public void onSuccess(QueryUserListResponse response) {

    }

    @Override
    public void onError(String errMsg, int errCode) {

    }
});

// First of all subscribe for events.
channel.onEvent(.userPresenceChanged)
    .subscribe(onNext: { event in
        print(event)
    })
    .disposed(by: disposeBag)

// 1. Start watching a channel with the presence option.
channel.watch(options: .presence).subscribe().disposed(by: disposeBag)

// 2. Make a query for the channel with the presence option.
channel.query(pagination: .limit(30), options: [.watch, .presence])
    .subscribe(onNext: { channelResponses in
        print(channelResponses)
    })
    .disposed(by: disposeBag)

// 3 ways of watching user presence
// If you pass presence: true to channel.watch it will watch the list of user presence changes.
// Note that you can listen to at most 10 users using this API call
// watching a channel's state
val request = ChannelWatchRequest()
    .withPresence()
    .withMessages(Constant.DEFAULT_LIMIT)

channel.watch(
    request,
    object: QueryWatchCallback {
        override fun onSuccess(response: ChannelState?) {

        }

        override fun onError(errMsg: String?, errCode: Int) {

        }
    }
)

// queryChannels allows you to listen to the members of the channels that are returned
// so this does the same thing as above and listens to online status changes for john and jack
val request = QueryChannelsRequest(filter, sort)
            .withLimit(10)
            .withWatch()
            .withPresence()
      .withMessageLimit(20)

client.queryChannels(request, object : QueryChannelListCallback{
    override fun onSuccess(response: QueryChannelsResponse?) {
        
    }

    override fun onError(errMsg: String?, errCode: Int) {
        
    }
})

// queryUsers allows you to listen to user presence changes for john and jack
val request = QueryUserRequest(
	Filters.`in`("id", listOf("jessica")), 
	QuerySort().desc("last_active")
).withPresence()

client.queryUsers(request, 
  object : QueryUserListCallback {
    override fun onSuccess(response: QueryUserListResponse?) {
    }

    override fun onError(errMsg: String?, errCode: Int) {
    }
})

Users' online status changes can be handled via event delegation; just subscribe for the "user.presence.changed" event the same you do for any other event.

Flag

Any user is allowed to flag a message or a user.

const data = await authClient.flagMessage(messageResponse.message.id);

client.flag_message(message_id)

// Flag User
client.flagUser(userId, new FlagCallback() {
    @Override
    public void onSuccess(FlagResponse response) {
       
    }

    @Override
    public void onError(String errMsg, int errCode) {
       
    }
});

// Flag a message.
channel.flag(message: message)
    .subscribe(onNext: { flagMessageResponse in
        print(flagMessageResponse)
    })
    .disposed(by: disposeBag)

// or
message.flag()
    .subscribe(onNext: { flagMessageResponse in
        print(flagMessageResponse)
    })
    .disposed(by: disposeBag)

client.flagUser("userId", object : FlagCallback {
    override fun onSuccess(response: FlagResponse) {

    }

    override fun onError(errMsg: String, errCode: Int) {

    }
})

Mute

Any user is allowed to mute another user.

// client-side mute
const data = await authClient.muteUser('eviluser');

// server-side mute requires the id of the user creating the mute as well
const data = await authClient.muteUser('eviluser', 'user_id');

client.mute_user(muted_user_id, user_id)

// Mute User
client.muteUser(userId, new MuteUserCallback() {
  @Override
  public void onSuccess(MuteUserResponse response) {
      
  }

  @Override
  public void onError(String errMsg, int errCode) {

  }
});

// Mute a user.
Client.shared.mute(user: user)
    .subscribe(onNext: { mutedUsersResponse in
        print(mutedUsersResponse)
    })
    .disposed(by: disposeBag)

client.muteUser("userId", object : MuteUserCallback{
    override fun onSuccess(response: MuteUserResponse ) {

    }

    override fun onError(errMsg: String, errCode: Int) {

    }
})

Ban

Users can be banned from an app entirely or from a channel. When a user is banned, it will be not allowed to post messages until the ban is removed or expired. In most cases only admins or moderators are allowed to ban other users from a channel.

Note: Banning a user from all channels can only be done using server-side auth.

• JS/Node
• Python
• Java
• Swift
• Kotlin

// ban a user for 60 minutes from all channel
let data = await authClient.banUser('eviluser', {
    timeout: 60,
    reason: 'Banned for one hour',
});

// ban a user from the livestream:fortnite channel
data = await channel.banUser('eviluser', {
    reason: 'Profanity is not allowed here',
});

// remove ban from channel
data = await channel.unbanUser('eviluser');

// remove global ban
data = await authClient.unbanUser('eviluser');

# ban a user for 60 minutes from all channel
client.ban_user("eviluser", timeout=60, reason="Banned for one hour")

# ban a user from the livestream:fortnite channel
channel.ban_user("eviluser", reason="Profanity is not allowed here")

# remove ban from channel
channel.unban_user("eviluser")

# remove global ban
client.unban_user("eviluser")

client.banUser(userId, channel, reason, timeout, new CompletableCallback() {
    @Override
    public void onSuccess(CompletableResponse response) {
        
    }

    @Override
    public void onError(String errMsg, int errCode) {

    }
});

channel.ban(user: user, timeoutInMinutes: timeout, reason: reason)
    .subscribe()
    .disposed(by: disposeBag)

client.banUser(userId, channel, reason, timeout, object : CompletableCallback {
    override fun onSuccess(response: CompletableResponse) {

    }

    override fun onError(errMsg: String, errCode: Int) {

    }
})

Automod

For livestream and gaming channel types Automod is enabled by default. There are three options for moderation:

• disabled
• simple (blocks messages that contain a list of profane words)
• ai (uses an AI-based classification system to detect various types of bad content)

You can configure the thresholds for the AI-based system by specifying a value between 0 and 1 for the following types of bad content. As an example, if you set the value for Spam to 0.7 it will block any message that seems very likely to be spam. On the other hand, if you set a value of 0.3 it will be very sensitive and block anything that remotely looks like spam.

• Spam:
  • Unsolicited messages: typically used as clickbait for financial gain from bot messages.
• Toxic:
  • Not a constructive comment, or in general not nice.
  • Ex: "This is dumb" would be classified highly as toxic and only slightly obscene.
• SevereToxic:
  • Worst of the worst. Typically insulting, obscene and degrading.
  • Ex: "What a motherfucking piece of crap those fuckheads for blocking us!"
• Obscene:
  • Generally reserved for inappropriate words. Typically offensive to accepted standards of morality.
• Threat:
  • A direct threat to another user.
  • Ex: "I will spit on you" would classified highly as toxic and a threat but only slightly obscene.
• Insult:
  • Insulting another user.
  • Ex: "You are dumb" would be classified as toxic and insulting, yet only moderately obscene.
• IdentityHate:
  • Degradation of a protected class.

AI-based moderation is a premium feature. Please contact sales to discuss your options.

Official Clients

Official clients are currently available for a number of languages:

• 

  Ruby

• 

  JS

• 

  Python

• 

  .Net

• 

  PHP

• 

  Go

Here’s an example of sending a chat message from a server-side integration:

• JS/Node
• Python
• Ruby
• PHP
• Java
• Go
• Swift
• C#

const options = {};
const serverClient = new StreamChat('STREAM_KEY', 'STREAM_API_SECRET', options);
const spacexChannel = serverClient.channel('team', 'spacex', {
    image: image,
    created_by: elon,
});
const createResponse = await spacexChannel.create();
const text = 'I was gonna get to mars but then I got high';
const message = {
    text,
    user: elon,
}
const response = await spacexChannel.sendMessage(message);

# pip install stream-chat

from stream_chat import StreamChat

client = StreamChat(api_key="STREAM_KEY", api_secret="STREAM_API_SECRET")
spacex_channel = client.channel('team', 'spacex', {
    "image": image,
});
spacex_channel.create("elon")

spacex_channel.send_message(
    {"text": "I was gonna get to mars but then I got high"},
    user_id="elon"
)

# gem install stream-chat-ruby

require 'stream-chat'

client = StreamChat::Client.new(api_key='STREAM_KEY', api_secret='STREAM_API_SECRET')
spacex_channel = client.channel("team", channel_id: "spacex", data: {'image'=> image})
spacex_channel.create('elon')


spacex_channel.send_message({'text' => 'I was gonna get to mars but then I got high'}, 'elon')

//composer require get-stream/stream-chat

$client = new GetStream\StreamChat\Client("STREAM_KEY", "STREAM_API_SECRET");
$spacexChannel = $client->Channel("team", "spacex", ['image' => image]);
$spacexChannel->create('elon');

$spacexChannel->sendMessage(["text" => "I was gonna get to mars but then I got high"], 'elon');

// at the moment we don't have a Java client for server side usage

// go get github.com/GetStream/stream-chat-go

import stream "github.com/GetStream/stream-chat-go"

client, _ := stream.NewClient("STREAM_KEY", []byte("STREAM_API_SECRET"))

spacexChannel, _ := client.CreateChannel("team", "spacex","elon", map[string]interface{}{
    "image": image,
})

message := stream.Message{
    Text: "I was gonna get to mars but then I got high",
}

channel.SendMessage(&message, "elon")

// at the moment we don't have a Swift client for server side usage

// nuget install stream-chat-net

using StreamChat;

var client = new Client("STREAM_KEY", "STREAM_API_SECRET");
var spacexChannel = client.Channel("team", "spacex");
spacexChannel.Create('elon');

var message = new MessageInput()
{
    Text = "I was gonna get to mars but then I got high",
};
spacexChannel. SendMessage(message, 'elon');

Note the 3 differences compared to the client side integration:

1. Initialize the client with the server side secret.
2. Create the Channel instead of initializing it (we don't want to retrieve the state or subscribe to changes in this case).
3. Pass the user parameter if the endpoint requires it (eg. creating a channel or a message)

• JS/Node
• Python

const tommaso = { id: "tommaso" };

// create a channel and assign user Tommaso as owner
const channel = serverClient.channel("team", "stream", { created_by: tommaso })
await channel.create();

// send a message for tommaso
const message = {
   text: "hi there!",
   user: tommaso,
};
await channel.sendMessage(message);

# create a channel and assign user Tommaso as owner
channel = client.channel("team", "stream")
channel.create("tommaso")

# send a message for tommaso
message = {
    "text": "hi there!",
    "user": "tommaso"
}
channel.send_message(message, "tommaso")

tream's Command Line Interface (CLI) makes it easy to create and manage your Stream apps directly from the terminal. Currently, only Chat is supported. You can find the source code on GitHub

Installation

yarn global add getstream-cli

# OR

npm install -g getstream-cli

First time setup

In order to initialize the CLI, you need to configure it with your Stream credentials, such as your API Key and Secret. These can be found on the Dashboard

$ stream config:set
✔ What is your full name? · Bobby Tables
✔ What is your email address associated with Stream? · bob@tables.com
✔ What is your Stream API key? · foo
✔ What is your Stream API secret? · ***

Documentation

Later in this docs we will also refer to how you can use the CLI tool to make changes to your chat application.
You can find the complete documentation for Stream CLI here.

Change a user role

• JS/Node
• Python
• Ruby
• PHP
• Java
• Go
• Swift
• C#

await serverClient.updateUser({
    id: 'tommaso',
    name: 'Tommy Doe',
    role: 'admin',
});

client.update_user({
    "id": "tommaso",
    "name": "Tommy Doe",
    "role": "admin",
})

client.update_user({
    "id" => "tommaso",
    "name" => "Tommy Doe",
    "role" => "admin",
})

client->updateUser([
    "id" => "tommaso",
    "name" => "Tommy Doe",
    "role" => "admin"
])

// at the moment we don't have a Java client for server side usage

user := User{
    ID: "tommaso",
    Role: "admin",
    ExtraData: map[string]interface{}{
        "name": "Tommy Doe",
    }
}

client.UpdateUser(&user)

// at the moment we don't have a Swift client for server side usage

var user = new User()
{
    ID = "tommaso",
    Role = Role.Admin,
};
bob.SetData("name", "Tommy Doe");

await client.Users.Update(user);

Add moderators to a channel

• JS/Node
• Python
• Ruby
• PHP
• Java
• Go
• Swift
• C#

let channel = serverClient.channel("livestream", "fortnite");
await channel.addModerators(["thierry", "tommaso"]));

channel = client.channel("livestream", "fortnite")
channel.add_moderators(["thierry", "tommaso"])

channel = client.channel("livestream", "fortnite")
channel.add_moderators(["thierry", "tommaso"])

channel = client->Channel("livestream", "fortnite");
channel->addModerators(["thierry", "tommaso"]);

// at the moment we don't have a Java client for server side usage

channel = client.Channel("livestream", "fortnite")
channel.AddModerators("thierry", "tommaso")

// at the moment we don't have a Swift client for server side usage

var chan = client.Channel("livestream", "fortnite");
await chan.AddModerators(new string[] { "thierry", "tommaso" });

Remove moderators from a channel

• JS/Node
• Python
• Ruby
• PHP
• Java
• Go
• Swift
• C#

await channel.demoteModerators(["thierry"]));

channel.demote_moderators(["thierry"])

channel.demote_moderators(["thierry"])

channel->demoteModerators(["thierry"]);

// at the moment we don't have a Java client for server side usage

channel.DemoteModerators("thierry")

// at the moment we don't have a Swift client for server side usage

await chan.DemoteModerators(new string[] { "thierry", "tommaso" });

Enabling development tokens

Token validation can be disabled for development apps. This allows you to use development tokens and work on user token provisioning later on.

• JS/Node
• Python
• Swift

// disable auth checks, allows dev token usage
await client.updateAppSettings({
    disable_auth_checks: true,
});

// re-enable auth checks
await client.updateAppSettings({
    disable_auth_checks: false,
});

# disable auth checks, allows dev token usage
client.update_app_settings(disable_auth_checks=True)

# re-enable auth checks
client.update_app_settings(disable_auth_checks=False)

Client.shared.set(user: user, token: .development)

Disable permission checking

By default all apps ship with role based permission checks. During development you can decide to turn off permission checks, this way all users will act as admin users.

• JS/Node
• Python

// disable permission checks
await client.updateAppSettings({
	disable_permissions_checks: true,
});

// re-enable permission checks
await client.updateAppSettings({
	disable_permissions_checks: false,
});

# disable permission checks
client.update_app_settings(disable_permissions_checks=True)

# re-enable permission checks
client.update_app_settings(disable_permissions_checks=False)

By using webhooks, you can receive all events within your application. When configured, every event happening on Stream Chat will propagate to your webhook endpoint via a HTTP POST request.

Webhook can help you migrating from a different chat provider to Stream without disruption or to support complex notification mechanisms (eg. send an SMS to an offline user when a direct message is sent).

Webhook requirements

In order to use webhooks, the endpoint responding to the URL must:

• Be reachable from public internet, tunneling services like ngrok are supported
• Respond with a 200 HTTP code in less than 3 seconds
• Handle HTTP requests with POST body
• Able to parse JSON payloads
• Support HTTP/1.1

While not required, we recommend to follow these best-practices for production environments:

• Use SSL over HTTP using a certificate from a trusted authority (eg. Letsencrypt)
• Verify the x-signature header
• Support Keep-Alive
• Be highly available
• Offload the processing of the message (read, store and forget)

Configuration

• CLI

// see https://getstream.io/chat/docs/js/#cli_introduction for CLI introduction

stream chat:push:webhook \
    --url 'https://acme.com/my/awesome/webhook/handler/'

Verify events via X-Signature

All HTTP requests can be verified as coming from Stream (and not tampered by a 3rd party) by analyzing the signature attached to the request. Every request includes an HTTP header called "x-signature" containing a cryptographic signature of the message. Your webhook endpoint can validate that payload and signature match.

• JS/Node
• Python
• Ruby
• PHP
• Java
• Go
• Swift
• C#

// first argument is the request body as a string, second the signature header
const isValid = client.verifyWebhook(req.rawBody, req.headers['x-signature']);

import stream_chat

client = stream_chat.connect('API_KEY', 'API_SECRET')

# Django request
valid = client.verify_webhook(request.body, request.META['HTTP_X_SIGNATURE'])

# Flask request
valid = client.verify_webhook(request.data, request.headers['X-SIGNATURE'])

require 'stream-chat'

client = StreamChat::Client.new(api_key='STREAM_KEY', api_secret='STREAM_SECRET')

// signature comes from the HTTP header x-signature
valid = client.verify_webhook(request_body, signature)

$client = new GetStream\StreamChat\Client("STREAM_API_KEY", "STREAM_API_SECRET");

// signature comes from the HTTP header x-signature
$valid = $client->verifyWebhook($requestBody, $signature);

// at the moment we don't have a Java client for server side usage

client, _ := stream.NewClient(APIKey, []byte(APISecret))

// signature comes from the HTTP header x-signature
isValid := client.VerifyWebhook(body, signature)

// at the moment we don't have a Swift client for server side usage

using StreamChat;

var client = new Client("API KEY", "API SECRET");

// signature comes from the HTTP header x-signature 
client.VerifyWebhook(requestBody, signature);

Below you can find the complete list of events that are sent via web-hooks together with the description of the data payload.

For message and channel events the webhook request body will also include the list of channel members and attach additional information about their read status. For performance reasons, such list is only included for channels with up to 50 members.

When applicable, the following attributes are included to the event user and to the event members:

Webhook event types

message.new

{
  "cid": "messaging:fun",
  "type": "message.new",
  "message": {
    "id": "fff0d7c0-60bd-4835-833b-3843007817bf",
    "text": "8b780762-4830-4e2a-aa43-18aabaf1732d",
    "html": "<p>8b780762-4830-4e2a-aa43-18aabaf1732d</p>\n",
    "type": "regular",
    "user": {
      "id": "97b49906-0b98-463b-aa47-0aa945677eb2",
      "role": "user",
      "created_at": "2019-04-24T08:48:38.440123Z",
      "updated_at": "2019-04-24T08:48:38.440708Z",
      "online": false
    },
    "attachments": [],
    "latest_reactions": [],
    "own_reactions": [],
    "reaction_counts": null,
    "reply_count": 0,
    "created_at": "2019-04-24T08:48:39.918761Z",
    "updated_at": "2019-04-24T08:48:39.918761Z",
    "mentioned_users": []
  },
  "user": {
    "id": "97b49906-0b98-463b-aa47-0aa945677eb2",
    "role": "user",
    "created_at": "2019-04-24T08:48:38.440123Z",
    "updated_at": "2019-04-24T08:48:38.440708Z",
    "online": false,
    "channel_unread_count": 1,
    "channel_last_read_at": "2019-04-24T08:48:39.900585Z",
    "total_unread_count": 1,
    "unread_channels": 1,
    "unread_count": 1
  },
  "created_at": "2019-04-24T08:48:38.949986Z",
  "members": [
    {
      "user_id": "97b49906-0b98-463b-aa47-0aa945677eb2",
      "user": {
        "id": "97b49906-0b98-463b-aa47-0aa945677eb2",
        "role": "user",
        "created_at": "2019-04-24T08:48:38.440123Z",
        "updated_at": "2019-04-24T08:48:38.440708Z",
        "online": false,
        "channel_unread_count": 1,
        "channel_last_read_at": "2019-04-24T08:48:39.900585Z",
        "total_unread_count": 1,
        "unread_channels": 1,
        "unread_count": 1
      },
      "created_at": "2019-04-24T08:48:39.652296Z",
      "updated_at": "2019-04-24T08:48:39.652296Z"
    }
  ]
}

message.read

{
  "cid": "messaging:fun",
  "type": "message.read",
  "user": {
    "id": "a6e21b36-798b-408a-9cd1-0cf6c372fc7f",
    "role": "user",
    "created_at": "2019-04-24T08:49:58.170034Z",
    "updated_at": "2019-04-24T08:49:59.345304Z",
    "last_active": "2019-04-24T08:49:59.344201Z",
    "online": true,
    "total_unread_count": 0,
    "unread_channels": 0,
    "unread_count": 0,
    "channel_unread_count": 0,
    "channel_last_read_at": "2019-04-24T08:49:59.365498Z"
  },
  "created_at": "2019-04-24T08:49:59.365489Z"
}

message.updated

{
  "cid": "messaging:fun",
  "type": "message.updated",
  "message": {
    "id": "93163f53-4174-4be8-90cd-e59bef78da00",
    "text": "new stuff",
    "html": "<p>new stuff</p>\n",
    "type": "regular",
    "user": {
      "id": "75af03a7-fe83-4a2a-a447-9ed4fac2ea36",
      "role": "user",
      "created_at": "2019-04-24T08:51:26.846395Z",
      "updated_at": "2019-04-24T08:51:27.973941Z",
      "last_active": "2019-04-24T08:51:27.972713Z",
      "online": false
    },
    "attachments": [],
    "latest_reactions": [],
    "own_reactions": [],
    "reaction_counts": null,
    "reply_count": 0,
    "created_at": "2019-04-24T08:51:28.005691Z",
    "updated_at": "2019-04-24T08:51:28.138422Z",
    "mentioned_users": []
  },
  "user": {
    "id": "75af03a7-fe83-4a2a-a447-9ed4fac2ea36",
    "role": "user",
    "created_at": "2019-04-24T08:51:26.846395Z",
    "updated_at": "2019-04-24T08:51:27.973941Z",
    "last_active": "2019-04-24T08:51:27.972713Z",
    "online": true,
    "channel_unread_count": 1,
    "channel_last_read_at": "2019-04-24T08:51:27.994245Z",
    "total_unread_count": 2,
    "unread_channels": 2,
    "unread_count": 2
  },
  "created_at": "2019-04-24T10:51:28.142291+02:00"
}

message.deleted

{
  "cid": "messaging:fun",
  "type": "message.deleted",
  "message": {
    "id": "268d121f-82e0-4de1-8c8b-ef1201efd7a3",
    "text": "new stuff",
    "html": "<p>new stuff</p>\n",
    "type": "regular",
    "user": {
      "id": "76cd8430-2f91-4059-90e5-02dffb910297",
      "role": "user",
      "created_at": "2019-04-24T09:44:21.390868Z",
      "updated_at": "2019-04-24T09:44:22.537305Z",
      "last_active": "2019-04-24T09:44:22.535872Z",
      "online": false
    },
    "attachments": [],
    "latest_reactions": [],
    "own_reactions": [],
    "reaction_counts": {},
    "reply_count": 0,
    "created_at": "2019-04-24T09:44:22.57073Z",
    "updated_at": "2019-04-24T09:44:22.717078Z",
    "deleted_at": "2019-04-24T09:44:22.730524Z",
    "mentioned_users": []
  },
  "created_at": "2019-04-24T09:44:22.733305Z"
}

reaction.new

{
  "cid": "messaging:fun",
  "type": "reaction.new",
  "message": {
    "id": "4b3c7b6c-a39d-4069-9450-2a3716cf4ca6",
    "text": "new stuff",
    "html": "<p>new stuff</p>\n",
    "type": "regular",
    "user": {
      "id": "57fabaed-446a-40b4-a6ec-e0ac8cad57e3",
      "role": "user",
      "created_at": "2019-04-24T09:49:47.158005Z",
      "updated_at": "2019-04-24T09:49:48.301933Z",
      "last_active": "2019-04-24T09:49:48.300566Z",
      "online": false
    },
    "attachments": [],
    "latest_reactions": [
      {
        "message_id": "4b3c7b6c-a39d-4069-9450-2a3716cf4ca6",
        "user": {
          "id": "57fabaed-446a-40b4-a6ec-e0ac8cad57e3",
          "role": "user",
          "created_at": "2019-04-24T09:49:47.158005Z",
          "updated_at": "2019-04-24T09:49:48.301933Z",
          "last_active": "2019-04-24T09:49:48.300566Z",
          "online": true
        },
        "type": "lol",
        "created_at": "2019-04-24T09:49:48.481994Z"
      }
    ],
    "own_reactions": [],
    "reaction_counts": {
      "lol": 1
    },
    "reply_count": 0,
    "created_at": "2019-04-24T09:49:48.334808Z",
    "updated_at": "2019-04-24T09:49:48.483028Z",
    "mentioned_users": []
  },
  "reaction": {
    "message_id": "4b3c7b6c-a39d-4069-9450-2a3716cf4ca6",
    "user": {
      "id": "57fabaed-446a-40b4-a6ec-e0ac8cad57e3",
      "role": "user",
      "created_at": "2019-04-24T09:49:47.158005Z",
      "updated_at": "2019-04-24T09:49:48.301933Z",
      "last_active": "2019-04-24T09:49:48.300566Z",
      "online": true
    },
    "type": "lol",
    "created_at": "2019-04-24T09:49:48.481994Z"
  },
  "user": {
    "id": "57fabaed-446a-40b4-a6ec-e0ac8cad57e3",
    "role": "user",
    "created_at": "2019-04-24T09:49:47.158005Z",
    "updated_at": "2019-04-24T09:49:48.301933Z",
    "last_active": "2019-04-24T09:49:48.300566Z",
    "online": true,
    "unread_channels": 2,
    "unread_count": 2,
    "channel_unread_count": 1,
    "channel_last_read_at": "2019-04-24T09:49:48.321138Z",
    "total_unread_count": 2
  },
  "created_at": "2019-04-24T09:49:48.488497Z"
}

reaction.deleted

{
  "cid": "messaging:fun",
  "type": "reaction.deleted",
  "message": {
    "id": "4b3c7b6c-a39d-4069-9450-2a3716cf4ca6",
    "text": "new stuff",
    "html": "<p>new stuff</p>\n",
    "type": "regular",
    "user": {
      "id": "57fabaed-446a-40b4-a6ec-e0ac8cad57e3",
      "role": "user",
      "created_at": "2019-04-24T09:49:47.158005Z",
      "updated_at": "2019-04-24T09:49:48.301933Z",
      "last_active": "2019-04-24T09:49:48.300566Z",
      "online": false
    },
    "attachments": [],
    "latest_reactions": [],
    "own_reactions": [],
    "reaction_counts": {},
    "reply_count": 0,
    "created_at": "2019-04-24T09:49:48.334808Z",
    "updated_at": "2019-04-24T09:49:48.511631Z",
    "mentioned_users": []
  },
  "reaction": {
    "message_id": "4b3c7b6c-a39d-4069-9450-2a3716cf4ca6",
    "user": {
      "id": "57fabaed-446a-40b4-a6ec-e0ac8cad57e3",
      "role": "user",
      "created_at": "2019-04-24T09:49:47.158005Z",
      "updated_at": "2019-04-24T09:49:48.301933Z",
      "last_active": "2019-04-24T11:49:48.497656+02:00",
      "online": true
    },
    "type": "lol",
    "created_at": "2019-04-24T09:49:48.481994Z"
  },
  "user": {
    "id": "57fabaed-446a-40b4-a6ec-e0ac8cad57e3",
    "role": "user",
    "created_at": "2019-04-24T09:49:47.158005Z",
    "updated_at": "2019-04-24T09:49:48.301933Z",
    "last_active": "2019-04-24T11:49:48.497656+02:00",
    "online": true,
    "total_unread_count": 2,
    "unread_channels": 2,
    "unread_count": 2,
    "channel_unread_count": 1,
    "channel_last_read_at": "2019-04-24T09:49:48.321138Z"
  },
  "created_at": "2019-04-24T09:49:48.511082Z"
}

member.added

{
  "cid": "messaging:fun",
  "type": "member.added",
  "member": {
    "user_id": "d4d7b21a-78d4-4148-9830-eb2d3b99c1ec",
    "user": {
      "id": "d4d7b21a-78d4-4148-9830-eb2d3b99c1ec",
      "role": "user",
      "created_at": "2019-04-24T09:49:47.149933Z",
      "updated_at": "2019-04-24T09:49:47.151159Z",
      "online": false
    },
    "created_at": "2019-04-24T09:49:48.534412Z",
    "updated_at": "2019-04-24T09:49:48.534412Z"
  },
  "user": {
    "id": "d4d7b21a-78d4-4148-9830-eb2d3b99c1ec",
    "role": "user",
    "created_at": "2019-04-24T09:49:47.149933Z",
    "updated_at": "2019-04-24T09:49:47.151159Z",
    "online": false,
    "channel_last_read_at": "2019-04-24T09:49:48.537084Z",
    "total_unread_count": 0,
    "unread_channels": 0,
    "unread_count": 0,
    "channel_unread_count": 0
  },
  "created_at": "2019-04-24T09:49:48.537082Z"
}

member.updated

{
  "cid": "messaging:fun",
  "type": "member.updated",
  "member": {
    "user_id": "d4d7b21a-78d4-4148-9830-eb2d3b99c1ec",
    "user": {
      "id": "d4d7b21a-78d4-4148-9830-eb2d3b99c1ec",
      "role": "user",
      "created_at": "2019-04-24T09:49:47.149933Z",
      "updated_at": "2019-04-24T09:49:47.151159Z",
      "online": false
    },
    "is_moderator": true,
    "created_at": "2019-04-24T09:49:48.534412Z",
    "updated_at": "2019-04-24T09:49:48.547034Z"
  },
  "user": {
    "id": "d4d7b21a-78d4-4148-9830-eb2d3b99c1ec",
    "role": "user",
    "created_at": "2019-04-24T09:49:47.149933Z",
    "updated_at": "2019-04-24T09:49:47.151159Z",
    "online": false,
    "total_unread_count": 0,
    "unread_channels": 0,
    "unread_count": 0,
    "channel_unread_count": 0,
    "channel_last_read_at": "2019-04-24T09:49:48.549211Z"
  },
  "created_at": "2019-04-24T09:49:48.54921Z"
}

member.removed

{
    "cid": "messaging:fun",
    "type": "member.removed",
    "user": {
        "id": "6585dbbb-3d46-4943-9b14-a645aca11df4",
        "role": "user",
        "created_at": "2019-03-22T14:22:04.581208Z",
        "online": false
    },
    "created_at": "2019-03-22T14:22:07.040496Z"
}

channel.updated

{
    "cid": "messaging:fun",
    "type": "channel.updated",
    "channel": {
        "cid": "messaging:fun",
        "id": "fun",
        "type": "messaging",
        "last_message_at": "2019-04-24T09:49:48.576202Z",
        "created_by": {
            "id": "57fabaed-446a-40b4-a6ec-e0ac8cad57e3",
            "role": "user",
            "created_at": "2019-04-24T09:49:47.158005Z",
            "updated_at": "2019-04-24T09:49:48.301933Z",
            "last_active": "2019-04-24T09:49:48.497656Z",
            "online": true
        },
        "created_at": "2019-04-24T09:49:48.180908Z",
        "updated_at": "2019-04-24T09:49:48.180908Z",
        "frozen": false,
        "config": {
            "created_at": "2016-08-18T16:42:30.586808Z",
            "updated_at": "2016-08-18T16:42:30.586808Z",
            "name": "messaging",
            "typing_events": true,
            "read_events": true,
            "connect_events": true,
            "search": true,
            "reactions": true,
            "replies": true,
            "mutes": true,
            "message_retention": "infinite",
            "max_message_length": 5000,
            "automod": "disabled",
            "commands": [
                "giphy",
                "flag",
                "ban",
                "unban",
                "mute",
                "unmute"
            ]
        },
        "awesome": "yes"
    },
    "created_at": "2019-04-24T09:49:48.594316Z"
}

channel.deleted

{
  "cid": "messaging:fun",
  "type": "channel.deleted",
  "channel": {
    "cid": "messaging:fun",
    "id": "fun",
    "type": "messaging",
    "created_at": "2019-04-24T09:49:48.180908Z",
    "updated_at": "2019-04-24T09:49:48.180908Z",
    "deleted_at": "2019-04-24T09:49:48.626704Z",
    "frozen": false,
    "config": {
      "created_at": "2016-08-18T18:42:30.586808+02:00",
      "updated_at": "2016-08-18T18:42:30.586808+02:00",
      "name": "messaging",
      "typing_events": true,
      "read_events": true,
      "connect_events": true,
      "search": true,
      "reactions": true,
      "replies": true,
      "mutes": true,
      "message_retention": "infinite",
      "max_message_length": 5000,
      "automod": "disabled",
      "commands": [
        "giphy",
        "flag",
        "ban",
        "unban",
        "mute",
        "unmute"
      ]
    }
  },
  "created_at": "2019-04-24T09:49:48.630913Z"
}

user.updated

{
  "type": "user.updated",
  "user": {
    "id": "thierry-7b690297-98fa-42dd-b999-a75dd4c7c993",
    "role": "user",
    "online": false,
    "awesome": true
  },
  "created_at": "2019-04-24T12:54:58.956621Z",
  "members": []
}

Stream Chat supports push for both Android and iOS. In this section you will find all information on how to configure push for APN and Firebase.

Only new messages are pushed to mobile devices, all other chat events are only send to Websocket clients and webhook endpoints if configured.

Push delivery logic

Push message delivery follows the following logic

• Only channel members can receive push messages
• Members that are currently online do not receive push messages
• Messages added within a thread are only sent to users that are part of that thread (they posted at least a message or were mentioned)
• Messages from muted users are not sent
• Messages are sent to all registered devices for a user (up to 25)

Push Notifications for iOS

Using the APNs, your users' apps can receive push notifications directly on their client app for new messages when offline. Stream supports both Certificate-based provider connection trust(.p12 certificate), as well as Token-based provider connection trust(JWT).

Setup APN push using token authentication

Token based authentication is the preferred way to setup push. Token based is very easy to setup and guarantees strong security.

Step 1. Retrieve your TeamID

Sign in to your Apple Developer Account and then navigate to Membership. Copy your Team ID and store it somewhere safe.

Step 2. Retrieve your Bundle ID

1. From App Store Connect, navigate to My Apps

2. Select the app you are using Stream Chat with

3. Make sure the App Store tab is selected and navigate to App Information on the left bar

   

4. In the Bundle ID(1)dropdown, make sure the proper bundle id is selected. Copy the bundle id next to Your Bundle ID(2)

   

Step 3. Generate a token

1. From your Apple Developer Account overview, navigate to Certificates, Identifiers & Providers

   

2. Make sure iOS, tvOS, watchOS is selected on the navigation pane on the left, and go to Keys > All

   

3. Click on the + button to Add a new key

   

4. In the Name field input a name for your key. In the Key Services section, select Apple Push Notifications service (APNs) and then click on Continue

   

5. Review the information from the previous step and click on Confirm

6. Copy your Key ID and store it somewhere safe.

7. Save the key on your hard drive. Note:You can only dowload your key now. If you lose the key, you will have to repeat step 2

   

Step 4. Upload the Key credentials to Stream chat

Upload the TeamID, KeyID, Key and BundleID from the previous steps.

• JS/Node
• CLI

await client.updateAppSettings({
    apn_config: {
        auth_key: fs.readFileSync(
            './auth-key.p8',
            'utf-8',
        ),
        auth_type: 'token',
        key_id: 'key_id',
        bundle_id: 'com.apple.test',
        team_id: 'team_id',
        notification_template: `{"aps" :{"alert":{"title":"{{ sender.name }}","subtitle":"New direct message from {{ sender.name }}","body":"{{ message.text }}"},"badge":"{{ unread_count }}","category":"NEW_MESSAGE"}}`
    },
})

stream chat:push:apn \
    --auth_key './auth-key.p8' \
    --team_id 'team_id' \
    --key_id 'key_id' \
    --bundle_id 'com.apple.test' \
    -n '{"aps":{"alert":{"title":"{{ sender.name }}","subtitle":"New direct message from {{ sender.name }}","body":"{{ message.text }}"},"badge":{{ unread_count }},"category":"NEW_MESSAGE"}}'

Note:If your wish to use the APNs development endpoint instead of the production one, you must specify this when uploading the Key Credentials via the --development parameter:

• JS/Node
• CLI

await client.updateAppSettings({
    apn_config: {
        auth_key: fs.readFileSync(
            './auth-key.p8',
            'utf-8',
        ),
        key_id: 'key_id',
        auth_type: 'token',
        development: true,
        bundle_id: 'com.apple.test',
        team_id: 'team_id',
        notification_template: `{"aps" :{"alert":{"title":"{{ sender.name }}","subtitle":"New direct message from {{ sender.name }}","body":"{{ message.text }}"},"badge":{{ unread_count }},"category":"NEW_MESSAGE"}}`
    },
})

stream chat:push:apn \
    --auth_key './auth-key.p8' \
    --team_id 'team_id' \
    --key_id 'key_id' \
    --bundle_id 'com.apple.test' \
    --development \
    -n '{"aps":{"alert":{"title":"{{ sender.name }}","subtitle":"New direct message from {{ sender.name }}","body":"{{ message.text }}"},"badge":{{ unread_count }},"category":"NEW_MESSAGE"}}'

Setup APN push using certificate authentication

If token based authentication is not an option, you can setup APN with certificate authentication. You will need to generate a valid p12 certificate for your application and upload it to Stream.

Step 1. Create a Certificate Signing Request(CSR)

1. On your Mac, open Keychain Access

2. Go to Keychain Access > Certificate Assistant > Request a Certificate from a Certificate Authority.

   

3. Fill out the information in the Certificate Information window as specified below and click "Continue."

   • In the User Email Address field, enter the email address to identify with this certificate
   • In the Common Name field, enter your name
   • In the Request group, click the "Saved to disk" option
   
4. Save the file on your hard drive.(E.g.: /Users/john/Downloads/CertificateSigningRequest.certSigningRequest)

Step 2. Create a Push Notification SSL certificate

1. Sign in to your Apple Developer Account and then navigate to Certificates, Identifiers & Providers

   

2. Make sure iOS, tvOS, watchOS is selected on the navigation pane on the left, and go to Certificates > All

   

3. Click on the + button to Add a new certificate

   

4. In the Development section, select Apple Push Notification service SSL (Sandbox) and then click on Continue

   

5. Select your app in the dropdown list and then click on Continue

6. You will see instructions on how to generate a .certSigningRequest file. This was already covered in the previous section. Click on Continue

7. Click on Choose File and then navigate to where you have saved the .certSigningRequest file from the previous section (E.g.: /Users/john/Downloads/CertificateSigningRequest.certSigningRequest). Click on Continue

8. Click on Download to save your certificate to your hard drive.(E.g.: /Users/john/Downloads/aps_development.cer)

   

Step 3. Export the certificate in .p12 format

1. On your mac, navigate to where you have saved the .cer file from the previous section (E.g.: /Users/john/Downloads/aps_development.cer) and double click on the file. This will add it to your Keychain

2. Go to Keychain Access

3. At the top left, select Keychains > login.

   Then, at the bottom left, select Category > Certificates

   

4. Select the certificate you've created in the previous step. It should look like Apple Development IOS Push Services: YOUR_APP_NAME and expand it to see the private key(it should be named after the Name you provided when creating the Certificate Signing Request: in the case of this example: John Smith)

   

5. Right-click the private key and click on Export. In the File format section select Personal Information Exchange (.p12) and save the file on your hard drive

   

Step 4. Upload the certificate to Stream chat

• JS/Node
• CLI

await client.updateAppSettings({
    apn_config: {
        p12_cert: fs.readFileSync(
            './certificate.p12',
        ),
        auth_type: 'certificate',
        notification_template: `{"aps":{"alert":{"title":"{{ sender.name }}","subtitle":"New direct message from {{ sender.name }}","body":"{{ message.text }}"},"badge":{{ unread_count }},"category":"NEW_MESSAGE"}}`
    },
})

stream chat:push:apn \
    --p12_cert './certificate.p12' \
    -n '{"aps":{"alert":{"title":"{{ sender.name }}","subtitle":"New direct message from {{ sender.name }}","body":"{{ message.text }}"},"badge":{{ unread_count }},"category":"NEW_MESSAGE"}}'

Note:If your wish to use the APNs development endpoint instead of the production one, this information will be automatically taken from your certificate.

Using Firebase, your users' apps can receive push notifications directly on their client app for new messages when offline.

In order to push notifications to Android devices, you need to have an application on Firebase and configure your Stream account using the Firebase server key.

Retrieving the Server Key from Firebase

1. From the Firebase Console, select the project your app belongs to.

2. Click on the gear icon next to Project Overview and navigate to Project settings

   

3. Navigate to the Cloud Messaging tab

4. Under Project Credentials, locate the Server key and copy it

   

5. Upload the Server Key

   • JS/Node
   • CLI

   await client.updateAppSettings({
       firebase_config: {
           server_key: 'server_key',
           notification_template: `{"message":{"notification":{"title":"New messages","body":"You have {{ unread_count }} new message(s) from {{ sender.name }}"},"android":{"ttl":"86400s","notification":{"click_action":"OPEN_ACTIVITY_1"}}}}`
       },
   })

   stream chat:push:firebase \
       -k 'server_key' \
       -n '{"message":{"notification":{"title":"New messages","body":"You have {{ unread_count }} new message(s) from {{ sender.name }}"},"android":{"ttl":"86400s","notification":{"click_action":"OPEN_ACTIVITY_1"}}}}'

For both Firebase and APN, the payload that is being sent is rendered using the handlebars templating language, to ensure full configurability for your app.

Stream provides the following variables in the template rendering context:

Defaults

When editing APN/Firebase settings, if you leave the notification_template field empty, default templates will be used.

APN default:

{
    "aps" : {
        "alert" : {
            "title" : "{{ sender.name }} @ {{ channel.name }}",
            "body" : "{{ message.text }}"
        },
        "badge": {{ unread_count }},
        "category" : "NEW_MESSAGE"
    }
}

Firebase default:

{
    "title": "{{ sender.name }} @ {{ channel.name }}",
    "body": "{{ message.text }}",
    "click_action": "OPEN_ACTIVITY_1",
    "sound": "default"
}

Limitations

There are some limitations that Stream imposes on the push notification handlebars template to make sure no malformed payloads are being sent to push providers

• Custom arrays cannot be indexed

  For example, given the context:

  {
      "sender":{
          "name": "Bob",
          "some_array": ["foo","bar"]
      }
  }

  And the template:

  "title": {{sender.some_array.[0]}}

  The rendered payload will be:

  "title": ""

• Interpolating whole lists and object isn't allowed

  For example, given the context:

  {
      "sender":{
          "name": "bob",
          "some_array": ["foo","bar"],
          "address": {
              "street": "willow str"
          }
      }
  }

  And the template:

  "title": "{{ sender.some_array }} {{ sender.address }}"

  The rendered payload will be:

  "title": "[] {}"

• Unquoted fields that aren't in the context will be rendered as empty strings

  For example, given the context:

  {
      "sender":{
          "name": "bob"
      }
  }

  And the template:

  "title": {{ sender.missing_field }}

  The rendered payload will be:

  "title": ""

Advanced use cases

For advanced use cases(e.g. A list of channel members in the notification title, conditional rendering, etc), Stream provides some handlebars helper functions

Most of the functions above are straight forward, except for implodeMembers, which will be detailed further.

The full function signature is: {{implodeMembers otherMembers|members [limit=] [separator=] [nameField=] [suffixFmt=]}}

Examples

Let's put these helpers to use in a few examples:

1. Rendering channel members in the notification title. Each member's name is stored in the fullName field.

   What we want to achieve:

   {
       "aps": {
           "alert": {
               "title": "Bob Jones, Jessica Wright, Tom Hadle and 4 other(s)",
               "body": "Bob Jones: Hello there fellow channel members"
           },
           "badge": 0
       }
   }

   How we will achieve it: using implodeMembers with a custom name field (leaving others empty so that defaults will be used):

   {
       "aps": {
           "alert": {
               "title": "{{implodeMembers otherMembers nameField="fullName"}}",
               "body": "{{ sender.fullName }}: {{ message.text }}"
           },
           "badge": {{ unread_count }}
       }
   }

2. Rendering channel members in the notification title. Each member's name is stored in the nested details.name field.

   What we want to achieve:

   {
       "aps": {
           "alert": {
               "title": "Bob Jones, Jessica Wright, Tom Hadle and 4 other(s)",
               "body": "Bob Jones: Hello there fellow channel members"
           },
           "badge": 0
       }
   }

   How we will achieve it: since implodeMembers doesn't support nested fields, we need to use a bunch of helpers such as each,ifLte. Note how the use of ~ will trim the whitespaces so that the title in rendered in a single row:

   {
       "aps": {
           "alert": {
               "title": "
               {{~#each otherMembers}}
                   {{#ifLte @index 2}}
                       {{~this.details.name}}{{#ifLt @index 2 }}, {{/ifLt~}}
                   {{~else if @last~}}
                       {{{ " " }}} and {{remainder otherMembers 3}} other(s)
                   {{~/ifLte~}}
               {{/each~}}",
               "body": "{{ sender.details.name }}: {{ message.text }}"
           },
           "badge": {{ unread_count }}
       }
   }

Once your app has push enabled, you can use the APIs to register user devices such as iPhones and Android phones.

Each chat user has a limit of 25 unique devices. Once this limit is reached, the oldest device will be removed and replaced by the new device.

Register a device

• JS/Node
• Python
• Ruby
• Java
• Swift
• CLI

await client.addDevice(
    '2ffca4ad6599adc9b5202d15a5286d33c19547d472cd09de44219cda5ac30207', 
    'apn', 
    '42'
)

client.add_device(
    '2ffca4ad6599adc9b5202d15a5286d33c19547d472cd09de44219cda5ac30207', 
    'apn', 
    '42'
)

client.add_device(
    '2ffca4ad6599adc9b5202d15a5286d33c19547d472cd09de44219cda5ac30207', 
    'apn', 
    '42'
)

client.addDevice(deviceToken, new CompletableCallback() { ... });

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    Client.shared.addDevice(deviceToken: deviceToken).subscribe().disposed(by: disposeBag)
}

stream chat:push:device:add \
    --device_id '2ffca4ad6599adc9b5202d15a5286d33c19547d472cd09de44219cda5ac30207'
    --user_id '42'
    --provider 'apn'

Deregister a device

• JS/Node
• Python
• Ruby
• Java
• Swift
• CLI

await client.removeDevice(
    '2ffca4ad6599adc9b5202d15a5286d33c19547d472cd09de44219cda5ac30207', 
    '42'
)

client.delete_device(
    '2ffca4ad6599adc9b5202d15a5286d33c19547d472cd09de44219cda5ac30207', 
    '42'
)

client.delete_device(
    '2ffca4ad6599adc9b5202d15a5286d33c19547d472cd09de44219cda5ac30207', 
    '42'
)

client.removeDevice(deviceToken, new CompletableCallback() { ... });

Client.shared.removeDevice(deviceId: device.id).subscribe().disposed(by: disposeBag)

stream chat:push:device:delete \
    --device_id '2ffca4ad6599adc9b5202d15a5286d33c19547d472cd09de44219cda5ac30207'
    --user_id '42'

Once you're all setup with push notifications, you can use the CLI to test how the these notifications will look for your devices.

In preparation of this make sure that:

• Your app has push notifications configured for at least one provider(APNs or Firebase)
• You have a user that has at least one device associated

The base command for testing push notifications is:

• CLI

stream chat:push:test --user_id 'user_123'

This will do several things for you:

1. Pick a random message from a channel that this user is part of
2. Use the notification templates configured for your push providers to render the payload using this message
3. Send this payload to all of the user's devices

This particular use case is ideal for testing a newly configured app, to make sure the push notifications are exactly as wanted.

In some other cases, your app is already configured with push notifications and is running smoothly, but you want to try out a new notification template. For example, let's say you want to test a new APN notification template:

• CLI

stream chat:push:test --user_id 'user_123' --apn_notification_template '{"aps":{"alert":{"title":"{{ sender.name }} @ {{ channel.name }}","body":"testing out new stuff:{{ message.text }}"},"category":"NEW_MESSAGE_2"}}'

As you can see, this one time only, the new template will be used for the push notification instead of the configured one:

Here's a full list of parameters that you can use with the test command:

To try out push notifications on an actual device, you can use React Native to quickly build an app that just receives notifications.

Before getting down to business with React Native, a few things need to be setup first:

1. Make sure you’ve created a development app within the dashboard.

   

2. To make things easier, we are going to disable auth so that we can easily test push messages. Please note that this only suitable for test/dev environments.

   From your app's dashboard, navigate to the Chat tab and then scroll down to Chat Events. Make sure the Disable Auth Checks toggle is On and click on Save.

   

3. Install XCode and Command Line Tools. More info on that here

4. Install dependencies and initialize your test project(for this tutorial we'll use the name chat-push-example)

   yarn global add react-native-cli

   react-native init chat-push-example

   cd chat-push-example
   yarn add stream-chat react-native-push-notifications
   react-native link react-native-push-notifications

   Note: If you are adding this to an existing React Native project created with Expo or CRNA, you will need to eject. Please note that this ejecting is irreversible; however, it is required to access native iOS and Android capabilities.
   Shortcut: If you don't want to jump through all the hoops described in the following sections, we have a mostly preconfigured repository with everything described in this doc on GitHub. Just follow the instructions in the README to get started.

For iOS, we will be using Apple’s APN service to power the push functionality, rather than Expo or Firebase Cloud Messaging.

You will need to link the PushNotificationIOS library, which is exported from React Native, to your project:

1. Open Xcode and in the sidebar on the left, make sure you’re in the Project Navigator tab (the folder icon). Right click on the Libraries directory within your project name and select Add files to YOUR_PROJECT_NAME.

   

2. A file dialog will pop-up. Navigate to the root of your project, then to node_modules/react-native/Libraries/PushNotificationsIOS/RCTPushNotification.xcodeproj. Click Add.

   

3. Click the root of your application's Xcode project in the navigator sidebar and click Build Phases in the tabs at the top of the middle pane. On the next screen, find the dropdown labeled Link Binaries with Libraries, expand it, and click the plus icon in the bottom left.

   

4. Type RCTPushNotification in the search box. You should see a file named libRCTPushNotification.a in the list. Select it and click Add.

   

5. Navigate to AppDelegate.m in your project.

   

6. Add the following import just below #import "AppDelegate.h".

   #import "AppDelegate.h"
   
   #import <React/RCTPushNotificationManager.h> // <-- THIS

7. Add the following snippet to the bottom of the file, just before @end.

   // Required to register for notifications
   - (void)application:(UIApplication *)application didRegisterUserNotificationSettings:(UIUserNotificationSettings *)notificationSettings
    {
     [RCTPushNotificationManager didRegisterUserNotificationSettings:notificationSettings];
    }
    // Required for the register event.
   - (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken
    {
     [RCTPushNotificationManager didRegisterForRemoteNotificationsWithDeviceToken:deviceToken];
    }
    // Required for the notification event. You must call the completion handler after handling the remote notification.
   - (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo
                                                           fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler
    {
      [RCTPushNotificationManager didReceiveRemoteNotification:userInfo fetchCompletionHandler:completionHandler];
    }
    // Required for the registrationError event.
   - (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error
    {
     [RCTPushNotificationManager didFailToRegisterForRemoteNotificationsWithError:error];
    }
    // Required for the localNotification event.
   - (void)application:(UIApplication *)application didReceiveLocalNotification:(UILocalNotification *)notification
    {
     [RCTPushNotificationManager didReceiveLocalNotification:notification];
    }

Running on iOS devices

If you want to run your React Native application on a device, you’re going to have to edit the XCode project to include code signing and push capabilities:

1. In XCode, from the navigation bar on the left make sure your project is selected. Navigate to the General tab.

   

2. Expand Signing and make sure you are logged in with your Apple Developer Account. Once logged in, select your development team and be sure to check Automatically Manage Signing.

   

3. Expand Identity and make sure your Bundle Identifier matches the one you used to configure push notifications with Stream. If you haven’t done this yet, please refer to the docs here and then return to this tutorial.

   

4. Navigate to the Capabilities tab and make sure Push Notifications are enabled

   

5. You’re all set! Plug in your iOS device, select it from the run menu in XCode and press Run.

   

For Android, we’ll be using Firebase Cloud Messaging to power push notifications:

1. Go to the Firebase Console, create a new application OR select an existing project.
2. Go to Project Settings and under the General tab.

3. Click on Your Apps, add an Android application and download your google-services.json file – you need to put this in the root of your projects android directory.

   

4. Put google-services.json in the root of your project's android directory.(e.g. ./android)

5. Make sure google-services.json file is included in your Android project’s dependencies by navigating to your project level build.gradle file (./android/build.gradle) and adding the following line:

   buildscript {
   	// ...
   	dependencies {
   		// ...
   		classpath 'com.google.gms:google-services:+'
   		// ...	
   	}
   	// ...
   }

6. In the same directory, find the settings.gradle file and copy the following content into the file if it isn’t already there.

   include ':react-native-push-notification'
   project(':react-native-push-notification').projectDir = file('../node_modules/react-native-push-notification/android')

   Note: When you previously ran react-native link, it should have added the necessary files; however, it’s best to always double check. Linking can be temperamental at times.

7. Navigate to ./android/app/src and check you have the res folder. If not, create it and inside create another folder values. Then create a new file named colours.xml whose content is the following:

   
   <resources>
   <color name="white">#FFF</color>
   </resources>
           

8. Linking may have also taken care of this step, but once again, navigate to MainApplication.java in android/app/src/main and check it has these two parts, as highlighted with comments:

   import com.dieam.reactnativepushnotification.ReactNativePushNotificationPackage;  // <--- THIS
   
   public class MainApplication extends Application implements ReactApplication {
   
     private final ReactNativeHost mReactNativeHost = new ReactNativeHost(this) {
         @Override
         protected boolean getUseDeveloperSupport() {
           return BuildConfig.DEBUG;
         }

9. Go to android/app/src/main/AndroidManifest.xml and copy the following (the comments below will help guide you for your particular setup)

   
   <!-- < Only if you're using GCM or localNotificationSchedule() > -->
     <uses-permission android:name="android.permission.WAKE_LOCK" />
     <permission
       android:name="${applicationId}.permission.C2D_MESSAGE"
       android:protectionLevel="signature" />
      <uses-permission android:name="${applicationId}.permission.C2D_MESSAGE" />
   
      <!-- < Only if you're using GCM or localNotificationSchedule() > -->
      <uses-permission android:name="android.permission.VIBRATE" />
      <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>
   
   <!-- Then, within the <application> block, place the following -->
   
     <receiver
       android:name="com.google.android.gms.gcm.GcmReceiver"
       android:exported="true"
       android:permission="com.google.android.c2dm.permission.SEND" >
       <intent-filter>
           <action android:name="com.google.android.c2dm.intent.RECEIVE" />
           <category android:name="${applicationId}" />
       </intent-filter>
     </receiver>
   
     <receiver android:name="com.dieam.reactnativepushnotification.modules.RNPushNotificationPublisher" />
     <receiver android:name="com.dieam.reactnativepushnotification.modules.RNPushNotificationBootEventReceiver">
       <intent-filter>
         <action android:name="android.intent.action.BOOT_COMPLETED" />
       </intent-filter>
     </receiver>
     <service android:name="com.dieam.reactnativepushnotification.modules.RNPushNotificationRegistrationService"/>
   
     <service
         android:name="com.dieam.reactnativepushnotification.modules.RNPushNotificationListenerServiceGcm"
         android:exported="false" >
       <intent-filter>
         <action android:name="com.google.android.c2dm.intent.RECEIVE" />
       </intent-filter>
     </service>
   
     <service
           android:name="com.dieam.reactnativepushnotification.modules.RNPushNotificationListenerService"
           android:exported="false" >
       <intent-filter>
           <action android:name="com.google.firebase.MESSAGING_EVENT" />
       </intent-filter>
   </service>
           

Unlike iOS, the Android emulator does support push notifications - just make sure you use an emulator with Google Play Services installed (shown by the Play Store Icon in the AVD Manager)

Thanks to react-native-push-notifications, we are provided a platform agnostic experience while still using native push on each platform.

All that's left is integrating the test app with the Stream Chat client. Open up App.js in the root of your project and check that componentDidMount exists. If the file does not exist add an async componentDidMount method to the class:

//...
import { PushNotificationIOS } from 'react-native';
import PushNotification from 'react-native-push-notification';
import { StreamChat } from 'stream-chat';
import { API_KEY, USER_TOKEN, USER_ID } from 'react-native-dotenv';

export default class App extends Component {

    async componentDidMount() {
  
      const client = new StreamChat(API_KEY, null);
  
      await client.setUser({ id: USER_ID }, USER_TOKEN);
  
      PushNotification.configure({
        onRegister(token) {
          client
            .addDevice(token.token, token.os === 'ios' ? 'apn' : 'firebase')
            .then(() => {
              console.log(`registered device with token ${token}`);
            })
            .catch((e) => {
              console.error(`registering device failed: ${e}`);
            });
        },
        onNotification(notification) {
          notification.finish(PushNotificationIOS.FetchResult.NoData);
        },
        senderID: "1069091084846",// (Android Only) Grab this from your Firebase Dashboard where you got google-services.json
        requestPermissions: true
      });
    }
    //...
}

For the sake of this tutorial, we created a .env file to store these values and grab them using react-native-dotenv as shown above – a good idea for your API_KEY in any case, but your USER_ID and USER_TOKEN will likely come from elsewhere in a real-world setting, depending on your use-case.

All that's left to do is to use the stream-cli to send out a test push notification. You can find out how that works in this section of the docs. Just make sure you use the same user_id in both the cli and this test app.

To build your own chat bot you can use the following 4 features of the chat API:

1. Webhooks
2. Attachments, Fields and Actions
3. Custom Slash Commands
4. Custom Attachments

As an example let's say that you want to build a chatbot that handles customer care for a bank. You'll typically want to gather some data automatically before routing the request to a human. To achieve that you would start by setting up a webhook (webhook docs). The webhook will be called whenever there is a new message on the channel.

When handling the webhook you'll want to run some AI to determine what the user is talking about. A good starting point is recognizing the most common requests. For instance your AI could recoganize a message like this: "I noticed a weird transaction on my account." Next the AI can reply by asking the user for more details leveraging the attachment, field and action system.

Let's have the AI reply with a message asking for more information.

const message = {
    text: 'Which account was affected by this issue?',
    attachments: [
    {
        type: 'form',
        title: 'Select your account',
        actions: [
                {
                        name: 'account',
                        text: 'Checking',
                        style: 'primary',
                        type: 'button',
                        value: 'checking',
                },
                {
                        name: 'account',
                        text: 'Saving',
                        style: 'default',
                        type: 'button',
                        value: 'saving',
                },
                {
                        name: 'account',
                        text: 'Cancel',
                        style: 'default',
                        type: 'button',
                        value: 'cancel',
                },
        ],
        },
        ],
};
const response = await channel.sendMessage(message);

When the user submits their choice the webhook endpoint will be called again. Now that you have some more information gathered it's time to connect the user to a real support agent. You can do this by adding a member to the conversation and your support agent will be notified in real time. To improve their productivity you'll want to leverage slash commands. Slash commands make it easy to automate common tasks. Lets show how to create your own slash command for managing tickets

As a first step you'll want to setup a custom slash command for the "ticket" keyword. At the moment this isn't fully documented yet, so contact support if you need help. With the slash command setup your account managers will be able to automate common tasks like this: /ticket suspicious transaction with id 1234

const message = {
    text: '/ticket suspicious transaction with id 1234'
};
const response = await channel.sendMessage(message);

Custom attachments can also be helpful when building chat bots. You could for instance create a custom attachment for allowing users to select a date. The React Chat tutorial shows an example of how to create a custom attachment.

The Chat API allows you to specify filters and ordering for several endpoints. You can query channels, users and messages. The query syntax is similar to Mongoose. Note that we don't run Mongo in the background and only support a subset of operations. Have a look below at the complete list of supported operations:

If you've just started using Stream, you might want to import data from your infrastructure or provider. Instead of using the APIs and creating your own import scripts, you can make use of our import feature.

The process

The steps for importing data into your app are as follows:

1. Generate the import file for your data (full file reference below)
2. Reach out to send us the import file
3. The file will be validated according to the rules described in this doc
4. If validation passes, a member of our team will approve and run the import
5. Once the import is completed (usually a few minutes), you will get a confirmation email

Import file

The import file must be structured as a JSON array of objects. Each object is an item to add to your application (eg. a user, a message, ...).

Import entries format

Item types

An import file can contain entries with any of these types.

user type

{
  "type": "user",
  "item": {
    "id": "aad24491-c286-4169-bbfc-9280de419cb6",
    "name": "Jesse",
    "profile_image": "http://getstream.com",
    "created_at": "2017-01-01T01:00:00Z",
    "description": "Taj Mahal guitar player at some point"
  }
}

channel type

{
  "type": "channel",
  "item": {
    "id": "6e693c74-262d-4d3d-8846-686364c571c8",
    "type": "livestream",
    "created_by": "aad24491-c286-4169-bbfc-9280de419cb6",
    "name": "Rock'n Roll Circus"
  }
}

message type

message attachments

Messages can contain a list of attachments such as videos, images and other custom types.

{
  "type": "message",
  "item": {
    "id": "977e691a-c091-4e3b-8f70-ba8944a3e500",
    "channel_type": "livestream",
    "channel_id": "6e693c74-262d-4d3d-8846-686364c571c8",
    "user":"aad24491-c286-4169-bbfc-9280de419cb6",
    "text": "Such a great song, check out my solo at 2:25",
    "type": "regular",
    "created_at": "2017-02-01T02:00:00Z",
    "attachments": [
      {
        "type": "video",
        "url": "https://www.youtube.com/watch?v=flgUbBtjl9c"
      }
    ]
  }
}

reaction type

{
  "type": "reaction",
  "item": {
    "message_id": "977e691a-c091-4e3b-8f70-ba8944a3e500",
    "type": "love",
    "user_id": "aad24491-c286-4169-bbfc-9280de419cb6",
    "created_at": "2019-03-02T15:00:00Z"
  }
}

member type

{
  "type": "member",
  "item": {
    "channel_type": "livestream",
    "channel_id": "6e693c74-262d-4d3d-8846-686364c571c8",
    "user_id": "aad24491-c286-4169-bbfc-9280de419cb6",
    "is_moderator": true,
    "created_at": "2017-02-01T02:00:00Z"
  }
}

Migrating from Layer is easy. This guide will help you complete the migration quickly:

1. Export

   The first step is downloading an export of your Layer data. The Layer docs specify how to create an export. Next email support@getstream.io your data export to have it imported to Stream. This process typically takes 1 business day.

2. Frontend components

   Layer doesn’t provide frontend components. You will want to decide if you want to customize one of Stream’s frontend components or work with the chat API from your own frontend. Implementing a fully featured Chat in React can be very time-consuming.

   Have a look at these 5 examples and see if you can customize them. Swapping the front end components is the fastest way to integrate with Stream.

3. Differences

   • Stream provides 5 built-in chat types for the most common use cases. The commerce chat type is the most similar to Layer. So you’ll want to use that one as a starting point.
   • Layer has the concept of Distinct Conversations and Non Distinct conversations. With Stream you initialize a channel with a channel type and channel id. So you simply need to make sure the ID is unique when you want to create a new conversation.
   • Stream doesn’t have MessageParts we have Message Attachments. The docs for sending messages are here
   • Conversations are called Channels and instead of Participants Stream has Members.
   • Layer allows you to specify a Metadata field. Stream allows you to add custom data directly to users, channels, messages, attachments and events.

4. Go live

   After testing your awesome new chat solution discuss a go-live date with Stream’s support team. We’ll re-import your data backup.

5. Help

   If you have more tips for migrating from Layer to Stream be sure to contact us. We’re refining this guide continuously.

Channel types

Sendbird has 2 channel types. The open channel or the group channel. Stream has 5 built-in channel types: livestream, messaging, commerce, gaming, and team. You can also create your own channel types. This allows you to configure the features and permissions to exactly fit your use case. Usually, you’ll want to use the “livestream” chat type if you’re using a Sendbird open channel.

Channels

Instead of the getChannel and channel.enter, Stream uses 1 API call to both get and enter a channel.

The concept of UserMessage and FileMessage in Sendbird is replaced using a Message with a list of attachments.

Thumbnails

Instead of specifying thumbnail sizes upfront you can request different image sizes at read time.

Private vs. Public groups

This difference is handled by Stream’s permission system. You can allow or not allow non-members to edit the list of members for a channel.

Limitations

• Stream currently doesn’t directly support translating messages. You can write a custom bot to support this though.
• You can query users

Every Application is rate limited at the API endpoint. These limits are set on a 1-minute and 15-minute time windows, API requests have specific rate limits. For example, reading a channel has a different limit than sending a message.

User and App base rate limits

There are two kind of rate limits for Chat: app rate limits and user rate limits.
App rate limits are calculated per endpoint for your entire application. When the limit is hit, all calls from the same app and endpoint will result in an error.
In order to avoid individual users to use your entire quota, every single user is limited to at most 60 requests per minute (per API endpoint). When the limit is exceeded, only request from that user will be rejected.

What Happens when you are Rate Limited

If an API call exceeds a rate limit during the target time window, subsequent requests for the same API function will be rejected. The payload returned for that API call will indicate that rate limiting has occurred.

If your application becomes rate-limited it doesn't block other API calls from working. For example, hitting a rate limit on follows will still allow you to read feeds. Each 'resource' is rate-limited separately.

Rate limits are reset at the end of each time window.

How to avoid rejected API requests

For Enterprise plans, Stream will review your architecture, and set higher rate limits for your production application. For other paid plans, you will need to review responses from Stream to watch for error conditions indicating that your API request was rate-limited and retry. We recommend implementing an exponential back-off retry mechanism.