Integrating Ethora / chat component Users system with your existing (legacy) system

[TarasFilatov]

This is a step by step guidance on how to ensure the User accounts are in sync when embedding Ethora into your existing / legacy system which already has its own users authentication mechanism. 

Such implementation ensures smooth experience for your end Users whereby they use Ethora features as part of your system without additional login or authentication steps required. 

 

USERS SYNC

Implementation stage

1. Register an account at Ethora.com website and create your App
2. Copy your App ID and App Secret
3. Implement in your existing backend the procedure of generating JWT tokens with your Ethora App ID and App Secret.
4. Implement in your existing backend the procedure of User Create and User Delete via Ethora (DP) API. This will ensure each User in your system automatically has an Ethora platform account. 
5. Implement in your existing backend the login procedure. User logs into your existing system, an Ethora JWT is generated by your backend with identification payload e.g. {email: "dwight.schrute@acme.com", type: "client", appId: "123"}) including User's e-mail and your Ethora App ID. This JWT will be signed with your Ethora App Secret. Your backend then passes this JWT into your frontend. Your frontend, in turn, passes it into the embedded Ethora Chat Component (or other Ethora component integrated into your system). Ethora component verifies whether your JWT is valid for your App ID (token.payload.appId). If so, Ethora component authenticates the User with the given e-mail (token.payload.email).

Kick-off preparation

1. Test the above mechanisms in both Dev/QA and Prod environments along with the general functioning of your system with Ethora component embedded. 
2. As you test creating, logging in and deleting the Users, log into your Ethora server admin panel and check that User accounts are created and deleted correctly to replicate the status in your system. 
3. Clean the Prod environment if needed.
4. Use Ethora import-users API to import all of the prior existing Users accounts into Ethora server. Note: Your User Create and User Delete procedures will take care of synchronising Users going forward, but you still need to ensure both your existing system and Ethora server have the same list of Users at the start. 

Launch

1. Launch the implementation in your system into Prod. 

 

(OPTIONAL) CHAT ROOMS SYNC 

You might want to tie Ethora-powered chat rooms to certain entities in your system.

Your system will know which chat room to display to the User depending on certain business logic of your system.

For example, chat room could be related to a certain communication between your team member and a client. This communication can be linked to a certain order, support ticket or case. Alternatively, there could be certain 'space' where a group of your users have access, and there is going to be a chat room for that space. Such as a workspace for a team collaborating on something, a game location etc. In such case you are going to have a certain unique entity ID (let's call it UUID) in your system that is going to be linked to chat rooms.

To sync Chats, similarly to syncing Users, you can add Ethora API calls into your backend like so.

1. Implement Chat Create and Chat Delete procedures. Call /chats/ API for this purpose. 

/chats/

access = [ "public", "private" ]  Default: private. Public Chats can be joined by any User who has access to the server and knows its address. Private Chats can only be joined by Users you explicitly add.

UUID = integer. Here you may store reference IDs of entities in your existing business logic. This allows you to tie Chats with your existing business logic without having to store JIDs generated by Ethora. 

When creating a new Chat, /chats/ will return the request status and if successful, JID of the newly created Chat.

Delete the Chat when your business logic doesn't need it anymore. Note: all chat history will be deleted as well through this action. 

 

2. (optional) Implement Users access management for Chats.

Unless you set your Chats to be "public", you will have to manage which Users have access to your Chats. 

This will depend on your business logic. For example, when case or communication is closed you can simply delete the Chat. However there are might be situations where the Chat is still required, but you need more Users to join the conversation or you need some Users to be removed from it.

/chat-access/

chatJid - you need to specify either JID (Ethora ID for Chats) or UUID (your ID for chat related entity) for Ethora to know which Chat room to work with

chatUuid - you need to specify either JID (Ethora ID for Chats) or UUID (your ID for chat related entity) for Ethora to know which Chat room to work with

userUuid - you need to specify either JID (Ethora ID for users) or UUID (your ID for users) for Ethora to know which User to work with

userJid - you need to specify either JID (Ethora ID for users) or UUID (your ID for users) for Ethora to know which User to work with

accessCode - specify access code to set for User for this Chat

• 0000 - no access (user is banned or removed)
• xxx1 -  read only access 
• xx1x - write access
• x1xx - admin / moderator access
• 1xxx - owner access

accessTimer - if access setting is temporary (such as a temporary ban), specify time in seconds here for this setting to expire

 

 

 

 

 

 

 

 

 

[TarasFilatov]

UPDATED

Suggested sequence (example - DXHub product integration)

 

1. When a user account is created in your system, call POST /v1/users/batch to create a mirror user account in Ethora.

Make sure to provide UUID with your own user ID or user hash from your system.

Note: password here is only for the purpose of the client app of your user to be calling Ethora API. This is not the user password from your own backend - we don't need that. Password is not stored openly in Ethora DB, but for additional security just don't send us real user passwords from your own system. This is Ethora platform password which is used, for example, in some advanced functionalities such as file attachments, user profiles etc. For simple integrations where only messaging is required, you may ignore this and simply fill the password field with some random hash. If you decide to introduce advanced features later you can use PUT method to update your user accounts with new passwords.

When a new chat room is required, do steps 2 and 3:

(In case with DXHub you want to do this when a new Source (i.e. camera stream) is created in your system.)

 

2. call POST /v1/chat to create a new chat.

Note: make sure to provide your own chatUuid which will correspond to the entity in your system that needs to be provided with the chat room - in DXHub project this would be your Source ID / hash.

 

3. Add all users to the chat room by calling POST /v1/chat/users-access with your users UUID and also the chat room UUID that you need to set.

(in DXHub this would be all users belonging to Organization whose Source this is)

 

That's it!

This should be enough for a demo PoC integration.

Once users are created in your system, there will be a mirror account in Ethora system and once a chat room is required, it will be created and users added. 

In frontend now, chat component will receive the user UUID and chat UUID from your backend and will automatically log the user into the corresponding chat without any extra login steps required. The chat will simply display and work, without the end user knowing anything about Ethora platform.

For proper Production-ready integration you also need to integrate the deletion of users, chat rooms and removal users access from the chats according to your business logic. You can implement this similarly following our Swagger documentation https://api.ethoradev.com/api-docs/ as soon as your PoC is validated.