Class: Telerivet::Campaign

Inherits:
Entity
  • Object
show all
Defined in:
lib/telerivet/campaign.rb

Overview

A campaign is something that is sent to a group of contacts on a particular schedule.

Depending on the campaign type, a campaign may send a text message, make a voice call, or trigger an automated service. A campaign may either send a single broadcast at once, or send multiple broadcasts to different contacts over time.

Campaigns are initially created as a draft and can be edited and previewed before being sent. This supports a workflow where campaigns can be drafted via the API, and subsequently edited, approved, and sent via either the web app or the API. Once sent, a campaign creates one or more broadcasts to deliver messages to the target recipients.

Campaigns build on top of other core entity types including broadcasts and scheduled messages. Although it is possible to send broadcasts or schedule messages directly via the API, campaigns can be used in order to provide the ability to save drafts, allow manual editing and approval before sending, or to organize broadcasts within Telerivet.

Fields:

- id (string, max 34 characters)
  * ID of the campaign
  * Read-only

- name
  * 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.
  * Updatable via API

- campaign_type
  * 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)
  * Allowed values: broadcast_text, broadcast_call, broadcast_svc, relative, anniversary
  * Read-only

- status
  * Current status of the campaign
  * Allowed values: draft, scheduled, sent, pending_review
  * Read-only

- group_id
  * ID of the group of contacts that the campaign will be sent to
  * Updatable via API

- exclude_group_id
  * ID of a group of contacts to exclude from the campaign
  * Updatable via API

- route_id
  * ID of the phone or route used to send the campaign
  * Updatable via API

- broadcast_id
  * ID of the most recent broadcast created by this campaign, if applicable
  * Read-only

- estimated_count (int)
  * Estimated number of messages that will be sent in this campaign
  * Read-only

- message_count (int)
  * Number of messages that have been sent in this campaign
  * Read-only

- respondent_group_id
  * ID of a group to add contacts to after they respond to the campaign
  * Updatable via API

- clicked_group_id
  * ID of a group to add contacts to after they click a link in the campaign
  * Updatable via API

- label_ids (array)
  * List of IDs of labels applied to messages sent by this campaign
  * Updatable via API

- schedule_mode
  * 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](#Campaign.send).
  * Allowed values: immediate, at_time
  * Updatable via API

- schedule_time (UNIX timestamp)
  * 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](#Campaign.send).
  * Updatable via API

- content (string)
  * 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)](#variables)
  * Updatable via API

- media (array)
  * Array of media attachments (applies to `broadcast_text` campaigns).
  * Read-only

- route_params (Hash)
  * Route-specific parameters for the message (applies to `broadcast_text` campaigns).
      See [Route-Specific Parameters](#route_params).
  * Updatable via API

- track_clicks (boolean)
  * Whether to shorten links and track link clicks (applies to `broadcast_text`
      campaigns).
  * Updatable via API

- short_link_params (Hash)
  * Parameters for short links when `track_clicks` is enabled (applies to
      `broadcast_text` campaigns).
  * Updatable via API

- audio_url
  * For voice calls, the URL of an MP3 file to play when the contact answers the call
      (applies to `broadcast_call` campaigns)
  * Updatable via API

- tts_lang
  * For voice calls, the language of the text-to-speech voice (applies to
      `broadcast_call` campaigns)
  * Allowed values: 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
  * Updatable via API

- tts_voice
  * For voice calls, the text-to-speech voice (applies to `broadcast_call` campaigns)
  * Allowed values: female, male
  * Updatable via API

- service_id
  * ID of the service associated with this campaign (applies to `broadcast_call` or
      `broadcast_svc` campaigns)
  * Read-only

- date_variable
  * Custom contact variable storing date or date/time values relative to which messages
      will be scheduled (applies to `relative` and `anniversary` campaigns)
  * Updatable via API

- items (array)
  * Array of campaign items (applies to `relative` and `anniversary` campaigns). Each
      item defines a scheduled message with timing and content.
  * Updatable via API

- message_type
  * Type of messages sent by this campaign, or null if not applicable
  * Read-only

- timezone_id
  * The ID of the timezone used for scheduling messages in this campaign, or null to use
      the project's default timezone
  * Updatable via API

- time_created (UNIX timestamp)
  * Time the campaign was created in Telerivet
  * Read-only

- time_updated (UNIX timestamp)
  * Time the campaign was last updated in Telerivet
  * Read-only

- vars (Hash)
  * 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.
  * Updatable via API

- url
  * URL to view the campaign in the Telerivet web app
  * Read-only

- url_edit
  * URL to edit the campaign in the Telerivet web app
  * Read-only

- url_send
  * URL to preview and send the campaign in the Telerivet web app
  * Read-only

- user_id
  * ID of the Telerivet user who created the campaign
  * Read-only

- project_id
  * ID of the project this campaign belongs to
  * Read-only

Instance Method Summary collapse

Methods inherited from Entity

#get, #initialize, #load, #set, #set_data, #to_s, #vars

Constructor Details

This class inherits a constructor from Telerivet::Entity

Instance Method Details

#audio_url ⇒ Object 



391
392
393
 
# File 'lib/telerivet/campaign.rb', line 391

def audio_url
    get('audio_url')
end

#audio_url=(value) ⇒ Object 



395
396
397
 
# File 'lib/telerivet/campaign.rb', line 395

def audio_url=(value)
    set('audio_url', value)
end

#broadcast_id ⇒ Object 



303
304
305
 
# File 'lib/telerivet/campaign.rb', line 303

def broadcast_id
    get('broadcast_id')
end

#campaign_type ⇒ Object 



271
272
273
 
# File 'lib/telerivet/campaign.rb', line 271

def campaign_type
    get('campaign_type')
end

#clicked_group_id ⇒ Object 



323
324
325
 
# File 'lib/telerivet/campaign.rb', line 323

def clicked_group_id
    get('clicked_group_id')
end

#clicked_group_id=(value) ⇒ Object 



327
328
329
 
# File 'lib/telerivet/campaign.rb', line 327

def clicked_group_id=(value)
    set('clicked_group_id', value)
end

#content ⇒ Object 



355
356
357
 
# File 'lib/telerivet/campaign.rb', line 355

def content
    get('content')
end

#content=(value) ⇒ Object 



359
360
361
 
# File 'lib/telerivet/campaign.rb', line 359

def content=(value)
    set('content', value)
end

#date_variable ⇒ Object 



419
420
421
 
# File 'lib/telerivet/campaign.rb', line 419

def date_variable
    get('date_variable')
end

#date_variable=(value) ⇒ Object 



423
424
425
 
# File 'lib/telerivet/campaign.rb', line 423

def date_variable=(value)
    set('date_variable', value)
end

#delete ⇒ Object

Deletes this campaign. Any scheduled messages will be cancelled.



255
256
257
 
# File 'lib/telerivet/campaign.rb', line 255

def delete()
    @api.do_request("DELETE", get_base_api_path())
end

#estimated_count ⇒ Object 



307
308
309
 
# File 'lib/telerivet/campaign.rb', line 307

def estimated_count
    get('estimated_count')
end

#exclude_group_id ⇒ Object 



287
288
289
 
# File 'lib/telerivet/campaign.rb', line 287

def exclude_group_id
    get('exclude_group_id')
end

#exclude_group_id=(value) ⇒ Object 



291
292
293
 
# File 'lib/telerivet/campaign.rb', line 291

def exclude_group_id=(value)
    set('exclude_group_id', value)
end

#get_base_api_path ⇒ Object 



475
476
477
 
# File 'lib/telerivet/campaign.rb', line 475

def get_base_api_path()
    "/projects/#{get('project_id')}/campaigns/#{get('id')}"
end

#group_id ⇒ Object 



279
280
281
 
# File 'lib/telerivet/campaign.rb', line 279

def group_id
    get('group_id')
end

#group_id=(value) ⇒ Object 



283
284
285
 
# File 'lib/telerivet/campaign.rb', line 283

def group_id=(value)
    set('group_id', value)
end

#id ⇒ Object 



259
260
261
 
# File 'lib/telerivet/campaign.rb', line 259

def id
    get('id')
end

#items ⇒ Object 



427
428
429
 
# File 'lib/telerivet/campaign.rb', line 427

def items
    get('items')
end

#items=(value) ⇒ Object 



431
432
433
 
# File 'lib/telerivet/campaign.rb', line 431

def items=(value)
    set('items', value)
end

#label_ids ⇒ Object 



331
332
333
 
# File 'lib/telerivet/campaign.rb', line 331

def label_ids
    get('label_ids')
end

#label_ids=(value) ⇒ Object 



335
336
337
 
# File 'lib/telerivet/campaign.rb', line 335

def label_ids=(value)
    set('label_ids', value)
end

#media ⇒ Object 



363
364
365
 
# File 'lib/telerivet/campaign.rb', line 363

def media
    get('media')
end

#message_count ⇒ Object 



311
312
313
 
# File 'lib/telerivet/campaign.rb', line 311

def message_count
    get('message_count')
end

#message_type ⇒ Object 



435
436
437
 
# File 'lib/telerivet/campaign.rb', line 435

def message_type
    get('message_type')
end

#name ⇒ Object 



263
264
265
 
# File 'lib/telerivet/campaign.rb', line 263

def name
    get('name')
end

#name=(value) ⇒ Object 



267
268
269
 
# File 'lib/telerivet/campaign.rb', line 267

def name=(value)
    set('name', value)
end

#project_id ⇒ Object 



471
472
473
 
# File 'lib/telerivet/campaign.rb', line 471

def project_id
    get('project_id')
end

#respondent_group_id ⇒ Object 



315
316
317
 
# File 'lib/telerivet/campaign.rb', line 315

def respondent_group_id
    get('respondent_group_id')
end

#respondent_group_id=(value) ⇒ Object 



319
320
321
 
# File 'lib/telerivet/campaign.rb', line 319

def respondent_group_id=(value)
    set('respondent_group_id', value)
end

#route_id ⇒ Object 



295
296
297
 
# File 'lib/telerivet/campaign.rb', line 295

def route_id
    get('route_id')
end

#route_id=(value) ⇒ Object 



299
300
301
 
# File 'lib/telerivet/campaign.rb', line 299

def route_id=(value)
    set('route_id', value)
end

#route_params ⇒ Object 



367
368
369
 
# File 'lib/telerivet/campaign.rb', line 367

def route_params
    get('route_params')
end

#route_params=(value) ⇒ Object 



371
372
373
 
# File 'lib/telerivet/campaign.rb', line 371

def route_params=(value)
    set('route_params', value)
end

#save ⇒ Object

Saves any fields or custom variables that have changed for this campaign.



217
218
219
 
# File 'lib/telerivet/campaign.rb', line 217

def save()
    super
end

#schedule_mode ⇒ Object 



339
340
341
 
# File 'lib/telerivet/campaign.rb', line 339

def schedule_mode
    get('schedule_mode')
end

#schedule_mode=(value) ⇒ Object 



343
344
345
 
# File 'lib/telerivet/campaign.rb', line 343

def schedule_mode=(value)
    set('schedule_mode', value)
end

#schedule_time ⇒ Object 



347
348
349
 
# File 'lib/telerivet/campaign.rb', line 347

def schedule_time
    get('schedule_time')
end

#schedule_time=(value) ⇒ Object 



351
352
353
 
# File 'lib/telerivet/campaign.rb', line 351

def schedule_time=(value)
    set('schedule_time', value)
end

#send ⇒ Object

Sends or schedules this campaign. The campaign must be in the draft or scheduled status, and must be fully configured (e.g. with a group, route, and message content).

For broadcast campaigns, this will send the campaign immediately if the campaign's schedule_mode is immediate. If schedule_mode is at_time, it will schedule the campaign to be sent at the time of the schedule_time timestamp.

For relative and anniversary campaigns, this will schedule the campaign according to the configuration in the items and date_variable properties.

Returns: Telerivet::Campaign



235
236
237
238
 
# File 'lib/telerivet/campaign.rb', line 235

def send()
    require_relative 'campaign'
    Campaign.new(@api, @api.do_request("POST", get_base_api_path() + "/send"))
end

#service_id ⇒ Object 



415
416
417
 
# File 'lib/telerivet/campaign.rb', line 415

def service_id
    get('service_id')
end

#short_link_params ⇒ Object 



383
384
385
 
# File 'lib/telerivet/campaign.rb', line 383

def short_link_params
    get('short_link_params')
end

#short_link_params=(value) ⇒ Object 



387
388
389
 
# File 'lib/telerivet/campaign.rb', line 387

def short_link_params=(value)
    set('short_link_params', value)
end

#status ⇒ Object 



275
276
277
 
# File 'lib/telerivet/campaign.rb', line 275

def status
    get('status')
end

#time_created ⇒ Object 



447
448
449
 
# File 'lib/telerivet/campaign.rb', line 447

def time_created
    get('time_created')
end

#time_updated ⇒ Object 



451
452
453
 
# File 'lib/telerivet/campaign.rb', line 451

def time_updated
    get('time_updated')
end

#timezone_id ⇒ Object 



439
440
441
 
# File 'lib/telerivet/campaign.rb', line 439

def timezone_id
    get('timezone_id')
end

#timezone_id=(value) ⇒ Object 



443
444
445
 
# File 'lib/telerivet/campaign.rb', line 443

def timezone_id=(value)
    set('timezone_id', value)
end

#track_clicks ⇒ Object 



375
376
377
 
# File 'lib/telerivet/campaign.rb', line 375

def track_clicks
    get('track_clicks')
end

#track_clicks=(value) ⇒ Object 



379
380
381
 
# File 'lib/telerivet/campaign.rb', line 379

def track_clicks=(value)
    set('track_clicks', value)
end

#tts_lang ⇒ Object 



399
400
401
 
# File 'lib/telerivet/campaign.rb', line 399

def tts_lang
    get('tts_lang')
end

#tts_lang=(value) ⇒ Object 



403
404
405
 
# File 'lib/telerivet/campaign.rb', line 403

def tts_lang=(value)
    set('tts_lang', value)
end

#tts_voice ⇒ Object 



407
408
409
 
# File 'lib/telerivet/campaign.rb', line 407

def tts_voice
    get('tts_voice')
end

#tts_voice=(value) ⇒ Object 



411
412
413
 
# File 'lib/telerivet/campaign.rb', line 411

def tts_voice=(value)
    set('tts_voice', value)
end

#unschedule ⇒ Object

Cancels a scheduled campaign, reverting it to the draft status. The campaign must be in the scheduled or pending_review status.

Returns: Telerivet::Campaign



247
248
249
250
 
# File 'lib/telerivet/campaign.rb', line 247

def unschedule()
    require_relative 'campaign'
    Campaign.new(@api, @api.do_request("POST", get_base_api_path() + "/unschedule"))
end

#url ⇒ Object 



455
456
457
 
# File 'lib/telerivet/campaign.rb', line 455

def url
    get('url')
end

#url_edit ⇒ Object 



459
460
461
 
# File 'lib/telerivet/campaign.rb', line 459

def url_edit
    get('url_edit')
end

#url_send ⇒ Object 



463
464
465
 
# File 'lib/telerivet/campaign.rb', line 463

def url_send
    get('url_send')
end

#user_id ⇒ Object 



467
468
469
 
# File 'lib/telerivet/campaign.rb', line 467

def user_id
    get('user_id')
end