Build a Core SDK App for iOS

The Core SDK allows you to call all the necessary In-App Messaging APIs directly from your app. With the Core SDK, you’re in full control over the entire user experience—you tell the API when to send a message and the API tells you when a message is received.

This article applies to the following implementations:

UI SDK	Core SDK
	✅

If you want to use our ready-made user interface and user experience, use the UI SDK instead.

Import the framework wherever you’re using the SDK.

Create a Configuration instance. To create a configuration instance, you can point to the config file you previously downloaded from your org, or you can manually add the values from within this config file.

Once you've added the config.json file to your project, you can reference it from the code.

To learn how to download the config file from your org, see Configure a Messaging for In-App Deployment in Salesforce Help. This file contains the Service API URL, the org ID, and the API name for the deployment. For example:

{
  "OrganizationId": "00ZZZ0000000Zzz",
  "DeveloperName": "MyMessagingForInAppDeployment",
  "Url": "https://zzzz.my.api.url.salesforce-scrt.com"
}

If you don't want to use the config.json file in your project, you can configure the SDK manually using the Service API URL, the org ID, and the API name for the deployment.

The CoreFactory class lets you create a CoreClient object.

To receive messages and events, call CoreClient.start().

The CoreClient object lets you create a ConversationClient object to start a conversation.

This example creates a random UUID for the conversation ID. However, if you want this conversation to persist even after the app is restarted, be sure to use the same conversation ID. Also, if you want to see this same conversation across multiple devices, in addition to using the same conversation ID, turn on user verification, which is described in the Enhance the Experience section.

Don't use user IDs or other IDs as the ConversationID. Conversation IDs establish a permanent link with a user and are only available to the user who created it. Using a different existing ID instead of a unique ID can result in access issues or errors while developing or testing your Messaging for In-app and Web (MIAW) integration. To pass existing IDs required for your flow, use the Pre-chat feature.

In order to get the pre-chat fields before a conversation, call the retrieveRemoteConfiguration method from your CoreClient object. This method passes back an SMIRemoteConfigurationCompletion completion block that contains the array of pre-chat fields.

Each pre-chat field has the properties necessary for you to build your pre-chat form. After you present a pre-chat form to the user, fill in the value field for each pre-chat object. Then submit the pre-chat fields using the submit(remoteConfig: ) method on the ConversationClient object.

IMPORTANT: The submit(preChatFields: ) method is deprecated in SDK version 1.4. If you want to use new features added in version 1.4 and later, submit pre-chat fields using the submit(remoteConfig: ) method.

To learn about hidden pre-chat fields, see Hidden Pre-Chat for iOS.

Send a message with the ConversationClient instance.

If you see the Exception Failed (417) error on sending a message, it’s because you set the Pre-Chat Display Frequency to Every Session in the Pre-Chat Settings and a new session is being created. To fix this, call the submitRemoteConfiguration method on the ConversationClient object with your pre-chat values.

To listen for events (such as new incoming messages), implement a delegate.

Implement the CoreDelegate protocol to listen for general messaging events or implement the ConversationClientDelegate protocol to listen for messaging events related to a particular conversation. The conversation delegate (ConversationClientDelegate) gets all events for a specific conversation. The core delegate (CoreDelegate) gets events for every conversation. The core delegate also returns network connectivity events (didChangeNetworkStatus) and general error messages (didError).

When you receive conversation entries from various event methods, they’re delivered as ConversationEntry objects. In addition to the payload, you can inspect the format (for example, RichLink) and the type (for example, Message) when deciding how to process the message.

Use the addDelegate method on the CoreClient instance to add a core delegate. Use the addDelegate method on the ConversationClient instance to add a conversation client delegate.

The Participant protocol has a role field of type ParticipantRole. Participant maps to the sender field of the ConversationEntry protocol.

Participant Role Type	Description
`ParticipantRoleSystem`	Set for `ParticipantChangedOperation`. The `participant` field on the `ParticipantChangedOperation` protocol represents the participant whose role is being updated.
`ParticipantRoleUser`	Set for all conversation entries sent by a user.
`ParticipantRoleAgent`	Set for all conversation entries sent by an agent.
`ParticipantRoleChatbot`	Set for all conversation entries sent by a chatbot.
`ParticipantRoleRouter`	Set for `ParticipantChangedOperation`. This role is ignored by the SDK UI experience.
`ParticipantRoleSupervisor`	Set for `ParticipantChangedOperation` after a supervisor on a Salesforce org joins a conversation after the agent raises a flag seeking their input. This role is ignored by the SDK UI experience.

You can enhance your users' experience by adding push notifications, passing information to Salesforce about a verified user, sending hidden pre-chat fields, adjusting chat button visibility based on business hours, and more.

For enhanced features, see Enhance the Experience for iOS.

For more details about the Core SDK, see the iOS Reference Documentation.

For an example app, see the Core SDK example in GitHub.