# Schedules

Schedule notifications for delivery.


## Schedule object {#scheduleobject}

A schedule object consists of a schedule, i.e., a future delivery time, an optional name, and a push object.

[Jump to examples ↓](#scheduleobject-examples)

- **`localization_ids`** `array[string]`

  An array of identifiers used for reporting. Each ID represents a localized message (push object with `localizations` array).

- **`name`** `string`

  An optional string.

- **`push`** `object` <[Push object]({{< ref "/developer/rest-api/ua/schemas/push/" >}}#pushobject)> **REQUIRED**

  A push object describes everything about a push notification, including the audience and push payload. A push object is composed of up to seven attributes.

- **`push_ids`** `array[string]`

  An array of the push IDs associated with the schedule. The `push_ids` key is set by the server, and so is present in responses but not in creation requests sent from the client. Requests that contain this key will return a `HTTP 400 Bad Request`.

  Min items: 1, Max items: 100

  Example: `00256e0b-b02f-4f12-a77f-4c3d57078330,f59970d3-3d42-4584-907e-f5c57f5d46a1`

  Read only: true

- **`schedule`** `object` **REQUIRED**
  **Any of:**

  - [Schedule specification]({{< ref "/developer/rest-api/ua/schemas/schedules/" >}}#schedulespec)

    The delivery time specified in UTC.

  - **Recurring schedule** `object`

    Recurring schedules allow you to send a message multiple times at a set cadence. This is useful for subscription reminders, birthdays, etc. This is accomplished by adding recurring data to the schedule endpoint.

    - **`recurring`** `object`
      **OBJECT PROPERTIES**

      - **`cadence`** `object` **REQUIRED**

        Defines how often the message is to be sent. It consists of the type (unit) and an optional value (count).

        **One of:**

        - **Standard Cadence** `object`
          - **`count`** `integer` **REQUIRED**

            The frequency of messaging corresponding to the `type`. For example, a `count` of 2 results in a message every 2 hours, days, weeks, months, etc. based on the `type` value.

            Min: 1

          - **`type`** `string` **REQUIRED**

            The unit of measurement for the cadence.

            Possible values: `hourly`, `daily`, `monthly`, `yearly`

        - **Weekly Cadence** `object`
          - **`count`** `integer` **REQUIRED**

            The frequency of messaging on the weekly cadence. For example, a `count` of 2 results in a message every 2 weeks.

            Min: 1

          - **`days_of_week`** `string`

            The days of the week on which Airship can send your message.

            Possible values: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`

          - **`type`** `string` **REQUIRED**

            Possible values: `weekly`


      - **`end_time`** `string`

        The [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format) when the schedule will end and stop sending messages.

        Format: `date-time`

      - **`exclusions`** `array`

        The [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format) ranges when messages are not sent.

        Min items: 1

        **One of:**

          - **`hour_range`** `string`

            The hourly interval exclude from your cadence. Use 24-hour time separated by a dash, example: `"12-14"`. Times are inclusive.


            Example: `12-14`

          - **`date_range`** `string`

            The [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format) ranges to exclude from your cadence. Separate the start and end date-times with a forward slash (`/`). Date-times are inclusive.


            Format: `date-time`

          - **`days_of_week`** `array[string]`

            The days of the week that you want to exclude from your schedule cadence. Days are inclusive. Airship considers `monday` the beginning of a week.

            Min items: 1

            Possible values: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`


      - **`paused`** `boolean`

        If `true`, the schedule is paused, and will not result in sends at the regularly scheduled `cadence`.

        Read only: true


- **`url`** `string`

  The `url` key is set by the server, and so is present in responses but not in creation requests sent from the client.

  Format: `url`

  Read only: true


**Used in:**

- [List a specific schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedule)
- [List schedules]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedules)
- [Schedule a notification]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#schedulenotification)
- [Schedule a templated push]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#scheduletemplatedpush)
- [Update schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#updateschedule)

**Examples**

*Example schedule*

```json
{
    "url": "http://go.urbanairship/api/schedules/2d69320c-3c91-5241-fac4-248269eed109",
    "schedule": {"scheduled_time": "2020-04-01T18:45:30"},
    "name": "My schedule",
    "push": {
        "audience": {"tag": "49ers"},
        "device_types": [ "ios", "android" ],
        "notification": {"alert": "Touchdown!"},
        "options": {"expiry": 10800}
    }
}

```

---

## Schedule specification {#schedulespec}

The delivery time specified in UTC.

[Jump to examples ↓](#schedulespec-examples)

**One of:**

- **Scheduled time** `object`

  Scheduled push to be delivered globally at the same moment.

  - **`scheduled_time`** `string`

    A [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format).

    Format: `date-time`

- **Local scheduled time** `object`

  Deliver a message at each device's local time. This ensures that users receive your message at the same time of day across all time zones in your app's audience. This feature only works for channels that have a `timezone` tag (or Named Users containing at least one channel with a `timezone` tag). Devices in the audience that do not have a `timezone` tag will not receive your message.


  - **`local_scheduled_time`** `string`

    Alternative to `scheduled_time`. The scheduled device local [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format) to send the notification.


    Format: `date-time`

    Example: `2018-03-01T12:00:00`

- **Best time** `object`

  Alternative to `scheduled_time`. Uses predictive analytics to send the notification at the [optimal send time](/docs/guides/features/intelligence-ai/predictive/optimal-send-time/) for each member of your audience.

  When your audience includes users without an optimal send time tag, those users will be dropped from delivery and will not receive the message. Since optimal send time is determined from user behavior over time, new users might not have an optimal send time determined for the first week or two after channel registration.


  - **`best_time`** `object`

    Schedules the notification for the optimal send time.


    **OBJECT PROPERTIES**

    - **`send_date`** `string`

      The date set by the user for when the push should go out, localized to the time zone for a given channel. Best-time pushes require activation of our predictive analytics toolset.


      Format: `date`


**Used in:**

- [Create experiment (A/B Test)]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#createexperiment)
- [Experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiments)
- [Experiment lookup]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiment)
- [List a specific schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedule)
- [List schedules]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedules)
- [Schedule a notification]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#schedulenotification)
- [Schedule a templated push]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#scheduletemplatedpush)
- [Scheduled experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getscheduledexperiments)
- [Update schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#updateschedule)
- [Validate experiment]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#validateexperiment)

**Examples**

*Global schedule*

```json
{
   "scheduled_time": "2020-04-01T18:45:30"
}

```

*Best time example*

```json
{
  "best_time": {
    "send_date": "2020-06-01"
  }
}

```

*Local time*

```json
{
   "local_scheduled_time": "2020-04-01T18:45:30"
}

```

---