Embedded Service Chat SDK for iOS Developer Guide
jConfigure a Chat Session
When you start a chat session, you specify an SCSChatConfiguration object as one of the arguments. This object contains all the configuration settings necessary for Chat to start a session. To create an SCSChatConfiguration object, you specify information about your org and deployment.
In Swift:
1let config = SCSChatConfiguration(liveAgentPod: "TO_DO_POD_NAME",
2 // e.g. "d.gla5.gus.salesforce.com"
3 orgId: "TO_DO_ORG_ID",
4 // e.g. "00DB00000003Rxz"
5 deploymentId: "TO_DO_DEPLOYMENT_ID",
6 // e.g. "573B00000005KXz"
7 buttonId: "TO_DO_BUTTON_ID")
8 // e.g. "575C00000004h3m"In Objective-C:
1SCSChatConfiguration *config =
2 [[SCSChatConfiguration alloc] initWithLiveAgentPod:@"TO_DO_POD_NAME"
3 // e.g. "d.gla5.gus.salesforce.com"
4 orgId:@"TO_DO_ORG_ID"
5 // e.g. "00DB00000003Rxz"
6 deploymentId:@"TO_DO_DEPLOYMENT_ID"
7 // e.g. "573B00000005KXz"
8 buttonId:@"TO_DO_BUTTON_ID"];
9 // e.g. "575C00000004h3m"However, there are other options you can set using SCSChatConfiguration at configuration time.
The following features are available for configuration:
| Property Name | Description | Type & Default Value |
|---|---|---|
| allowMinimization | Indicates whether the user is allowed to minimize the chat session view. | Bool: true/YES |
| allowURLPreview | Indicates whether the user is shown URL previews when the agent types a URL in the chat feed. | Bool: true/YES |
| defaultToMinimized | Indicates whether the chat session starts out as a minimized thumbnail view. | Bool: true/YES |
| Property Name | Description | Type & Default Value |
|---|---|---|
| allowBackgroundExecution | Indicates whether to allow extended background execution to support active chat sessions. When true, active chat sessions can remain in the background for more than three minutes. See allowBackgroundNotifications for related functionality. | Bool: true/YES |
| allowBackgroundNotifications | Indicates whether the session posts local notifications based on chat activity. Requires that allowBackgroundExecution is also set to true. To learn more, see Notifications for Chat Activity. | Bool: true/YES |
| Property Name | Description | Type & Default Value |
|---|---|---|
| prechatEntities | Pre-chat fields are always sent to the agent at the start of the session. To fill in fields of a particular record, instantiate an SCSPrechatEntity for each Salesforce object (for example, Case or Contact) and an SCSPrechatEntityField for each field (for example, Subject or LastName). To learn more, see Create or Update Salesforce Records from a Chat Session. | SCSPrechatEntity array: nil |
| prechatFields | You can specify both optional and required fields shown to the user before a chat session starts. You can also directly pass data to an agent without requiring any user input. To create pre-chat fields, add SCSPrechatObject instances to the prechatFields property on the SCSChatConfiguration object. To learn more, see Show Pre-Chat Fields to User. | SCSPrechatObject array: nil |
| Property Name | Description | Type & Default Value |
|---|---|---|
| eventList | Adds a custom path that displays a custom tile and performs a custom action within your app. To learn more, see Handle Custom URLs in Chat. | SCSAppEventList |
| queueStyle | Determines the style of the queue: queue position number (.position), estimated wait time (.estimatedWaitTime), or no queue information (.none). You can subscribe to queue position events using session(didUpdateQueuePosition:estimatedWaitTime:) on SCSChatSessionDelegate. To understand the algorithm used for the estimated wait time, see the estimated wait time documentation in the Chat REST API Developer Guide. | SCSChatConfigurationQueueStyle: .position |
| remoteLoggingEnabled | Indicates whether session logs are sent for collection. (Logs sent remotely don't collect personal information. Unique IDs are created for tying logs to sessions and those IDs can't be correlated back to specific users.) | Bool: true/YES |
| visitorName | Name of the chat visitor. This value is used by the Service Cloud console and displayed to the agent. | String: "Visitor" |
When using the estimated wait time, the wait time is shown to the user in minutes. However, you can set the minimum (minimumEstimatedWaitTime) and maximum () wait time values. If the wait time exceeds the maximum value, a generic message appears, which you can customize (using the customizable chat strings in the ServiceCloud.Chat.Status.EstimatedWait namespace).
When using the queue position number, the queue position is 0 if the agent capacity is greater than or equal to the number of customer requests. Otherwise, the position value represents how far the customer is from getting served by an agent.
1q = max(n - c, 0)- q is the queue position
- n is the position of the customer compared to all waiting customers
- c is the total capacity of all agents
For example, if the total capacity is 10, the first 10 waiting visitors have a position of 0, the 11th has a position of 1, the 12th has a position of 2, and so on.
Once you've fully configured the SCSChatConfiguration object, you can start the session using the startSession method.
Example
The following example configures a session with one pre-chat field and a visitor name "Jane Doe".
In Swift:
1let config = SCSChatConfiguration(liveAgentPod: "YOUR_POD_NAME",
2 orgId: "YOUR_ORG_ID",
3 deploymentId: "YOUR_DEPLOYMENT_ID",
4 buttonId: "YOUR_BUTTON_ID")
5
6// Set the visitor name
7config?.visitorName = "Jane Doe"
8
9// Change from queue position to estimated wait time
10config?.queueStyle = .estimatedWaitTime
11
12// Add a required email field (with an email keyboard and no auto-correction)
13let emailField = SCSPrechatTextInputObject(label: "Email")
14emailField?.isRequired = true
15emailField?.keyboardType = .emailAddress
16emailField?.autocorrectionType = .no
17config?.prechatFields.append(emailField!)In Objective-C:
1SCSChatConfiguration *config =
2 [[SCSChatConfiguration alloc] initWithLiveAgentPod:@"YOUR_POD_NAME"
3 orgId:@"YOUR_ORG_ID"
4 deploymentId:@"YOUR_DEPLOYMENT_ID"
5 buttonId:@"YOUR_BUTTON_ID"];
6
7// Set the visitor name
8config.visitorName = @"Jane Doe";
9
10// Change from queue position to estimated wait time
11config.queueStyle = SCSChatConfigurationQueueStyleEstimatedWaitTime;
12
13// Add a required email field (with an email keyboard and no auto-correction)
14SCSPrechatTextInputObject* emailField = [[SCSPrechatTextInputObject alloc]
15 initWithLabel:@"Email"];
16emailField.required = YES;
17emailField.keyboardType = UIKeyboardTypeEmailAddress;
18emailField.autocorrectionType = UITextAutocorrectionTypeNo;
19[config.prechatFields addObject:emailField];