Merging Users

When Smooch determines that two separate appUsers are actually the same person, the two users may be merged together in order to provide a more unified view of the user, and to allow the business to keep track of users more easily as they move between different channels. The purpose of this section is to describe when and how merges occur, and how your software should react to them.

When merges occur

Merges can be triggered in two ways:

Merging because of a channel transfer

When a user confirms their identity on a messaging channel by completing a channel transfer flow, it is possible that the confirmed identity already matches another user in your Smooch app. If two anonymous appUsers are confirmed to be in possession of the same messaging channel account or phone number, then those two users will be merged into one.

A channel transfer can be initiated either by the business via the link app user to channel API, or by the user choosing to continue their conversation on a different channel.

Example business-initiated flow

  1. A user named Alice sends a message to your business’ configured Twilio phone number, creating an appUser record in Smooch associated to that phone number.
  2. Later on, Alice starts a conversation with your business through your iOS application. There are currently two user records in Smooch, Alice on SMS (User X), and Alice on Twilio (User Y).
  3. During Alice’s conversation on iOS (User Y), she confirms to the business that she owns the phone number associated to User X, and would like to receive further updates over SMS.
  4. The business uses the link app user to channel API to attach the phone number to User Y.
  5. Smooch determines that both User X and User Y share the same phone number, and decides that they should be merged into one.
  6. The users are merged together, and the conversation history is now shared between both iOS and SMS. Alice can choose to reply from either channel, and her replies will be routed to the same conversation.

Example user-initiated flow

  1. A user named Alice is using the Web Messenger on your business’ website to chat with a support agent.
  2. Alice does not want to remain at her computer for the duration of the support session, and chooses to continue her conversation on Facebook Messenger.
  3. Alice is now linked to the Messenger channel, and can send replies from either her browser session, or Facebook Messenger, and her replies will be routed to the same conversation (Conversation X).
  4. Later on, Alice returns to the business’ website from a different computer, and starts a new conversation (Conversation Y) with a support agent.
  5. Once again, Alice chooses to continue her conversation on Facebook Messenger.
  6. The Facebook Messenger account that she used in step 5 is the same account as was used in step 2, and therefore Smooch determines that Conversation X and Conversation Y are referring to the same person, and therefore decides that they should be merged into one.
  7. The users are merged together and Alice now sees her full conversation history which is shared between both browsers, as well as Alice’s Facebook Messenger account. Alice can choose to reply from either channel, and her replies will be routed to the same conversation.

Merging because of a login event

When an anonymous user on the Web or Mobile SDKs is identified using the login method, and the identified user already exists in Smooch (if they were previously active on a different device, for example) a merge will occur between the anonymous user and the identified user. This allows a user to start a conversation with your business anonymously before they log in (for example, while browsing your business’ website). After logging in, the user will still see the conversation they had before logging in and be able to seamlessly continue as a logged in user.

Example flow on Web Messenger

  1. A user named Alice visits your business’ website, and logs in using her existing account in your system.
  2. As a result of the authentication, the website calls the login method to identify the user with a userId and JWT.
  3. Alice starts a conversation with your business using the Web Messenger, as her identified user (User X).
  4. Later on, Alice visits your website from a different browser, but does not choose to log in.
  5. Alice uses the Web Messenger to start a new anonymous conversation with your business, creating a new anonymous user (User Y).
  6. While conversing with a support agent, Alice decides to log in to your website to view her account settings.
  7. Your website calls the login method, and supplies the same userId as in step 2.
  8. User X and User Y are now confirmed to be the same identified user, and Smooch merges the two users into one.
  9. The users and conversations are merged together, and Alice is able to seamlessly continue her conversation using the Web Messenger, and is also able to view her previous conversation history by scrolling up in the messaging window.

How merges work

Before a merge can occur between users, Smooch must first elect a “surviving” user, which is the user that will remain once the merge is complete. The second user becomes the “discarded” user, and will eventually be deleted at the end of the merge. In the case of a merge initiated via channel transfer, the user that initiated the transfer becomes the surviving user. In the case of a merge initiated via a login event, the surviving user is the user that was created in Smooch first.

Once a surviving user is elected, Smooch starts the merge flow for the users and their associated conversations.

  1. The discarded user’s structured fields are transferred to the surviving user.

    • In the case of a conflict, the surviving user retains its original value.
    • In the case of the signedUpAt field, the earlier date is used.
  2. The discarded user’s custom properties are merged with the surviving user’s.

    • In the case of a conflict, the surviving user retains its original value.
    • If the resulting size of the merged properties is greater than the maximum allowed value of 4KB, then properties are discarded one by one until the object is within the size limit.
  3. If an anonymous user is being merged with an identified user, the userId of the identified user is assigned to the surviving user.
  4. The clients arrays of both users are merged, filtering for duplicates. The resulting user will contain all the clients of both users.
  5. The conversation histories of both users are merged, sorting the resulting conversation by message timestamp.
  6. An appUser:merge webhook is fired to indicate the surviving user, discarded user, and any custom properties that were discarded as part of step 3.

Handling merge events as a business

When a merge occurs, Smooch will send an appUser:merge event to any subscribed webhooks, to inform the business that a merge occurred. When you receive such an event, you should update any records in your own system that reference the discarded user to instead reference the surviving user. If any record merging is required on your end, you should also perform that in response to this event.

In the event where user properties were discarded as a result of a merge (in the case where the properties would have exceeded the size limit of 4KB), you may also want to handle this event in your system. The discarded properties and their values can be found in the discardedProperties field of the webhook payload.