# NOTE: This file is auto generated by OpenAPI Generator 6.2.0 (https://openapi-generator.tech).
# Do not edit this file manually.

defmodule BrazeEx.Api.MessagingLiveActivities do
  @moduledoc """
  API calls for all endpoints tagged `MessagingLiveActivities`.
  """

  alias BrazeEx.Connection
  import BrazeEx.RequestBuilder

  @doc """
  ## Update Live Activity

  > Use this endpoint to update and end [Live Activities](https://www.braze.com/docs/developer_guide/platform_integration_guides/swift/live_activities/live_activities/) displayed by your iOS app. This endpoint requires additional setup. 


  Before using this endpoint, you must register an activity with the Braze Swift SDK using the [<code>launchActivity</code>](https://braze-inc.github.io/braze-swift-sdk/documentation/brazekit/braze/liveactivities-swift.class/launchactivity(pushtokentag:activity:fileid:line:)) method. Required request parameters will be defined during this step. Refer to [Live Activities](https://www.braze.com/developer_guide/platform_integration_guides/swift/live_activities/live_activities/) for more information on registration.

  Once you have registered your activity, pass a JSON payload with updates to the Apple Push Notification service (APNs) through this endpoint. See Apple's documentation on [updating your Live Activity with push notification payloads](https://developer.apple.com/documentation/activitykit/updating-and-ending-your-live-activity-with-activitykit-push-notifications) for more information.

  ## Prerequisites

  To use this endpoint, you’ll need to generate an API key with the `messages.live_activity.update` permission.

  ## Rate limit

  We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.

  ## Request parameters

  | Parameter | Required | Data Type | Description |
  | --- | --- | --- | --- |
  | `app_id` | Required | String | App [API identifier](https://www.braze.com/docs/api/identifier_types/#the-app-identifier) retrieved from **Settings > Setup and Testing > API Keys.** |
  | `activity_id` | Required | String | When you register your Live Activity using [<code>launchActivity</code>](https://braze-inc.github.io/braze-swift-sdk/documentation/brazekit/braze/liveactivities-swift.class), you use the `pushTokenTag` parameter to name the Activity's push token to a custom string.  <br>  <br>Set `activity_id` to this custom string to define which Live Activity you want to update. |
  | `content_state` | Required | Object | You define the `ContentState` parameters when you create your Live Activity. Pass the updated values for your `ContentState` using this object.  <br>  <br>The format of this request must match the shape you initially defined. |
  | `end_activity` | Optional | Boolean | If `true`, this request ends the Live Activity. |
  | `dismissal_date` | Optional | Datetime  <br>([ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) string) | This parameter defines the time to remove the Live Activity from the user's UI. If this time is in the past, the Live Activity will be removed immediately. |
  | `stale_date` | Optional | Datetime  <br>([ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) string) | This parameter tells the system when the Live Activity content is marked as outdated in the user's UI. |
  | `notification` | Optional | Object | Include an [<code>apple_push</code>](https://www.braze.com/docs/api/objects_filters/messaging/apple_object/) object to define a push notification. This behavior of this push notification depends on if the user is active or if the user is using a proxy device. {::nomarkdown}  <br>  <br>  <br>  <br>  <br>  <br>\- If a `notification` is included and the user is active on their iPhone when the update is delivered, the updated Live Activity UI will slide down and display like a push notification.  <br>\- If a `notification` is included and the user is not active on their iPhone, their screen will light up to display the updated Live Activity UI on their lock screen.  <br>\- The `notification alert` will not display as a standard push notification. Additionally, if a user has a proxy device, like an Apple Watch, the `alert` will be displayed there. |

  ## Response

  There are two status code responses for this endpoint: `201` and `4XX`.

  ### Example success response

  A `201` status code is returned if the request was formatted correctly and we received the request. The status code `201` could return the following response body.

  ``` json
  {
  "message": "success"
  }

  ```

  ### Example error response

  The `4XX` class of status code indicates a client error. Refer to the [API errors and responses article](https://www.braze.com/docs/api/errors/) for more information about errors you may encounter.

  The status code `400` could return the following response body.

  ``` json
  {
    "error": "\nProblem:\n  message body does not match declared format\nResolution:\n  when specifying application/json as content-type, you must pass valid application/json in the request's 'body' "
  }

  ```

  ### Parameters

  - `connection` (BrazeEx.Connection): Connection to server
  - `opts` (keyword): Optional parameters
    - `:"Content-Type"` (String.t): 
    - `:Authorization` (String.t): 
    - `:body` (String.t): 

  ### Returns

  - `{:ok, nil}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec messages_live_activity_update_post(Tesla.Env.client(), keyword()) ::
          {:ok, nil} | {:error, Tesla.Env.t()}
  def messages_live_activity_update_post(connection, opts \\ []) do
    optional_params = %{
      :"Content-Type" => :headers,
      :Authorization => :headers,
      :body => :body
    }

    request =
      %{}
      |> method(:post)
      |> url("/messages/live_activity/update")
      |> add_optional_params(optional_params, opts)
      |> ensure_body()
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {200, false}
    ])
  end
end