Configure WebSockets

A WebSocket is a bidirectional TCP connection between a client and server that’s kept open until the app closes it. WebSockets can be configured to work with our authentication features and products like Agentforce Speech Foundation.

WebSockets and HTTP

With a WebSocket, an app uses HTTP to make an initial connection. The connection then gets upgraded to a TCP socket-based connection.

On Android, Mobile SDK uses okhttp3.OkHttpClient.newWebSocket(okhttp3.Request, okhttp3.WebSocketListener) to return instances of okhttp3.WebSocket. See Square’s documentation: https://square.github.io/okhttp/.

On iOS, Mobile SDK uses URLSessionWebSocketTask, available through Apple’s URLSession API. See Apple’s documentation: https://developer.apple.com/documentation/foundation/urlsessionwebsockettask.

Set Up a WebSocket Connection

To create a WebSocket connection, use one of these RestClient methods. The methods return a ready-to-use WebSocket client instance that handles token injection and retry logic internally.

Android

1val websocket = restClient.newWebSocket(Request, WebSocketListener)

iOS

On iOS, you have the option to create a connection from a URLRequest or a RestRequest.

1let websocket = try await restClient.newWebSocket(from: urlRequest)
2
3let websocket = try await restClient.newWebSocket(from: restRequest)

Send Data with WebSockets

To send data to a Salesforce API endpoint, use the send method. Internally, send automatically refreshes the token if authentication fails and retries once with a new token before surfacing an error.

Android

1websocket.send(ByteString)
2
3websocket.send(String)

iOS

1try await websocket.send(.data(yourAudioData))
2
3try await websocket.send(.string("Your text message"))

Receive Data with WebSockets

WebSockets receive data by listening for incoming messages. Our listen methods:

Automatically resume the WebSocket task
Continuously listen for new messages
Refresh the token and reestablish the connection once, if needed

Android

To receive data on Android, use the WebSocketListener adapter object.

1WebSocketListener() {
2  override fun onMessage(webSocket: WebSocket, text: String) {
3    super.onMessage(webSocket, text)
4
5    // Handle incoming text message
6  }
7
8  override fun onMessage(webSocket: WebSocket, bytes: ByteString) {
9    super.onMessage(webSocket, bytes)
10
11    // Handle incoming binary message
12  }
13
14  override fun onFailure(
15    webSocket: WebSocket,
16    t: Throwable, response: Response?
17  ) {
18    super.onFailure(webSocket, t, response)
19    // Handle error
20  }
21}

iOS

To receive data on iOS, use the listen(onReceive:) method.

1client.listen { result in
2    switch result {
3    case .success(let message):
4        // Handle incoming message (text or binary)
5    case .failure(let error):
6        // Handle error
7    }
8}

We've Moved

Welcome to the new home of the Mobile SDK Developer Guide! For now, the Japanese guide can be found in PDF form.