> ## Documentation Index
> Fetch the complete documentation index at: https://learn.social.plus/llms.txt
> Use this file to discover all available pages before exploring further.

# Heartbeat Sync

> Start and stop SDK presence heartbeats for the current user or a live room viewer.

A heartbeat tells social.plus that the current user is still active. There are two heartbeat surfaces:

* **Current user heartbeat** marks the logged-in user online for user and channel presence. It is available on iOS and Android.
* **Room heartbeat** marks the current user as present in a live room. It is available on iOS, Android, and TypeScript.

<Info>
  Heartbeat intervals are controlled by server-side presence settings. The SDK sends the first heartbeat immediately, then continues on the configured cadence.
</Info>

## Platform Surface

| Heartbeat              | TypeScript                                      | iOS                                    | Android                                                      | Flutter       |
| ---------------------- | ----------------------------------------------- | -------------------------------------- | ------------------------------------------------------------ | ------------- |
| Current user heartbeat | Not available                                   | `client.presence.startHeartbeat()`     | `AmityCoreClient.presence().startHeartbeat()`                | Not available |
| Room heartbeat         | `RoomPresenceRepository.startHeartbeat(roomId)` | `AmityRoomPresenceRepository(roomId:)` | `AmityCoreClient.newRoomPresenceRepository().roomId(roomId)` | Not available |

## Parameters

| Operation                                               | Platform     | Parameter | Required | Description                                                   |
| ------------------------------------------------------- | ------------ | --------- | -------- | ------------------------------------------------------------- |
| `presence.enable` / `presence().enable`                 | iOS, Android | None      | No       | Enables user presence for the current user.                   |
| `presence.isEnabled` / `presence().isEnabled`           | iOS, Android | None      | No       | Checks whether user presence is enabled for the current user. |
| `presence.startHeartbeat` / `presence().startHeartbeat` | iOS, Android | None      | No       | Starts the current user's network presence heartbeat.         |
| `presence.stopHeartbeat` / `presence().stopHeartbeat`   | iOS, Android | None      | No       | Stops the current user's network presence heartbeat.          |
| `RoomPresenceRepository.startHeartbeat`                 | TypeScript   | `roomId`  | Yes      | Room ID where the current user should be counted as present.  |
| `AmityRoomPresenceRepository(roomId:)`                  | iOS          | `roomId`  | Yes      | Room ID used to create the room presence repository.          |
| `newRoomPresenceRepository().roomId(roomId)`            | Android      | `roomId`  | Yes      | Room ID used to create the room presence repository.          |

## Start the Current User Heartbeat

Use this when your app wants the current user to appear online in user and channel presence.

<CodeGroup>
  ```swift iOS theme={null}
  let isEnabled = try await client.presence.isEnabled()
  if !isEnabled {
      try await client.presence.enable()
  }

  try await client.presence.startHeartbeat()

  // Call when the user should no longer appear online.
  client.presence.stopHeartbeat()
  ```

  ```kotlin Android theme={null}
  AmityCoreClient.presence().isEnabled()
      .flatMapCompletable { isEnabled ->
          val enableIfNeeded = if (isEnabled) {
              Completable.complete()
          } else {
              AmityCoreClient.presence().enable()
          }

          enableIfNeeded.andThen(AmityCoreClient.presence().startHeartbeat())
      }
      .subscribeOn(Schedulers.io())
      .observeOn(AndroidSchedulers.mainThread())
      .subscribe({
          showSuccessMessage("Presence heartbeat started")
      }, { error ->
          showErrorMessage(error = error)
      })

  // Call when the user should no longer appear online.
  AmityCoreClient.presence().stopHeartbeat()
  ```
</CodeGroup>

## Start a Room Heartbeat

Use room heartbeat only while the current user is watching or participating in a live room.

<CodeGroup>
  ```swift iOS theme={null}
  let roomPresence = AmityRoomPresenceRepository(roomId: roomId)

  try await roomPresence.startHeartbeat()

  // Call when the viewer leaves the room.
  roomPresence.stopHeartbeat()
  ```

  ```kotlin Android theme={null}
  val roomPresence = AmityCoreClient.newRoomPresenceRepository().roomId(roomId)

  roomPresence.startHeartbeat()
      .subscribeOn(Schedulers.io())
      .observeOn(AndroidSchedulers.mainThread())
      .subscribe({
          showSuccessMessage("Room heartbeat started")
      }, { error ->
          showErrorMessage(error = error)
      })

  // Call when the viewer leaves the room.
  roomPresence.stopHeartbeat()
  ```

  ```typescript TypeScript theme={null}
  import { RoomPresenceRepository } from '@amityco/ts-sdk';

  RoomPresenceRepository.startHeartbeat(roomId);

  // Call when the viewer leaves the room.
  RoomPresenceRepository.stopHeartbeat(roomId);
  ```
</CodeGroup>

## Lifecycle Guidance

<AccordionGroup>
  <Accordion title="Start heartbeat only while the surface is active" icon="play">
    Start the current user heartbeat after login when the app wants the user to appear online. Start room heartbeat only while the room screen is visible and the user should count as a viewer.
  </Accordion>

  <Accordion title="Stop heartbeat during teardown" icon="square">
    Stop heartbeat when the user logs out, leaves the room, dismisses the screen, or your view model is deallocated. For mobile apps, also stop or pause room heartbeat when the room screen backgrounds.
  </Accordion>

  <Accordion title="Handle disabled presence" icon="triangle-alert">
    If presence is disabled for the network, heartbeat start calls can fail. Treat that as a configuration error and hide online-state UI instead of retrying forever.
  </Accordion>
</AccordionGroup>

## Related Topics

<CardGroup cols={2}>
  <Card title="User Presence" icon="user" href="/social-plus-sdk/core-concepts/realtime-communication/presence-state/user-presence">
    Read and sync user online state after the current user heartbeat is active.
  </Card>

  <Card title="Room Presence" icon="radio" href="/social-plus-sdk/core-concepts/realtime-communication/presence-state/room-presence">
    Read live room viewer counts and online room users.
  </Card>
</CardGroup>