---
title: "Create relative scheduled message"
method: POST
path: "/v1/projects/{project_id}/relative_scheduled"
tags: ["ScheduledMessage"]
---

# Create relative scheduled message

`POST /v1/projects/{project_id}/relative_scheduled`

## Request

- Base URL: `https://api.telerivet.com`
- URL: `https://api.telerivet.com/v1/projects/{project_id}/relative_scheduled`
- Auth: one of:
  - HTTP basic
  - OAuth 2 (authorization code, authorization URL `https://telerivet.com/oauth/authorize`, token URL `https://api.telerivet.com/oauth/token`)

Creates a relative scheduled message. This allows scheduling messages on a different date for each contact, for example on their birthday, a certain number of days before an appointment, or a certain number of days after enrolling in a campaign.

 Telerivet will automatically create a ScheduledMessage for each contact matching a RelativeScheduledMessage.

 Relative scheduled messages can be created for a group or an individual contact, although dynamic groups are not supported. Only one of the parameters group_id, to_number, and contact_id should be provided.

 With message_type=service, schedules an automated service (such as a poll). Any service that can be triggered for a contact can be scheduled via this method, whether or not the service actually sends a message.

## Path parameters

- `project_id` string, required

## Request body

- object
  - `message_type` string: Type of message to send
  - `content` string: Content of the message to schedule
  - `group_id` string: ID of the group to send the message to. Dynamic groups are not supported.
  - `to_number` string: Phone number to send the message to
  - `contact_id` string: ID of the contact to send the message to
  - `time_of_day` string: Time of day when scheduled messages will be sent in HH:MM format (with hours from 00 to 23). Required unless offset_scale is `I` (minutes), in which case it is ignored. (Messages are only scheduled for future times: if this time has already passed before a contact matches this relative scheduled message, a message will not be sent to the contact)
  - `timezone_id` string: TZ database timezone ID; see [List of tz database time zones Wikipedia article](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
  - `date_variable` string, required: Custom contact variable storing date or date/time values relative to which messages will be scheduled.
  - `offset_scale` 'I' | 'D' | 'W' | 'M' | 'Y': The type of interval that will be used to adjust the scheduled time relative to the date or date/time stored in the contact's date_variable, when offset_count is non-zero (I=minutes, D=day, W=week, M=month, Y=year). With `I` (minutes), the message is sent at the exact date/time stored in the contact variable plus the offset, and time_of_day is ignored; this requires date_variable to be a date/time field (not a date field).
  - `offset_count` integer: The number of minutes/days/weeks/months/years (according to offset_scale) to adjust the time of the scheduled message relative to the date or date/time stored in the custom contact variable identified by the date_variable parameter. May be positive, negative, or zero.
  - `rrule` string: A recurrence rule describing the how the schedule repeats, e.g. 'FREQ=MONTHLY' or 'FREQ=WEEKLY;INTERVAL=2'; see <https://tools.ietf.org/html/rfc2445#section-4.3.10>. (UNTIL is ignored; use end_time parameter instead).
  - `route_id` string: ID of the phone or route to send the message from
  - `service_id` string: Service to invoke for each recipient (when `message_type` is `call` or `service`)
  - `audio_url` string: The URL of an MP3 file to play when the contact answers the call (when `message_type` is `call`). If `audio_url` is provided, the text-to-speech voice is not used to say `content`, although you can optionally use `content` to indicate the script for the audio. For best results, use an MP3 file containing only speech. Music is not recommended because the audio quality will be low when played over a phone line.
  - `tts_lang` 'en-US' | 'en-GB' | 'en-GB-WLS' | 'en-AU' | 'en-IN' | 'da-DK' | 'nl-NL' | 'fr-FR' | 'fr-CA' | 'de-DE' | 'is-IS' | 'it-IT' | 'pl-PL' | 'pt-BR' | 'pt-PT' | 'ru-RU' | 'es-ES' | 'es-US' | 'sv-SE': The language of the text-to-speech voice (when `message_type` is `call`)
  - `tts_voice` 'female' | 'male': The name of the text-to-speech voice (when message_type=call)
  - `track_clicks` boolean: If true, URLs in the message content will automatically be replaced with unique short URLs.
  - `short_link_params` object: If `track_clicks` is true, `short_link_params` may be used to specify custom parameters for each short link in the message. The following parameters are supported: `domain` (string): A custom short domain name to use for the short links. The domain name must already be registered for your project or organization. `expiration_sec` (integer): The number of seconds after the message is created (queued to send) when the short links will stop forwarding to the destination URL. If null, the short links will not expire.
  - `replace_variables` boolean: Set to true to evaluate variables like [[contact.name]] in message content. (See available variables)
  - `media` object[]: Array of media attachments for the text message. If sending a type of message that doesn't support attachments (e.g. SMS), short links to each media URL will be appended to the end of the content (separated by a new line). To attach the Contact Card (a `.vcf` file that the recipient can save to their address book) of the route that sends the message, include the media item `{"type": "route_vcard"}`. The card is attached when each message is sent, using the current card of the phone that actually sends it (see the `vcard` property of the Phone object). If that route's Contact Card is not enabled, the message is sent without it. Alternatively, you can use the `media_urls` parameter with an array of URL strings.
    - `url` string: URL of the media file. Required unless file_id is provided. Use a https:// or http:// URL for media files that are already accessible via the internet. For media files that are not already accessible via the internet or uploaded as a stored file, the URL may be a data URI with the file data encoded via Base64 (e.g. "data:image/png;base64,..."), with a maximum decoded file size of 5 MB. Telerivet will automatically store this file in your project.
    - `file_id` string: ID of a previously uploaded stored file (see [project.uploadFile](#Project.uploadFile)). If file_id is provided, url is not required.
    - `type` string: MIME type of the media file (e.g. image/png). if not provided, Telerivet will attempt to determine the MIME type automatically from the extension of the filename or URL path component. Ignored if file_id is provided. To attach the Contact Card of the route that sends the message, use a media item with only `type` set to `route_vcard`.
    - `filename` string: Original filename of the media. Ignored if file_id is provided.
  - `route_params` object: Route-specific parameters to use when sending the message. When sending messages via chat apps such as WhatsApp, the route_params parameter can be used to send messages with app-specific features such as quick replies and link buttons. For more details, see Route-Specific Parameters.
  - `variants` object[]: Alternative message bodies (text messages only). Allows sending different message bodies depending on the route that sends the message, or the contact that the message is sent to. Each variant has conditions and its own message body. When each message is sent, the first variant whose conditions match is used instead of the default message body; if no variant matches, the default message body is used. A variant replaces the entire message body: content, media, route_params, track_clicks and short_link_params that are not specified in the variant are empty, not inherited from the default message body. Conditions are evaluated when the message is sent by a particular basic route, and can use the same variables as outgoing message content: contact variables such as [[contact.name]] and [[contact.vars.\*]], [[to_number]], [[time]], [[project.\*]], and variables of the basic route sending the message: [[phone.type]] (e.g. whatsapp), [[phone.id]], [[phone.vars.\*]], and [[phone.supports_quick_replies]], [[phone.supports_link_button]], [[phone.supports_native_attachments]] (1 if the route supports the feature, otherwise 0). Variables may include filters, e.g. [[contact.vars.language|default:"en"]]. For all available variables, see the [Variable Reference](https://telerivet.com/api/rest#variables). For A/B testing, a variant can have a random split (split_percent) so that it is only used for a random percentage of recipients, e.g. a single variant with split_percent 50 is used for about half of the recipients, and the default message body for the others. A random split can be combined with other conditions to run separate A/B tests for different routes or contacts. Since the first matching variant is used, list more specific variants before more general ones. For example, a variant with a condition `[[contact.vars.language]] is 'fr'` and split_percent 50 must be listed before a variant with only the condition `[[contact.vars.language]] is 'fr'`. Up to 10 variants are supported, each with up to 5 conditions.
    - `conditions` object[]: Conditions for using this variant (up to 5). Required unless the variant has a `split_percent`.
      - `variable` string: Variable to compare (required except when condition type is `contact_is_in_group` or `contact_not_in_group`), surrounded by double square brackets, e.g. `[[phone.type]]` or `[[contact.vars.lang]]`
      - `type` string, required: Type of condition
      - `value` string, required: Value to compare with the variable, or the group name if the condition type is `contact_is_in_group` or `contact_not_in_group`
    - `op` string: Operator to join multiple conditions: `and` (default) or `or`. If `split_percent` is specified, `or` is not supported.
    - `split_percent` integer: For A/B testing, the approximate percentage of recipients (1-100) randomly selected for this variant. Each variant with a `split_percent` is used for a separate random group of recipients, and recipients not selected for any variant receive the default message body (e.g. a single variant with a `split_percent` of 50 is used for about half of the recipients). Recipients are assigned to groups deterministically, so each contact is in the same group for all messages in the same broadcast or campaign. The total `split_percent` of all variants with the same conditions can be at most 100. If `split_percent` is omitted, the variant is used for all recipients that match its conditions.
    - `content` string: Content of the message when this variant is used
    - `media` object[]: Array of media attachments when this variant is used (same format as the `media` parameter)
    - `route_params` object: Route-specific parameters when this variant is used
    - `track_clicks` boolean: Whether to shorten links and track link clicks when this variant is used
    - `short_link_params` object: Parameters for short links when `track_clicks` is enabled (same format as the `short_link_params` parameter)
  - `label_ids` string: Array of IDs of labels to add to the sent messages (maximum 5). Does not apply when `message_type`=`service`, since the labels are determined by the service itself.
  - `end_time` integer: Time after which a recurring message will stop (not applicable to non-recurring scheduled messages)
  - `end_time_offset` integer: Number of seconds from now until the recurring message will stop
  - `vars` object: Custom variables to set for this relative scheduled message, which will be copied to each message sent from this scheduled message

## Response `200`

Successful response

- RelativeScheduledMessage: A relative scheduled message is a message that is scheduled relative to a date stored as a custom field for each recipient contact. This allows scheduling messages on a different date for each contact, for example on their birthday, a certain number of days before an appointment, or a certain number of days after enrolling in a campaign. Telerivet will automatically create a ScheduledMessage for each contact matching a RelativeScheduledMessage. Any service that can be manually triggered for a contact (including polls) may also be scheduled via a relative scheduled message, whether or not the service actually sends a message.
  - `id` string: ID of the relative scheduled message
  - `content` string: Text content of the relative scheduled message
  - `time_of_day` string, nullable: Time of day when scheduled messages will be sent in HH:MM format (with hours from 00 to 23), or null if offset_scale is `I` (minutes)
  - `date_variable` string: Custom contact variable storing date or date/time values relative to which messages will be scheduled.
  - `offset_scale` 'I' | 'D' | 'W' | 'M' | 'Y': The type of interval that will be used to adjust the scheduled time relative to the date or date/time stored in the contact's date_variable, when offset_count is non-zero (I=minutes, D=day, W=week, M=month, Y=year). With `I` (minutes), the message is sent at the exact date/time stored in the contact variable plus the offset, and time_of_day is ignored; this requires date_variable to be a date/time field (not a date field).
  - `offset_count` integer: The number of minutes/days/weeks/months/years (according to offset_scale) to adjust the time of the scheduled message relative to the date or date/time stored in the contact's date_variable. May be positive, negative, or zero.
  - `rrule` string: Recurrence rule for recurring scheduled messages, e.g. 'FREQ=MONTHLY' or 'FREQ=WEEKLY;INTERVAL=2'; see [RFC2445](https://tools.ietf.org/html/rfc2445#section-4.3.10).
  - `end_time` integer, nullable: Time after which recurring messages will stop (not applicable to non-recurring scheduled messages)
  - `timezone_id` string: Timezone ID used to compute times for recurring messages; see [List of tz database time zones Wikipedia article](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
  - `recipients_str` string: A string with a human readable description of the recipient
  - `group_id` string: ID of the group to send the message to (null if the recipient is an individual contact)
  - `contact_id` string: ID of the contact to send the message to (null if the recipient is a group)
  - `to_number` string: Phone number to send the message to (null if the recipient is a group)
  - `route_id` string: ID of the phone or route the message will be sent from
  - `service_id` string: The service associated with this message (for voice calls, the service defines the call flow)
  - `audio_url` string: For voice calls, the URL of an MP3 file to play when the contact answers the call
  - `tts_lang` 'en-US' | 'en-GB' | 'en-GB-WLS' | 'en-AU' | 'en-IN' | 'da-DK' | 'nl-NL' | 'fr-FR' | 'fr-CA' | 'de-DE' | 'is-IS' | 'it-IT' | 'pl-PL' | 'pt-BR' | 'pt-PT' | 'ru-RU' | 'es-ES' | 'es-US' | 'sv-SE': For voice calls, the language of the text-to-speech voice
  - `tts_voice` 'female' | 'male': For voice calls, the text-to-speech voice
  - `message_type` 'sms' | 'mms' | 'ussd' | 'ussd_session' | 'call' | 'chat' | 'service': Type of scheduled message
  - `time_created` integer: Time the relative scheduled message was created in Telerivet
  - `replace_variables` boolean: Set to true if Telerivet will render variables like [[contact.name]] in the message content, false otherwise
  - `track_clicks` boolean: If true, URLs in the message content will automatically be replaced with unique short URLs
  - `media` object[]: Array of media attachments for the text message. This property is undefined for messages that do not contain media files.
    - `url` string: URL of the media file. Note: For files stored by Telerivet (including uploaded files and incoming media attachments), the URL is temporary and may not be valid for more than 1 day.
    - `type` string: MIME type of the media file, or `route_vcard` for the Contact Card of the sending route in a message that has not been sent yet (in which case the other properties are null)
    - `filename` string: Original filename
    - `size` integer: File size in bytes
    - `file_id` string: ID of the stored file, if applicable
  - `route_params` object, nullable: Route-specific parameters to use when sending the message. When sending messages via chat apps such as WhatsApp, the route_params parameter can be used to send messages with app-specific features such as quick replies and link buttons. For more details, see Route-Specific Parameters.
  - `variants` object[], nullable: Alternative message bodies used instead of the default message body when their conditions match. Allows sending different message bodies depending on the route that sends the message, or the contact that the message is sent to. Each variant has conditions and its own message body. When each message is sent, the first variant whose conditions match is used instead of the default message body; if no variant matches, the default message body is used. A variant replaces the entire message body: content, media, route_params, track_clicks and short_link_params that are not specified in the variant are empty, not inherited from the default message body. Conditions are evaluated when the message is sent by a particular basic route, and can use the same variables as outgoing message content: contact variables such as [[contact.name]] and [[contact.vars.\*]], [[to_number]], [[time]], [[project.\*]], and variables of the basic route sending the message: [[phone.type]] (e.g. whatsapp), [[phone.id]], [[phone.vars.\*]], and [[phone.supports_quick_replies]], [[phone.supports_link_button]], [[phone.supports_native_attachments]] (1 if the route supports the feature, otherwise 0). Variables may include filters, e.g. [[contact.vars.language|default:"en"]]. For all available variables, see the [Variable Reference](https://telerivet.com/api/rest#variables). For A/B testing, a variant can have a random split (split_percent) so that it is only used for a random percentage of recipients, e.g. a single variant with split_percent 50 is used for about half of the recipients, and the default message body for the others. A random split can be combined with other conditions to run separate A/B tests for different routes or contacts. Since the first matching variant is used, list more specific variants before more general ones. For example, a variant with a condition `[[contact.vars.language]] is 'fr'` and split_percent 50 must be listed before a variant with only the condition `[[contact.vars.language]] is 'fr'`. Up to 10 variants are supported, each with up to 5 conditions.
    - `conditions` object[]: Conditions for using this variant (up to 5). Required unless the variant has a `split_percent`.
      - `variable` string: Variable to compare (required except when condition type is `contact_is_in_group` or `contact_not_in_group`), surrounded by double square brackets, e.g. `[[phone.type]]` or `[[contact.vars.lang]]`
      - `type` string, required: Type of condition
      - `value` string, required: Value to compare with the variable, or the group name if the condition type is `contact_is_in_group` or `contact_not_in_group`
    - `op` string: Operator to join multiple conditions: `and` (default) or `or`. If `split_percent` is specified, `or` is not supported.
    - `split_percent` integer: For A/B testing, the approximate percentage of recipients (1-100) randomly selected for this variant. Each variant with a `split_percent` is used for a separate random group of recipients, and recipients not selected for any variant receive the default message body (e.g. a single variant with a `split_percent` of 50 is used for about half of the recipients). Recipients are assigned to groups deterministically, so each contact is in the same group for all messages in the same broadcast or campaign. The total `split_percent` of all variants with the same conditions can be at most 100. If `split_percent` is omitted, the variant is used for all recipients that match its conditions.
    - `content` string: Content of the message when this variant is used
    - `media` object[]: Array of media attachments when this variant is used (same format as the `media` parameter)
    - `route_params` object: Route-specific parameters when this variant is used
    - `track_clicks` boolean: Whether to shorten links and track link clicks when this variant is used
    - `short_link_params` object: Parameters for short links when `track_clicks` is enabled (same format as the `short_link_params` parameter)
  - `vars` object: Custom variables stored for this scheduled message (copied to each ScheduledMessage and Message when sent). Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.
  - `label_ids` string: IDs of labels to add to the Message
  - `project_id` string: ID of the project this relative scheduled message belongs to

## Other responses

- `400`: Invalid request parameters
- `401`: Invalid or missing API key or Bearer token
- `404`: Resource not found

---

[API](https://skmtc.dev/telerivet/apis/telerivet-api.md) · [All operations](https://skmtc.dev/telerivet/apis/telerivet-api/llms.txt) · [OpenAPI document](https://skmtc.dev/telerivet/apis/telerivet-api/revisions/4e14b1c8d917?raw)