ScheduledMessage

Create relative scheduled message

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.

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)

Path parameters

project_idstring required

ID of the Project

Request body

message_typestring

Type of message to send

contentstring

Content of the message to schedule

group_idstring

ID of the group to send the message to. Dynamic groups are not supported.

to_numberstring

Phone number to send the message to

contact_idstring

ID of the contact to send the message to

time_of_daystring

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_idstring

TZ database timezone ID; see List of tz database time zones Wikipedia article.

date_variablestring 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_countinteger

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.

rrulestring

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_idstring

ID of the phone or route to send the message from

service_idstring

Service to invoke for each recipient (when message_type is call or service)

audio_urlstring

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.

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_clicksboolean

If true, URLs in the message content will automatically be replaced with unique short URLs.

short_link_paramsobject

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_variablesboolean

Set to true to evaluate variables like [[contact.name]] in message content. (See available variables)

route_paramsobject

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.

label_idsstring

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_timeinteger

Time after which a recurring message will stop (not applicable to non-recurring scheduled messages)

end_time_offsetinteger

Number of seconds from now until the recurring message will stop

varsobject

Custom variables to set for this relative scheduled message, which will be copied to each message sent from this scheduled message

Example request

{
  "content": "Hi [[contact.name]], just following up!",
  "group_id": "CG123123123123123123",
  "time_of_day": "15:07",
  "date_variable": "date",
  "offset_scale": "D",
  "offset_count": 3,
  "rrule": "FREQ=MONTHLY",
  "replace_variables": true
}

Response

Successful response

idstring

ID of the relative scheduled message

contentstring

Text content of the relative scheduled message

time_of_daystring 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_variablestring

Custom contact variable storing date or date/time values relative to which messages will be scheduled.

offset_scale'I' | 'D' | 'W' | 'M' | 'Y'

offset_countinteger

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.

rrulestring

Recurrence rule for recurring scheduled messages, e.g. 'FREQ=MONTHLY' or 'FREQ=WEEKLY;INTERVAL=2'; see RFC2445.

end_timeinteger nullable

Time after which recurring messages will stop (not applicable to non-recurring scheduled messages)

timezone_idstring

Timezone ID used to compute times for recurring messages; see List of tz database time zones Wikipedia article.

recipients_strstring

A string with a human readable description of the recipient

group_idstring

ID of the group to send the message to (null if the recipient is an individual contact)

contact_idstring

ID of the contact to send the message to (null if the recipient is a group)

to_numberstring

Phone number to send the message to (null if the recipient is a group)

route_idstring

ID of the phone or route the message will be sent from

service_idstring

The service associated with this message (for voice calls, the service defines the call flow)

audio_urlstring

For voice calls, the URL of an MP3 file to play when the contact answers the call

For voice calls, the language of the text-to-speech voice

tts_voice'female' | 'male'

For voice calls, the text-to-speech voice

Type of scheduled message

time_createdinteger

Time the relative scheduled message was created in Telerivet

replace_variablesboolean

Set to true if Telerivet will render variables like [[contact.name]] in the message content, false otherwise

track_clicksboolean

If true, URLs in the message content will automatically be replaced with unique short URLs

route_paramsobject 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.

varsobject

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_idsstring

IDs of labels to add to the Message

project_idstring

ID of the project this relative scheduled message belongs to

Example response

{
  "id": "SEfaf2411ed3584f08",
  "content": "hello world!",
  "time_of_day": "15:07",
  "date_variable": "date",
  "offset_scale": "D",
  "offset_count": 3,
  "rrule": "COUNT=1",
  "timezone_id": "America/Los_Angeles",
  "recipients_str": "Subscribers",
  "route_id": "PN4d246818d0ecd1fa",
  "service_id": "SV3d246818d0e3d1fb",
  "message_type": "sms",
  "time_created": 1395617416,
  "project_id": "PJ2ad0100821a98bea"
}

Changes

No recorded changes to this operation across all 1 revision of this API.