Chat JS APIs
Chat JS APIs
These public JS APIs will be automatically available in your screens once a Chat layout component is used. You can also include these by manually adding the fliplet-chat dependency to your app.
Access the chat JS API
Use the init() constructor to initialize the chat JS API. This will return a promise that will resolve to the chat JS API instance. You can then use the instance to access the chat JS API methods.
// Initialize the chat JS API and wait for it to be ready
const chat = await Fliplet.Chat.init();
The chat instance has access to the following methods:
chat.create()- Create a new private conversation with one or more peoplechat.conversations()- Get the list of conversations for the current userchat.contacts()- Get the list of contacts available to chat withchat.unread.count()- Get the number of unread messages for the current userchat.unread.get()- Get the list of unread messages for the current user
Starting conversations
Start/open a private conversation with a specific person
Add a contactEmail parameter when loading the chat screen to start/open a conversation with a specific contact:
Fliplet.Navigate.screen(chatScreenId, {
query: '?contactEmail=john@example.org'
});
Start/open a group conversation with one or more people
Add a contactConversation parameter with the list of Data Source Entry IDs of the contacts to include in the group, excluding the current user:
Fliplet.Navigate.screen(chatScreenId, {
query: '?contactConversation=1,2,3,4'
});
Navigate to the chat screen opening up a specific conversation
Add a conversationId query parameter when navigating to a chat screen to open a specific conversation:
// Fetch the first conversation's ID from the chat JS API
const conversationId = _.first(await chat.conversations()).id;
// Navigate to the chat screen opening up the first conversation
Fliplet.Navigate.screen(123, { query: '?conversationId=' + conversationId });
Hooks
Run a hook before the conversations are displayed
Use the beforeChatConversationsRendering hook to modify the list of conversations before they are displayed. The hook will receive the following data:
data.conversations- The list of conversations to be displayeddata.container- The chat component jQuery element
Fliplet.Hooks.on('beforeChatConversationsRendering', function onBeforeChatConversationsRendering(data) {
// data.conversations
});
Your hook can return a promise that will resolve to the modified list of conversations. For example, the following code will remove the last two conversations from the list:
Fliplet.Hooks.on('beforeChatConversationsRendering', function onBeforeChatConversationsRendering(data) {
return { conversations: _.dropRight(data.conversations, 2) };
});
Run a hook before the contacts are displayed
Use the beforeChatContactsRendering hook to modify the list of contacts before they are displayed. The hook will receive the following data:
data.contacts- The list of contacts to be displayeddata.container- The chat component jQuery element
Fliplet.Hooks.on('beforeChatContactsRendering', function onBeforeChatContactsRendering(data) {
return data;
});
Your hook can return a promise that will resolve to the modified list of contacts. For example, the following code will remove the last two contacts from the list:
Fliplet.Hooks.on('beforeChatContactsRendering', function onBeforeChatContactsRendering(data) {
return { contacts: _.dropRight(data.contacts, 2) };
});
Overwriting data to be rendered
The beforeChatContactsRendering hook explained above can be useful to modify the contacts list data. In the example below we will add the url from files in the File Manager, by comparing their name to the name entered in the data source’s column called “Image”. The code seems complex because we are also taking into consideration that the data source column can contain urls, base64 strings and file ids:
const folderId = 325;
const imageColumn = 'Image';
Fliplet.Hooks.on('beforeChatContactsRendering', function onBeforeChatContactsRendering(data) {
return Fliplet.Media.Folders.get({ folderId: folderId }).then(function(response) {
const allFiles = response.files;
// Test pattern for URLS
const urlPattern = /^https?:\/\//i;
// Test pattern for BASE64 images
const base64Pattern = /^data:image\/[^;]+;base64,/i;
// Test pattern for Numbers/IDs
const numberPattern = /^\d+$/i;
allFiles.forEach(function(file) {
// Add this IF statement to make the URLs to work with encrypted organizations
if (file.isEncrypted) {
file.url += '?auth_token=' + Fliplet.User.getAuthToken();
}
data.contacts.forEach(function(entry, index) {
if (entry.data[imageColumn] && file.name.indexOf(entry.data[imageColumn]) !== -1) {
data.contacts[index].data[imageColumn] = file.url;
// Save new temporary key to mark the URL as edited - Required (No need for a column with the same name)
data.contacts[index].data['imageUrlEdited'] = true;
} else if (urlPattern.test(entry.data[imageColumn]) || base64Pattern.test(entry.data[imageColumn])) {
// Save new temporary key to mark the URL as edited - Required (No need for a column with the same name)
data.contacts[index].data['imageUrlEdited'] = true;
} else if (numberPattern.test(entry.data[imageColumn])) {
var imageId = parseInt(entry.data[imageColumn], 10);
if (imageId === file.id) {
data.contacts[index].data[imageColumn] = file.url;
// Save new temporary key to mark the URL as edited - Required (No need for a column with the same name)
data.contacts[index].data['imageUrlEdited'] = true;
}
}
});
});
// Images that weren't converted to URLs will be left as empty
data.contacts.forEach(function(entry, index) {
if (!entry.data['imageUrlEdited'] && !urlPattern.test(entry.data[imageColumn]) && !base64Pattern.test(entry.data[imageColumn])) {
data.contacts[index].data[imageColumn] = '';
}
});
return data;
});
});
Private conversations
Get the list of conversations for the current user
Use the conversations() method to get the list of conversations for the current user. This will return a promise that will resolve to the list of conversations.
const conversations = await chat.conversations();
See the Instance methods for the conversation object section below for more information on the conversation object.
Instance methods for the conversation object
The conversations() method returns a list of conversation objects. Each conversation object has the following methods and properties:
conversation.participants- Methods to manage the participants of the conversationconversation.messages- Methods to manage the messages of the conversationconversation.contacts- Methods to manage the contacts of the conversationconversation.mute()- Mute notifications for the current userconversation.unmute()- Receive notifications for the current userconversation.isMuted- Check if the current user has muted notifications for the conversation
Get the list of participants
Use the fetch() method to get the list of participants for the conversation. This will return a promise that will resolve to the list of participants.
Each participant object has the following properties:
participant.id- The Data source entry ID of the participantparticipant.data- The Data source entry data of the participant, containing the full name, email, etc.
const participants = await conversation.participants.fetch();
If you only need the list of internal chat IDs of the conversation participants, you can use the get() method instead:
const participants = conversation.participants.get();
Add new participants to the conversation
Use the add() method to add new participants to the conversation. This will return a promise that will resolve when the participants have been added. You can pass a single ID or an array of IDs.
await conversation.participants.add(123);
conversation.participants.add([
1, 2, 3 // List of Data source entry ID for the participants to add
]).then(function () {
// People have been added to the conversation
});
The list of contacts can be fetched using the chat.contacts() method:
const contacts = await chat.contacts();
Remove participants from the conversation
conversation.participants.remove([
1, 2, 3 // List of Data source entry ID for the participants to remove
]).then(function () {
// People have been removed from the conversation
});
Get the list of messages for the conversation
Use the fetch() method to get the list of messages for the conversation. This will return a promise that will resolve to the list of messages.
Each message object has the following properties:
message.id- The Data source entry ID of the messagemessage.data- The Data source entry data of the message, containing the messagebody,filesand the sender infromUserIdmessage.createdAt- The timestamp when the message was sentmessage.isReadByCurrentUser- Whether the message has been read by the current user
const messages = await conversation.messages.fetch();
To add a reference with the message to the sender’s contact, you can use the following code:
// Fetch the list of contacts for the chat
const contacts = await chat.contacts();
// Fetch the list of messages for the conversation
const messages = await conversation.messages.fetch();
// Loop through the messages and add a reference to
// the sender's contact under the `user` property
// by matching the `fromUserId` with the contact flUserId
messages.forEach(message => message.user = _.find(contacts, c => c.data.flUserId === message.data.fromUserId));
Mute notifications for a conversation for the current user
// Check if a conversation is already muted
const isMuted = conversation.isMuted;
// Mute a conversation
conversation.mute().then(function () {
// Notifications have been muted for the conversation
});
Receive notifications for a conversation for the current user
conversation.unmute().then(function () {
// Notifications have been unmuted for the conversation
});
Create a new private conversation with one or more people
Use the chat.create method to create a new private conversation between multiple people.
You do not need to list the current user’s entry ID in the list of participants, as that will be included automatically by the system.
const conversation = await chat.create({
name: 'Running team', // Conversation name
participants: [1, 2, 3] // List of Data source entry ID for the participants
});
Add metadata to a conversation
You can add metadata to a conversation by adding a metadata parameter to the chat.create method.
const conversation = await chat.create({
name: 'Running team',
participants: [1, 2, 3],
allowInvite: true,
metadata: { guid: 'running-team' }
});
The metadata can be retrieved at the definition.metadata property on the conversation object:
const guid = _.get(conversation, 'definition.metadata.guid');
As an example, you can use the metadata to store the ID of a record in a data source that is related to the conversation and use it to find the conversation later on:
const conversations = await conversations.get();
const myConversation = _.find(conversations, c => _.get(c, 'definition.metadata.guid') === 'running-team'));
Enable conversation sharing with an invite code
If you want to enable the conversation to have an invite code that can be shared with other people to join the conversation, you can use the allowInvite: true parameter as shown in the following example:
const conversation = await chat.create({
name: 'Running team', // Conversation name
participants: [1, 2, 3], // List of Data source entry ID for the participants
allowInvite: true // Allow the conversation to have an invite code
});
You can then get the invite code for the conversation using the getInviteCode() function returning a promise that will resolve to the invite code:
const inviteCode = await conversation.getInviteCode();
Finally, any user having the code can join the conversation using the chat.conversations.join() method passing the invite code as a parameter:
const conversation = await chat.conversations.join(inviteCode);
Make sure the inviteCode is securely stored to avoid issues with unauthorized access to the conversation.
Public channels
Get the list of channels available
You can get the list of public channel for a chat using the following method:
const channels = await chat.channels.get();
Create a channel
Channels can be created by simply running this simple snippet via custom code (or by running it in the console). Make sure to change the channel name with the actual words you want to use:
const channel = await chat.channels.create('My channel name');
Delete a channel
You can delete a channel by running the following snippet. Make sure to change the channel ID with the actual ID of the channel you want to delete:
// Deletes a channel by its ID
await chat.channels.delete(123);
})
Messages
Get the count of unread messages for the current user
Use the unread.count() method to get the number of unread messages for the current user. This will return a promise that will resolve to the number of unread messages.
const unreadCount = await chat.unread.count();
Get the list of unread messages for the current user
Use the unread.get() method to get the list of unread messages for the current user. This will return a promise that will resolve to the list of unread messages.
const unreadMessages = await chat.unread.get();
User verification & Security
Change the column name used for verifying user login
If the user is logged in to a data source that is different from the Chat contact list, the column name used for the user email might be different between the data sources. Use the following hook to set the email column name for the login data source.
Fliplet.Hooks.on('flChatBeforeGetUserEmail', function (options) {
// Change the column name for the user email from the login data source
options.crossLoginColumnName = 'Authorized emails';
});
Change the link to security screen
If the user isn’t logged in, the feature will attempt to redirect users to a security screen based on the configuration set in Fliplet Studio. Use the following hook to customize how the link is configured.
Fliplet.Hooks.on('flChatBeforeRedirectToLogin', function (navigate) {
// Change the page where the user is redirected to
navigate.page = 123;
});