DocumentationAPI Reference

User lifecycle

User creation

When a messaging user is initially created, a set of related objects are typically created at the same time, depending on the context. Users will often be created along with a conversation, a participant, a client, and sometimes a message or set of messages. If the user is created by the Web Widget or SDK, a device will also be created at the same time.

Automatic user creation

Most users will be created automatically by the messaging platform when needed. For example, when a user reaches out over a social messaging channel for the first time, a user must be created which will be the owner for the resulting conversation. The following is a non-exhaustive list of situations which might cause a user to be created automatically:

  • The user opens the Web Widget or mobile SDK for the first time, prompting an AI agent to reach out.
  • The user sends a message on a social messaging channel, such as WhatsApp.
  • The user follows a referral link taking them to a messaging channel.
  • The business uses the notification API to send an outbound message to a user for the first time.
  • The loginUser method is used on the Web Widget or mobile SDK to authenticate a user with an external id.
  • The user interacts with a proactive message displayed by the Web Widget or one of the SDKs.

Manual user creation

A messaging user can be explicitly created using the Create User API:

const apiInstance = new SunshineConversationsClient.UsersApi()const data = new SunshineConversationsClient.UserCreateBody()
data.externalId = "my-external-id"
await apiInstance.createUser("{appId}", data)

Users created in this way must be assigned an externalId at creation time, and will therefore always be considered as authenticated. The user will not have any conversations or clients automatically provisioned for them at creation time. To make use of this user, you can use the create client API to connect the user to a social messaging channel, or use messaging authentication to log them in on the Web Widget or mobile SDK using a signed JWT token.

Creating users manually can be a good way to pre-populate your userbase with known profile information such as the user’s name so that when they reach out to you for the first time, that information is readily available. Pre-creating users however is not required.

Creation of Support users

As mentioned in introduction to users, the messaging user model is distinct from the user model in the Support product. Creation of a user in messaging will therefore not automatically produce a user that is visible in the Agent Workspace. Creation of a corresponding user in Support will only occur if one of the messaging user's conversations generates a ticket. At the time of ticket creation, if a Support user does not already exist, one will be automatically created.

User deletion

Manual deletion

To delete a messaging user, the Delete User API can be used, referencing the user by either their id or externalId:

const apiInstance = new SunshineConversationsClient.UsersApi()
await apiInstance.deleteUser("{appId}", "{user_id}")

When a messaging user is deleted, this will cascade into deletion of all their owned objects such as conversations, participants, clients, devices, and attachments.

Scheduled deletion

To schedule automatic deletion of users after a certain period of inactivity, the deletion schedules feature offers the ability to configure user expiration rules. For messaging users, deletion schedules can be used as follows:

  1. For users that have never escalated a conversation to the Agent Workspace, a messaging user will exist with no related Support user. The bot-only conversations deletion schedule can be configured to automatically clean up these messaging users.
  2. For messaging users that have escalated at least one conversation into a ticket, a corresponding Support user will exist. This relationship will make the messaging user ineligible for consideration by the bot conversations deletion schedule. Instead, the messaging user's lifecycle will be tied to that of the Support user. If the Support user is deleted by an end-user deletion schedule, this will cascade into deletion of the related messaging user as a result.

Therefore, for full automated deletion coverage of messaging users, you should configure both a bot-only conversations deletion schedule as well as an end-user deletion schedule.

Cascading deletion

Deletion of users only cascades in one direction - from Support to messaging. When a Support user is deleted, any attached messaging identities will be removed from the user, and the messaging user will be deleted as a result. On the other hand, deletion of a messaging user will not cascade into deletion of any data in Support.

OSZAR »