Campaign

Create a campaign

Creates a new draft campaign, without sending it.

post/v1/projects/{project_id}/campaigns

Request

  • Base URL: https://api.telerivet.com
  • URL: https://api.telerivet.com/v1/projects/{project_id}/campaigns
  • 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

campaign_type'broadcast_text' | 'broadcast_call' | 'broadcast_svc' | 'relative' | 'anniversary' required

Type of campaign to create

namestring

Name of the campaign

group_idstring

ID of the group of contacts to send the campaign to

exclude_group_idstring

ID of a group of contacts to exclude from this campaign

route_idstring

ID of the phone or route to send the campaign from

timezone_idstring

ID of the timezone to use for scheduling

label_idsstring

IDs of labels to apply to messages sent by this campaign

solution_idstring

ID of the solution that this campaign is part of, if any

respondent_group_idstring

ID of the group to add contacts to after they respond

clicked_group_idstring

ID of the group to add contacts to after they click a link

schedule_mode'immediate' | 'at_time'

Indicates whether the campaign should be sent immediately or at a future time (broadcast campaigns only). If schedule_time is set, schedule_mode is automatically set to at_time. If schedule_mode is set to immediate or null, schedule_time is automatically cleared.

Note that the campaign will not actually be sent or scheduled until the API method is called to send the campaign.

schedule_timeinteger

When the campaign is scheduled to be sent, as a UNIX timestamp (broadcast campaigns only). Setting this to a non-null value automatically sets schedule_mode to at_time.

Note that the campaign will not actually be scheduled until the API method is called to schedule the campaign.

contentstring

Text content of the message (broadcast_text campaigns), or the text-to-speech text for voice calls (broadcast_call campaigns). May contain variables like [[contact.name]].

(See available variables)

route_paramsobject

Route-specific parameters for the message (broadcast_text campaigns only). See Route-Specific Parameters.

track_clicksboolean

Whether to shorten links and track link clicks (broadcast_text campaigns only).

audio_urlstring

URL of an MP3 file to play for voice calls (broadcast_call campaigns only).

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'

Language for text-to-speech voice calls (broadcast_call campaigns only).

tts_voice'female' | 'male'

Voice for text-to-speech voice calls (broadcast_call campaigns only).

date_variablestring

Custom contact variable storing date or date/time values relative to which messages will be scheduled (relative and anniversary campaigns only).

To send messages relative to when each contact signs up or joins the group, use a date/time field that is set automatically when contacts are added to the campaign's group (the group's add_time_variable), and schedule the first message with a minute offset (offset_scale I) so that it is sent shortly after the contact joins, rather than at a fixed time_of_day. Minute offsets are not supported for date fields without a time.

varsobject

Custom variables and values to set for this campaign. 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.

Example request

{
  "campaign_type": "broadcast_text",
  "name": "My Campaign",
  "group_id": "CG1234567890abcdef",
  "route_id": "PN11586298d3412adf",
  "solution_id": "SO2ad0100821a98bea",
  "content": "Hello world"
}

Response

Successful response

idstring

ID of the campaign

namestring

Name of the campaign, which must be unique within the project. The campaign name is only visible within Telerivet, and does not appear in the messages sent to contacts.

campaign_type'broadcast_text' | 'broadcast_call' | 'broadcast_svc' | 'relative' | 'anniversary'

Type of the campaign. The following campaign types are available:

  • broadcast_text - Send a text message to a group of contacts
  • broadcast_call - Send a voice call to a group of contacts
  • broadcast_svc - Trigger a service for a group of contacts
  • relative - Send a series of messages over time relative to when each contact was added to a group
  • anniversary - Send messages on recurring dates (e.g. birthdays, anniversaries)
status'draft' | 'scheduled' | 'sent' | 'pending_review'

Current status of the campaign

group_idstring

ID of the group of contacts that the campaign will be sent to

exclude_group_idstring nullable

ID of a group of contacts to exclude from the campaign

route_idstring

ID of the phone or route used to send the campaign

broadcast_idstring nullable

ID of the most recent broadcast created by this campaign, if applicable

estimated_countinteger nullable

Estimated number of messages that will be sent in this campaign

message_countinteger nullable

Number of messages that have been sent in this campaign

respondent_group_idstring nullable

ID of a group to add contacts to after they respond to the campaign

clicked_group_idstring nullable

ID of a group to add contacts to after they click a link in the campaign

label_idsstring

List of IDs of labels applied to messages sent by this campaign

solution_idstring nullable

ID of the solution that this campaign belongs to, if any

schedule_mode'immediate' | 'at_time' nullable

Indicates whether the campaign should be sent immediately or at a future time (applies to broadcast campaign types). If schedule_time is set, schedule_mode is automatically set to at_time. If schedule_mode is set to immediate or null, schedule_time is automatically cleared.

Note that after setting schedule_mode to "immediate" on a campaign with the draft status, the campaign will not actually be sent until the API method is called to send the campaign.

schedule_timeinteger nullable

The time to send the campaign, as a UNIX timestamp (applies to broadcast campaign types). Setting this to a non-null value automatically sets schedule_mode to at_time.

Note that after setting schedule_time on a campaign with the draft status, the campaign will not actually be scheduled until the API method is called to schedule the campaign.

contentstring nullable

Text content of the message (applies to broadcast_text campaigns), or the text-to-speech text for voice calls (applies to broadcast_call campaigns). May contain variables like [[contact.name]].

(See available variables)

route_paramsobject nullable

Route-specific parameters for the message (applies to broadcast_text campaigns). See Route-Specific Parameters.

track_clicksboolean

Whether to shorten links and track link clicks (applies to broadcast_text campaigns).

audio_urlstring nullable

For voice calls, the URL of an MP3 file to play when the contact answers the call (applies to broadcast_call campaigns)

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 (applies to broadcast_call campaigns)

tts_voice'female' | 'male'

For voice calls, the text-to-speech voice (applies to broadcast_call campaigns)

service_idstring nullable

ID of the service associated with this campaign (applies to broadcast_call or broadcast_svc campaigns)

date_variablestring nullable

Custom contact variable storing date or date/time values relative to which messages will be scheduled (relative and anniversary campaigns only).

To send messages relative to when each contact signs up or joins the group, use a date/time field that is set automatically when contacts are added to the campaign's group (the group's add_time_variable), and schedule the first message with a minute offset (offset_scale I) so that it is sent shortly after the contact joins, rather than at a fixed time_of_day. Minute offsets are not supported for date fields without a time.

message_typestring nullable

Type of messages sent by this campaign, or null if not applicable

timezone_idstring nullable

The ID of the timezone used for scheduling messages in this campaign, or null to use the project's default timezone

time_createdinteger

Time the campaign was created in Telerivet

time_updatedinteger

Time the campaign was last updated in Telerivet

varsobject

Custom variables stored for this campaign. 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.

urlstring

URL to view the campaign in the Telerivet web app

url_editstring

URL to edit the campaign in the Telerivet web app

url_sendstring

URL to preview and send the campaign in the Telerivet web app

user_idstring

ID of the Telerivet user who created the campaign

project_idstring

ID of the project this campaign belongs to

Example response

{
  "id": "CM2ad0100821a98bea",
  "name": "Test Campaign",
  "campaign_type": "broadcast_text",
  "status": "draft",
  "group_id": "CG02139128391fa",
  "route_id": "RT2a586298d3412adf",
  "broadcast_id": "MB2489812e59c5c781",
  "estimated_count": 12942,
  "message_count": 8358,
  "solution_id": "SO2ad0100821a98bea",
  "schedule_mode": "immediate",
  "content": "Hello world",
  "service_id": "SV3d246818d0e3d1fb",
  "message_type": "sms",
  "timezone_id": "America/Los_Angeles",
  "time_created": 1390348075,
  "time_updated": 1390348075,
  "url": "https://telerivet.com/p/asdf/campaign/CM2ad0100821a98bea",
  "url_edit": "https://telerivet.com/p/asdf/campaign/CM2ad0100821a98bea/edit",
  "url_send": "https://telerivet.com/p/asdf/campaign/CM2ad0100821a98bea/preview",
  "user_id": "URba3e403e98f49735",
  "project_id": "PJ2ad0100821a98bea"
}

Changes

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