> ## Documentation Index > Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt > Use this file to discover all available pages before exploring further. # Update Live Activity > Update or terminate running iOS Live Activities using OneSignal’s Live Activities API. This endpoint enables real-time content updates and activity termination, ensuring dynamic, context-aware user experiences. ## Overview Update or terminate running iOS Live Activities using our REST API. This endpoint enables real-time content updates and activity termination, ensuring dynamic, context-aware user experiences. Before using this API, ensure your app is properly configured by following the [Live Activities developer setup](/docs/en/live-activities-developer-setup). ## How to Use this API 1. Select the Live Activity to update by specifying its `activity_id` in the URL. This is set when using the: * [Start Live Activity API](/reference/start-live-activity) * [Triggering it in-app](/docs/en/live-activities-developer-setup). * [`LiveActivities.enter` SDK method](/docs/en/mobile-sdk-reference#enter) 2. Update the state of the Live Activity by setting the `event_updates` parameter to a JSON object that matches the structure of the `ActivityAttributes.ContentState` struct defined in your Live Activity widget extension. 3. When ready to terminate the Live Activity: * Set the `event` parameter to `end` * Include a `dismissal_date` if you want the Live Activity to be dismissed in less than 4 hours. * Set the `dismissal_date` to a time in the past to dismiss the Live Activity immediately. User must have clicked "Allow" for the Live Activity to be removed programmatically. Once a Live Activity `activity_id` is ended, you cannot update it. This includes changing the `dismissal_date` or `event` parameter. If the Live Activity is not being dismissed immediately, it is either because: * The `activity_id` has already been ended. * The user has not clicked "Allow" for the Live Activity to be removed programmatically. *** ## OpenAPI ````yaml POST /apps/{app_id}/live_activities/{activity_id}/notifications openapi: 3.1.0 info: title: api.onesignal.com version: '11.6' servers: - url: https://api.onesignal.com security: - {} paths: /apps/{app_id}/live_activities/{activity_id}/notifications: post: summary: Update Live Activity description: >- Update or terminate running iOS Live Activities using OneSignal’s Live Activities API. This endpoint enables real-time content updates and activity termination, ensuring dynamic, context-aware user experiences. operationId: update-live-activity-api parameters: - name: app_id in: path description: >- Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids). schema: type: string required: true - name: activity_id in: path description: >- An identifier you set when starting the Live Activity to uniquely identify it and associated devices with the event. This value is crucial for maintaining a consistent reference to the Live Activity across different devices and sessions. Consider using a UUID, CUID, or NanoID for this parameter. schema: type: string required: true - name: Content-Type in: header required: true schema: type: string default: application/json - name: Authorization in: header description: >- Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids). required: true schema: type: string default: Key YOUR_APP_API_KEY requestBody: content: application/json: schema: type: object required: - event - event_updates - name properties: event: type: string description: >- The action to perform on the Live Activity. Options:`update` - Updates the content of an existing Live Activity without ending it. `end` — Ends the Live Activity and removes it from the user's view. See Apple's developer docs on [Starting and updating Live Activities](https://developer.apple.com/documentation/activitykit/starting-and-updating-live-activities-with-activitykit-push-notifications). enum: - update - end event_updates: type: object description: >- The content used to update a running Live Activity. The object must conform to the `ContentState` interface defined within your app's Live Activity. See [Live Activities developer setup](/docs/live-activities-developer-setup). format: json name: type: string description: >- An internal name you set to help organize and track messages. Not shown to recipients. Maximum 128 characters. contents: type: object description: >- The push message body with [language-specific values](/docs/en/multi-language-messaging#supported-languages). required: - en properties: en: type: string description: >- The required message language type. See [Supported Languages](/docs/en/multi-language-messaging#supported-languages). stale_date: type: integer description: >- A Unix timestamp (in seconds) that indicates the date the Live Activity is considered outdated. Once this time is reached, the system updates the Live Activity to [`ActivityState.stale`](https://developer.apple.com/documentation/activitykit/activitystate/stale) at which point you can update the Live Activity to indicate that its content is out of date. format: int32 dismissal_date: type: integer description: >- A Unix timestamp (in seconds) indicating when the Live Activity should be removed from user's device. Use with the `end` event. If not set, the Live Activity will be dismissed automatically after 4 hours. To dismiss the Live Activity immediately, the user must have allowed the Live Activity first. Then you can set a date that’s in the past — for example, `1663177260`. Alternatively, provide a date within a four-hour window to set a custom dismissal date before the default 4 hour period. See [Apple's documentation](https://developer.apple.com/documentation/activitykit/starting-and-updating-live-activities-with-activitykit-push-notifications#End-the-Live-Activity-with-a-custom-dismissal-date) for more. format: int32 priority: type: integer description: >- Set the priority based on the urgency of the message. `10` - High priority. `5` - Normal priority. Apple allows a certain budget of High priority updates per hour. Exceeding the budget may throttle your messages. Apple recommends choosing a mix of priority `5` and `10` to prevent throttling. If your app needs more frequent updates, use `NSSupportsLiveActivitiesFrequentUpdates` entry as directed in [Apple's Developer Docs](https://developer.apple.com/documentation/activitykit/starting-and-updating-live-activities-with-activitykit-push-notifications#Determine-the-update-frequency). format: int32 enum: - 5 - 10 ios_sound: type: string description: >- The name of a sound file in your app bundle to play when the Live Activity receives an update. If excluded, the system plays the default notification sound. Using the value `"nil"` will silence the sound. ios_relevance_score: type: number description: >- A value between `0` and `1`. If you start more than one Live Activity for your app, the Live Activity with the highest relevance score appears in the Dynamic Island. If Live Activities have the same relevance score, the system displays the Live Activity that started first. Additionally, the Relevance Score determines the order of your Live Activities on the Lock Screen. format: double responses: '201': description: '201' content: application/json: schema: type: object properties: id: type: string description: The ID of the Live Activity update request. '400': description: '400' content: application/json: schema: $ref: '#/components/schemas/BasicErrorResponse' example: errors: - >- Reason for the message not being started. Usually due to the activity type not being found in the app. '404': description: >- Activity type was not found in the app, or the Authorization key cannot reach this app. content: application/json: schema: $ref: '#/components/schemas/BasicErrorResponse' example: errors: - activity_id not found in this app '429': description: >- Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying. headers: Retry-After: description: >- Number of seconds to wait before retrying the request. Always emitted on 429 responses. schema: type: integer minimum: 0 content: application/json: schema: $ref: '#/components/schemas/BasicErrorResponse' example: errors: - API rate limit exceeded '503': description: >- Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes. headers: Retry-After: description: >- Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream. schema: type: integer minimum: 0 content: application/json: schema: $ref: '#/components/schemas/BasicErrorResponse' example: errors: - Service temporarily unavailable deprecated: false x-codeSamples: - lang: typescript label: Node.js SDK source: >- import Onesignal from '@onesignal/node-onesignal'; const configuration = Onesignal.createConfiguration({ restApiKey: 'YOUR_REST_API_KEY', }); const apiInstance = new Onesignal.DefaultApi(configuration); // string | The OneSignal App ID for your app. Available in Keys & IDs. const appId: string = "00000000-0000-0000-0000-000000000000"; // string | Live Activity record ID const activityId: string = "12345"; // UpdateLiveActivityRequest const updateLiveActivityRequest: Onesignal.UpdateLiveActivityRequest = { name: "name_example", event: "update", event_updates: {}, contents: { en: "en_example", ar: "ar_example", bs: "bs_example", bg: "bg_example", ca: "ca_example", zh_hans: "zh_hans_example", zh_hant: "zh_hant_example", zh: "zh_example", hr: "hr_example", cs: "cs_example", da: "da_example", nl: "nl_example", et: "et_example", fi: "fi_example", fr: "fr_example", ka: "ka_example", de: "de_example", el: "el_example", hi: "hi_example", he: "he_example", hu: "hu_example", id: "id_example", it: "it_example", ja: "ja_example", ko: "ko_example", lv: "lv_example", lt: "lt_example", ms: "ms_example", nb: "nb_example", pl: "pl_example", fa: "fa_example", pt: "pt_example", pa: "pa_example", ro: "ro_example", ru: "ru_example", sr: "sr_example", sk: "sk_example", es: "es_example", sv: "sv_example", th: "th_example", tr: "tr_example", uk: "uk_example", vi: "vi_example", }, headings: { en: "en_example", ar: "ar_example", bs: "bs_example", bg: "bg_example", ca: "ca_example", zh_hans: "zh_hans_example", zh_hant: "zh_hant_example", zh: "zh_example", hr: "hr_example", cs: "cs_example", da: "da_example", nl: "nl_example", et: "et_example", fi: "fi_example", fr: "fr_example", ka: "ka_example", de: "de_example", el: "el_example", hi: "hi_example", he: "he_example", hu: "hu_example", id: "id_example", it: "it_example", ja: "ja_example", ko: "ko_example", lv: "lv_example", lt: "lt_example", ms: "ms_example", nb: "nb_example", pl: "pl_example", fa: "fa_example", pt: "pt_example", pa: "pa_example", ro: "ro_example", ru: "ru_example", sr: "sr_example", sk: "sk_example", es: "es_example", sv: "sv_example", th: "th_example", tr: "tr_example", uk: "uk_example", vi: "vi_example", }, sound: "sound_example", stale_date: 1, dismissal_date: 1, priority: 1, }; try { const response = await apiInstance.updateLiveActivity(appId, activityId, updateLiveActivityRequest); console.log(response); } catch (e) { if (e instanceof Onesignal.ApiException) { // `e.errorMessages` flattens any error-envelope shape to a `string[]`; // the raw parsed body remains on `e.body`. console.error("updateLiveActivity failed: HTTP " + e.code, e.errorMessages); } else { throw e; } } - lang: python label: Python SDK source: >- import onesignal from onesignal.api import default_api from onesignal.models import * from pprint import pprint # See configuration.py for a list of all supported configuration parameters. # Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY. # We recommend adding both of them in the configuration page so that you will not need to figure it out yourself. configuration = onesignal.Configuration( rest_api_key = "YOUR_REST_API_KEY", # App REST API key required for most endpoints organization_api_key = "YOUR_ORGANIZATION_API_KEY" # Organization key is only required for creating new apps and other top-level endpoints ) # Enter a context with an instance of the API client with onesignal.ApiClient(configuration) as api_client: # Create an instance of the API class api_instance = default_api.DefaultApi(api_client) app_id = "00000000-0000-0000-0000-000000000000" # The OneSignal App ID for your app. Available in Keys & IDs. activity_id = "12345" # Live Activity record ID update_live_activity_request = UpdateLiveActivityRequest( name="name_example", event="update", event_updates={}, contents=LanguageStringMap( en="en_example", ar="ar_example", bs="bs_example", bg="bg_example", ca="ca_example", zh_hans="zh_hans_example", zh_hant="zh_hant_example", zh="zh_example", hr="hr_example", cs="cs_example", da="da_example", nl="nl_example", et="et_example", fi="fi_example", fr="fr_example", ka="ka_example", de="de_example", el="el_example", hi="hi_example", he="he_example", hu="hu_example", id="id_example", it="it_example", ja="ja_example", ko="ko_example", lv="lv_example", lt="lt_example", ms="ms_example", nb="nb_example", pl="pl_example", fa="fa_example", pt="pt_example", pa="pa_example", ro="ro_example", ru="ru_example", sr="sr_example", sk="sk_example", es="es_example", sv="sv_example", th="th_example", tr="tr_example", uk="uk_example", vi="vi_example", ), headings=LanguageStringMap( en="en_example", ar="ar_example", bs="bs_example", bg="bg_example", ca="ca_example", zh_hans="zh_hans_example", zh_hant="zh_hant_example", zh="zh_example", hr="hr_example", cs="cs_example", da="da_example", nl="nl_example", et="et_example", fi="fi_example", fr="fr_example", ka="ka_example", de="de_example", el="el_example", hi="hi_example", he="he_example", hu="hu_example", id="id_example", it="it_example", ja="ja_example", ko="ko_example", lv="lv_example", lt="lt_example", ms="ms_example", nb="nb_example", pl="pl_example", fa="fa_example", pt="pt_example", pa="pa_example", ro="ro_example", ru="ru_example", sr="sr_example", sk="sk_example", es="es_example", sv="sv_example", th="th_example", tr="tr_example", uk="uk_example", vi="vi_example", ), sound="sound_example", stale_date=1, dismissal_date=1, priority=1, ) try: # Update a Live Activity via Push api_response = api_instance.update_live_activity(app_id, activity_id, update_live_activity_request) pprint(api_response) except onesignal.ApiException as e: print("Exception when calling DefaultApi->update_live_activity: %s\n" % e) print("Status Code: %s" % e.status) print("Response Body: %s" % e.body) - lang: php label: PHP SDK source: >- setRestApiKeyToken('YOUR_REST_API_KEY') ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY'); $apiInstance = new onesignal\client\Api\DefaultApi( // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`. // This is optional, `GuzzleHttp\Client` will be used as default. new GuzzleHttp\Client(), $config ); $app_id = '00000000-0000-0000-0000-000000000000'; // string | The OneSignal App ID for your app. Available in Keys & IDs. $activity_id = '12345'; // string | Live Activity record ID $update_live_activity_request = new \onesignal\client\model\UpdateLiveActivityRequest(); // \onesignal\client\model\UpdateLiveActivityRequest try { $result = $apiInstance->updateLiveActivity($app_id, $activity_id, $update_live_activity_request); print_r($result); } catch (\onesignal\client\ApiException $e) { echo 'Exception when calling DefaultApi->updateLiveActivity: ', $e->getMessage(), PHP_EOL; echo 'Status Code: ', $e->getCode(), PHP_EOL; // getErrorMessages() flattens any error-envelope shape to a string[]; // the raw body remains on getResponseBody(). echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL; echo 'Response Body: ', $e->getResponseBody(), PHP_EOL; } catch (\Exception $e) { echo 'Exception when calling DefaultApi->updateLiveActivity: ', $e->getMessage(), PHP_EOL; } - lang: go label: Go SDK source: |- package main import ( "context" "fmt" "os" "github.com/OneSignal/onesignal-go-api/v5" ) func main() { appId := "00000000-0000-0000-0000-000000000000" // string | The OneSignal App ID for your app. Available in Keys & IDs. activityId := "12345" // string | Live Activity record ID updateLiveActivityRequest := *onesignal.NewUpdateLiveActivityRequest("Name_example", "Event_example", map[string]interface{}{"key": "value"}) // UpdateLiveActivityRequest | configuration := onesignal.NewConfiguration() apiClient := onesignal.NewAPIClient(configuration) restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, "YOUR_REST_API_KEY") // App REST API key required for most endpoints resp, r, err := apiClient.DefaultApi.UpdateLiveActivity(restAuth, appId, activityId).UpdateLiveActivityRequest(updateLiveActivityRequest).Execute() if err != nil { fmt.Fprintf(os.Stderr, "Error when calling `DefaultApi.UpdateLiveActivity``: %v\n", err) fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r) if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok { // ErrorMessages() flattens any error-envelope shape to a []string; // the raw body remains on Body(). fmt.Fprintf(os.Stderr, "Error Messages: %v\n", apiErr.ErrorMessages()) fmt.Fprintf(os.Stderr, "Response Body: %s\n", apiErr.Body()) } } // response from `UpdateLiveActivity`: UpdateLiveActivitySuccessResponse fmt.Fprintf(os.Stdout, "Response from `DefaultApi.UpdateLiveActivity`: %v\n", resp) } - lang: ruby label: Ruby SDK source: >- require 'onesignal' # setup authorization OneSignal.configure do |config| # Configure Bearer authorization: rest_api_key config.rest_api_key = 'YOUR_REST_API_KEY' end api_instance = OneSignal::DefaultApi.new app_id = '00000000-0000-0000-0000-000000000000' # String | The OneSignal App ID for your app. Available in Keys & IDs. activity_id = '12345' # String | Live Activity record ID update_live_activity_request = OneSignal::UpdateLiveActivityRequest.new({name: 'name_example', event: 'update', event_updates: 3.56}) # UpdateLiveActivityRequest | begin # Update a Live Activity via Push result = api_instance.update_live_activity(app_id, activity_id, update_live_activity_request) p result rescue OneSignal::ApiError => e puts "Error when calling DefaultApi->update_live_activity: #{e}" puts "Status Code: #{e.code}" # `e.error_messages` flattens any error-envelope shape to an Array; # the raw body remains on `e.response_body`. puts "Error Messages: #{e.error_messages}" puts "Response Body: #{e.response_body}" end - lang: java label: Java SDK source: |- // Import classes: import com.onesignal.client.ApiClient; import com.onesignal.client.ApiException; import com.onesignal.client.Configuration; import com.onesignal.client.auth.*; import com.onesignal.client.model.*; import com.onesignal.client.api.DefaultApi; public class Example { public static void main(String[] args) { ApiClient defaultClient = Configuration.getDefaultApiClient(); defaultClient.setBasePath("https://api.onesignal.com"); // Configure HTTP bearer authorization: rest_api_key HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication("rest_api_key"); rest_api_key.setBearerToken("YOUR_REST_API_KEY"); DefaultApi apiInstance = new DefaultApi(defaultClient); String appId = "00000000-0000-0000-0000-000000000000"; // String | The OneSignal App ID for your app. Available in Keys & IDs. String activityId = "12345"; // String | Live Activity record ID UpdateLiveActivityRequest updateLiveActivityRequest = new UpdateLiveActivityRequest(); // UpdateLiveActivityRequest | try { UpdateLiveActivitySuccessResponse result = apiInstance.updateLiveActivity(appId, activityId, updateLiveActivityRequest); System.out.println(result); } catch (ApiException e) { System.err.println("Exception when calling DefaultApi#updateLiveActivity"); System.err.println("Status code: " + e.getCode()); // getErrorMessages() flattens any error-envelope shape to a List; // the raw body remains on getResponseBody(). System.err.println("Error messages: " + e.getErrorMessages()); System.err.println("Reason: " + e.getResponseBody()); System.err.println("Response headers: " + e.getResponseHeaders()); e.printStackTrace(); } } } - lang: csharp label: C# SDK source: |- using System; using System.Collections.Generic; using System.Diagnostics; using OneSignalApi.Api; using OneSignalApi.Client; using OneSignalApi.Model; namespace Example { public class UpdateLiveActivityExample { public static void Main() { Configuration config = new Configuration(); config.BasePath = "https://api.onesignal.com"; // Configure Bearer token for authorization: rest_api_key config.AccessToken = "YOUR_REST_API_KEY"; var apiInstance = new DefaultApi(config); var appId = "00000000-0000-0000-0000-000000000000"; // string | The OneSignal App ID for your app. Available in Keys & IDs. var activityId = "12345"; // string | Live Activity record ID var updateLiveActivityRequest = new UpdateLiveActivityRequest(); // UpdateLiveActivityRequest | try { // Update a Live Activity via Push UpdateLiveActivitySuccessResponse result = apiInstance.UpdateLiveActivity(appId, activityId, updateLiveActivityRequest); Debug.WriteLine(result); } catch (ApiException e) { Debug.Print("Exception when calling DefaultApi.UpdateLiveActivity: " + e.Message ); Debug.Print("Status Code: "+ e.ErrorCode); // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList; // the raw body remains on e.ErrorContent. Debug.Print("Error Messages: " + string.Join(", ", e.ErrorMessages)); Debug.Print("Response Body: " + e.ErrorContent); Debug.Print(e.StackTrace); } } } } - lang: rust label: Rust SDK source: |- use onesignal_rust_api::apis::configuration::Configuration; use onesignal_rust_api::apis::default_api; use onesignal_rust_api::models; #[tokio::main] async fn main() { let mut configuration = Configuration::new(); configuration.rest_api_key_token = Some("YOUR_REST_API_KEY".to_string()); // Realistic values are pulled from the spec's `example:` fields where present. let app_id: &str = "00000000-0000-0000-0000-000000000000"; let activity_id: &str = "12345"; let update_live_activity_request: models::UpdateLiveActivityRequest = todo!(); match default_api::update_live_activity(&configuration, app_id, activity_id, update_live_activity_request).await { Ok(resp) => println!("{:?}", resp), Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => { // `e.error_messages()` flattens any error-envelope shape to a Vec; // the raw response remains on the ResponseError variant. eprintln!("update_live_activity failed: {:?}", e.error_messages()); } Err(e) => eprintln!("update_live_activity failed: {:?}", e), } } components: schemas: BasicErrorResponse: type: object properties: errors: type: array items: type: string description: One or more human-readable error messages. success: type: boolean description: >- Present (and `false`) on some endpoints (notifications, templates, segments). Not emitted by every endpoint. reference: type: array items: type: string description: >- Documentation URL fragments related to the error. Only emitted by the API-key auth error helpers. ````