Class: Telerivet::Project

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

Overview

Represents a Telerivet project.

Provides methods for sending and scheduling messages, as well as accessing, creating and updating a variety of entities, including contacts, messages, scheduled messages, groups, labels, phones, services, and data tables.

Fields:

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

- name
    * Name of the project
    * Updatable via API

- timezone_id
    * Default TZ database timezone ID; see
        <http://en.wikipedia.org/wiki/List_of_tz_database_time_zones>
    * Read-only

- vars (Hash)
    * Custom variables stored for this project
    * Updatable via API

Instance Method Summary collapse

Methods inherited from Entity

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

Constructor Details

This class inherits a constructor from Telerivet::Entity

Instance Method Details

#get_base_api_path ⇒ Object 



913
914
915
 
# File 'lib/telerivet/project.rb', line 913

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

#get_contact_by_id(id) ⇒ Object

Retrieves the contact with the given ID.

Note: This does not make any API requests until you access a property of the Contact.

Arguments:

- id
    * ID of the contact
    * Required

Returns:

Telerivet::Contact



324
325
326
327
 
# File 'lib/telerivet/project.rb', line 324

def get_contact_by_id(id)
    require_relative 'contact'
    return Contact.new(@api, {'project_id' => self.id, 'id' => id}, false)
end

#get_data_table_by_id(id) ⇒ Object

Retrieves the data table with the given ID.

Note: This does not make any API requests until you access a property of the DataTable.

Arguments:

- id
    * ID of the data table
    * Required

Returns:

Telerivet::DataTable



685
686
687
688
 
# File 'lib/telerivet/project.rb', line 685

def get_data_table_by_id(id)
    require_relative 'datatable'
    return DataTable.new(@api, {'project_id' => self.id, 'id' => id}, false)
end

#get_group_by_id(id) ⇒ Object

Retrieves the group with the given ID.

Note: This does not make any API requests until you access a property of the Group.

Arguments:

- id
    * ID of the group
    * Required

Returns:

Telerivet::Group



543
544
545
546
 
# File 'lib/telerivet/project.rb', line 543

def get_group_by_id(id)
    require_relative 'group'
    return Group.new(@api, {'project_id' => self.id, 'id' => id}, false)
end

#get_label_by_id(id) ⇒ Object

Retrieves the label with the given ID.

Note: This does not make any API requests until you access a property of the Label.

Arguments:

- id
    * ID of the label
    * Required

Returns:

Telerivet::Label



614
615
616
617
 
# File 'lib/telerivet/project.rb', line 614

def get_label_by_id(id)
    require_relative 'label'
    return Label.new(@api, {'project_id' => self.id, 'id' => id}, false)
end

#get_message_by_id(id) ⇒ Object

Retrieves the message with the given ID.

Note: This does not make any API requests until you access a property of the Message.

Arguments:

- id
    * ID of the message
    * Required

Returns:

Telerivet::Message



472
473
474
475
 
# File 'lib/telerivet/project.rb', line 472

def get_message_by_id(id)
    require_relative 'message'
    return Message.new(@api, {'project_id' => self.id, 'id' => id}, false)
end

#get_or_create_contact(options) ⇒ Object

Retrieves OR creates and possibly updates a contact by name or phone number.

If a phone number is provided, Telerivet will search for an existing contact with that phone number (including suffix matches to allow finding contacts with phone numbers in a different format).

If a phone number is not provided but a name is provided, Telerivet will search for a contact with that exact name (case insensitive).

If no existing contact is found, a new contact will be created.

Then that contact will be updated with any parameters provided (name, phone_number, and vars).

Arguments:

- options (Hash)
    * Required

  - name
      * Name of the contact
      * Required if phone_number not set

  - phone_number
      * Phone number of the contact
      * Required if name not set

  - vars (Hash)
      * Custom variables and values to update on the contact

Returns:

Telerivet::Contact



248
249
250
251
 
# File 'lib/telerivet/project.rb', line 248

def get_or_create_contact(options)
    require_relative 'contact'
    Contact.new(@api, @api.do_request("POST", get_base_api_path() + "/contacts", options))
end

#get_or_create_data_table(name) ⇒ Object

Gets or creates a data table by name.

Arguments:

- name
    * Name of the data table
    * Required

Returns:

Telerivet::DataTable



667
668
669
670
 
# File 'lib/telerivet/project.rb', line 667

def get_or_create_data_table(name)
    require_relative 'datatable'
    DataTable.new(@api, @api.do_request("POST", get_base_api_path() + "/tables", {'name' => name}))
end

#get_or_create_group(name) ⇒ Object

Retrieves or creates a group by name.

Arguments:

- name
    * Name of the group
    * Required

Returns:

Telerivet::Group



525
526
527
528
 
# File 'lib/telerivet/project.rb', line 525

def get_or_create_group(name)
    require_relative 'group'
    Group.new(@api, @api.do_request("POST", get_base_api_path() + "/groups", {'name' => name}))
end

#get_or_create_label(name) ⇒ Object

Gets or creates a label by name.

Arguments:

- name
    * Name of the label
    * Required

Returns:

Telerivet::Label



596
597
598
599
 
# File 'lib/telerivet/project.rb', line 596

def get_or_create_label(name)
    require_relative 'label'
    Label.new(@api, @api.do_request("POST", get_base_api_path() + "/labels", {'name' => name}))
end

#get_phone_by_id(id) ⇒ Object

Retrieves the phone with the given ID.

Note: This does not make any API requests until you access a property of the Phone.

Arguments:

- id
    * ID of the phone - see <https://telerivet.com/dashboard/api>
    * Required

Returns:

Telerivet::Phone



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

def get_phone_by_id(id)
    require_relative 'phone'
    return Phone.new(@api, {'project_id' => self.id, 'id' => id}, false)
end

#get_receipt_by_id(id) ⇒ Object

Retrieves the mobile money receipt with the given ID.

Note: This does not make any API requests until you access a property of the MobileMoneyReceipt.

Arguments:

- id
    * ID of the mobile money receipt
    * Required

Returns:

Telerivet::MobileMoneyReceipt



885
886
887
888
 
# File 'lib/telerivet/project.rb', line 885

def get_receipt_by_id(id)
    require_relative 'mobilemoneyreceipt'
    return MobileMoneyReceipt.new(@api, {'project_id' => self.id, 'id' => id}, false)
end

#get_scheduled_message_by_id(id) ⇒ Object

Retrieves the scheduled message with the given ID.

Note: This does not make any API requests until you access a property of the ScheduledMessage.

Arguments:

- id
    * ID of the scheduled message
    * Required

Returns:

Telerivet::ScheduledMessage



749
750
751
752
 
# File 'lib/telerivet/project.rb', line 749

def get_scheduled_message_by_id(id)
    require_relative 'scheduledmessage'
    return ScheduledMessage.new(@api, {'project_id' => self.id, 'id' => id}, false)
end

#get_service_by_id(id) ⇒ Object

Retrieves the service with the given ID.

Note: This does not make any API requests until you access a property of the Service.

Arguments:

- id
    * ID of the service
    * Required

Returns:

Telerivet::Service



811
812
813
814
 
# File 'lib/telerivet/project.rb', line 811

def get_service_by_id(id)
    require_relative 'service'
    return Service.new(@api, {'project_id' => self.id, 'id' => id}, false)
end

#id ⇒ Object 



897
898
899
 
# File 'lib/telerivet/project.rb', line 897

def id
    get('id')
end

#name ⇒ Object 



901
902
903
 
# File 'lib/telerivet/project.rb', line 901

def name
    get('name')
end

#name=(value) ⇒ Object 



905
906
907
 
# File 'lib/telerivet/project.rb', line 905

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

#query_contacts(options = nil) ⇒ Object

Queries contacts within the given project.

Arguments:

- options (Hash)

  - name
      * Filter contacts by name
      * Allowed modifiers: name[ne], name[prefix], name[not_prefix], name[gte], name[gt],
          name[lt], name[lte]

  - phone_number
      * Filter contacts by phone number
      * Allowed modifiers: phone_number[ne], phone_number[prefix],
          phone_number[not_prefix], phone_number[gte], phone_number[gt], phone_number[lt],
          phone_number[lte]

  - time_created (UNIX timestamp)
      * Filter contacts by time created
      * Allowed modifiers: time_created[ne], time_created[min], time_created[max]

  - last_message_time (UNIX timestamp)
      * Filter contacts by last time a message was sent or received
      * Allowed modifiers: last_message_time[exists], last_message_time[ne],
          last_message_time[min], last_message_time[max]

  - vars (Hash)
      * Filter contacts by value of a custom variable (e.g. vars[email], vars[foo], etc.)
      * Allowed modifiers: vars[foo][exists], vars[foo][ne], vars[foo][prefix],
          vars[foo][not_prefix], vars[foo][gte], vars[foo][gt], vars[foo][lt], vars[foo][lte],
          vars[foo][min], vars[foo][max]

  - sort
      * Sort the results based on a field
      * Allowed values: default, name, phone_number, last_message_time
      * Default: default

  - sort_dir
      * Sort the results in ascending or descending order
      * Allowed values: asc, desc
      * Default: asc

  - page_size (int)
      * Number of results returned per page (max 200)
      * Default: 50

  - offset (int)
      * Number of items to skip from beginning of result set
      * Default: 0

Returns:

Telerivet::APICursor (of Telerivet::Contact)



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

def query_contacts(options = nil)
    require_relative 'contact'
    @api.cursor(Contact, get_base_api_path() + "/contacts", options)
end

#query_data_tables(options = nil) ⇒ Object

Queries data tables within the given project.

Arguments:

- options (Hash)

  - name
      * Filter data tables by name
      * Allowed modifiers: name[ne], name[prefix], name[not_prefix], name[gte], name[gt],
          name[lt], name[lte]

  - sort
      * Sort the results based on a field
      * Allowed values: default, name
      * Default: default

  - sort_dir
      * Sort the results in ascending or descending order
      * Allowed values: asc, desc
      * Default: asc

  - page_size (int)
      * Number of results returned per page (max 200)
      * Default: 50

  - offset (int)
      * Number of items to skip from beginning of result set
      * Default: 0

Returns:

Telerivet::APICursor (of Telerivet::DataTable)



651
652
653
654
 
# File 'lib/telerivet/project.rb', line 651

def query_data_tables(options = nil)
    require_relative 'datatable'
    @api.cursor(DataTable, get_base_api_path() + "/tables", options)
end

#query_groups(options = nil) ⇒ Object

Queries groups within the given project.

Arguments:

- options (Hash)

  - name
      * Filter groups by name
      * Allowed modifiers: name[ne], name[prefix], name[not_prefix], name[gte], name[gt],
          name[lt], name[lte]

  - sort
      * Sort the results based on a field
      * Allowed values: default, name
      * Default: default

  - sort_dir
      * Sort the results in ascending or descending order
      * Allowed values: asc, desc
      * Default: asc

  - page_size (int)
      * Number of results returned per page (max 200)
      * Default: 50

  - offset (int)
      * Number of items to skip from beginning of result set
      * Default: 0

Returns:

Telerivet::APICursor (of Telerivet::Group)



509
510
511
512
 
# File 'lib/telerivet/project.rb', line 509

def query_groups(options = nil)
    require_relative 'group'
    @api.cursor(Group, get_base_api_path() + "/groups", options)
end

#query_labels(options = nil) ⇒ Object

Queries labels within the given project.

Arguments:

- options (Hash)

  - name
      * Filter labels by name
      * Allowed modifiers: name[ne], name[prefix], name[not_prefix], name[gte], name[gt],
          name[lt], name[lte]

  - sort
      * Sort the results based on a field
      * Allowed values: default, name
      * Default: default

  - sort_dir
      * Sort the results in ascending or descending order
      * Allowed values: asc, desc
      * Default: asc

  - page_size (int)
      * Number of results returned per page (max 200)
      * Default: 50

  - offset (int)
      * Number of items to skip from beginning of result set
      * Default: 0

Returns:

Telerivet::APICursor (of Telerivet::Label)



580
581
582
583
 
# File 'lib/telerivet/project.rb', line 580

def query_labels(options = nil)
    require_relative 'label'
    @api.cursor(Label, get_base_api_path() + "/labels", options)
end

#query_messages(options = nil) ⇒ Object

Queries messages within the given project.

Arguments:

- options (Hash)

  - direction
      * Filter messages by direction
      * Allowed values: incoming, outgoing

  - message_type
      * Filter messages by message_type
      * Allowed values: sms, mms, ussd, call

  - source
      * Filter messages by source
      * Allowed values: phone, provider, web, api, service, webhook, scheduled

  - starred (bool)
      * Filter messages by starred/unstarred

  - status
      * Filter messages by status
      * Allowed values: ignored, processing, received, sent, queued, failed,
          failed_queued, cancelled, delivered, not_delivered

  - time_created[min] (UNIX timestamp)
      * Filter messages created on or after a particular time

  - time_created[max] (UNIX timestamp)
      * Filter messages created before a particular time

  - contact_id
      * ID of the contact who sent/received the message

  - phone_id
      * ID of the phone that sent/received the message

  - sort
      * Sort the results based on a field
      * Allowed values: default
      * Default: default

  - sort_dir
      * Sort the results in ascending or descending order
      * Allowed values: asc, desc
      * Default: asc

  - page_size (int)
      * Number of results returned per page (max 200)
      * Default: 50

  - offset (int)
      * Number of items to skip from beginning of result set
      * Default: 0

Returns:

Telerivet::APICursor (of Telerivet::Message)



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

def query_messages(options = nil)
    require_relative 'message'
    @api.cursor(Message, get_base_api_path() + "/messages", options)
end

#query_phones(options = nil) ⇒ Object

Queries phones within the given project.

Arguments:

- options (Hash)

  - name
      * Filter phones by name
      * Allowed modifiers: name[ne], name[prefix], name[not_prefix], name[gte], name[gt],
          name[lt], name[lte]

  - phone_number
      * Filter phones by phone number
      * Allowed modifiers: phone_number[ne], phone_number[prefix],
          phone_number[not_prefix], phone_number[gte], phone_number[gt], phone_number[lt],
          phone_number[lte]

  - last_active_time (UNIX timestamp)
      * Filter phones by last active time
      * Allowed modifiers: last_active_time[exists], last_active_time[ne],
          last_active_time[min], last_active_time[max]

  - sort
      * Sort the results based on a field
      * Allowed values: default, name, phone_number
      * Default: default

  - sort_dir
      * Sort the results in ascending or descending order
      * Allowed values: asc, desc
      * Default: asc

  - page_size (int)
      * Number of results returned per page (max 200)
      * Default: 50

  - offset (int)
      * Number of items to skip from beginning of result set
      * Default: 0

Returns:

Telerivet::APICursor (of Telerivet::Phone)



372
373
374
375
 
# File 'lib/telerivet/project.rb', line 372

def query_phones(options = nil)
    require_relative 'phone'
    @api.cursor(Phone, get_base_api_path() + "/phones", options)
end

#query_receipts(options = nil) ⇒ Object

Queries mobile money receipts within the given project.

Arguments:

- options (Hash)

  - tx_id
      * Filter receipts by transaction ID

  - tx_type
      * Filter receipts by transaction type
      * Allowed values: receive_money, send_money, pay_bill, deposit, withdrawal,
          airtime_purchase, balance_inquiry, reversal

  - tx_time (UNIX timestamp)
      * Filter receipts by transaction time
      * Allowed modifiers: tx_time[ne], tx_time[min], tx_time[max]

  - name
      * Filter receipts by other person's name
      * Allowed modifiers: name[ne], name[prefix], name[not_prefix], name[gte], name[gt],
          name[lt], name[lte]

  - phone_number
      * Filter receipts by other person's phone number
      * Allowed modifiers: phone_number[ne], phone_number[prefix],
          phone_number[not_prefix], phone_number[gte], phone_number[gt], phone_number[lt],
          phone_number[lte]

  - sort
      * Sort the results based on a field
      * Allowed values: default
      * Default: default

  - sort_dir
      * Sort the results in ascending or descending order
      * Allowed values: asc, desc
      * Default: asc

  - page_size (int)
      * Number of results returned per page (max 200)
      * Default: 50

  - offset (int)
      * Number of items to skip from beginning of result set
      * Default: 0

Returns:

Telerivet::APICursor (of Telerivet::MobileMoneyReceipt)



866
867
868
869
 
# File 'lib/telerivet/project.rb', line 866

def query_receipts(options = nil)
    require_relative 'mobilemoneyreceipt'
    @api.cursor(MobileMoneyReceipt, get_base_api_path() + "/receipts", options)
end

#query_scheduled_messages(options = nil) ⇒ Object

Queries scheduled messages within the given project.

Arguments:

- options (Hash)

  - message_type
      * Filter scheduled messages by message_type
      * Allowed values: sms, mms, ussd, call

  - time_created (UNIX timestamp)
      * Filter scheduled messages by time_created
      * Allowed modifiers: time_created[ne], time_created[min], time_created[max]

  - next_time (UNIX timestamp)
      * Filter scheduled messages by next_time
      * Allowed modifiers: next_time[exists], next_time[ne], next_time[min],
          next_time[max]

  - sort
      * Sort the results based on a field
      * Allowed values: default, name
      * Default: default

  - sort_dir
      * Sort the results in ascending or descending order
      * Allowed values: asc, desc
      * Default: asc

  - page_size (int)
      * Number of results returned per page (max 200)
      * Default: 50

  - offset (int)
      * Number of items to skip from beginning of result set
      * Default: 0

Returns:

Telerivet::APICursor (of Telerivet::ScheduledMessage)



730
731
732
733
 
# File 'lib/telerivet/project.rb', line 730

def query_scheduled_messages(options = nil)
    require_relative 'scheduledmessage'
    @api.cursor(ScheduledMessage, get_base_api_path() + "/scheduled", options)
end

#query_services(options = nil) ⇒ Object

Queries services within the given project.

Arguments:

- options (Hash)

  - name
      * Filter services by name
      * Allowed modifiers: name[ne], name[prefix], name[not_prefix], name[gte], name[gt],
          name[lt], name[lte]

  - active (bool)
      * Filter services by active/inactive state

  - context
      * Filter services that can be invoked in a particular context
      * Allowed values: message, contact, project, receipt

  - sort
      * Sort the results based on a field
      * Allowed values: default, priority, name
      * Default: default

  - sort_dir
      * Sort the results in ascending or descending order
      * Allowed values: asc, desc
      * Default: asc

  - page_size (int)
      * Number of results returned per page (max 200)
      * Default: 50

  - offset (int)
      * Number of items to skip from beginning of result set
      * Default: 0

Returns:

Telerivet::APICursor (of Telerivet::Service)



793
794
795
796
 
# File 'lib/telerivet/project.rb', line 793

def query_services(options = nil)
    require_relative 'service'
    @api.cursor(Service, get_base_api_path() + "/services", options)
end

#save ⇒ Object

Saves any fields or custom variables that have changed for the project.



893
894
895
 
# File 'lib/telerivet/project.rb', line 893

def save()
    super
end

#schedule_message(options) ⇒ Object

Schedules an SMS message to a group or single contact. Note that Telerivet only sends scheduled messages approximately once per minute, so it is not possible to control the exact second at which a scheduled message is sent.

Arguments:

- options (Hash)
    * Required

  - content
      * Content of the message to schedule
      * Required

  - group_id
      * ID of the group to send the message to
      * Required if to_number not set

  - to_number (string)
      * Phone number to send the message to
      * Required if group_id not set

  - start_time (UNIX timestamp)
      * The time that the message will be sent (or first sent for recurring messages)
      * Required if start_time_offset not set

  - start_time_offset (int)
      * Number of seconds from now until the message is sent
      * Required if start_time not set

  - rrule
      * 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).
      * Default: COUNT=1 (one-time scheduled message, does not repeat)

  - route_id
      * ID of the phone or route to send the message from
      * Default: default sender phone ID

  - message_type
      * Type of message to send
      * Allowed values: sms, ussd
      * Default: sms

  - is_template (bool)
      * Set to true to evaluate variables like [[contact.name]] in message content
      * Default: false

  - label_ids (array)
      * Array of IDs of labels to add to the sent messages (maximum 5)

  - timezone_id
      * TZ database timezone ID; see
          <http://en.wikipedia.org/wiki/List_of_tz_database_time_zones>
      * Default: project default timezone

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

  - end_time_offset (int)
      * Number of seconds from now until the recurring message will stop

Returns:

Telerivet::ScheduledMessage



210
211
212
213
 
# File 'lib/telerivet/project.rb', line 210

def schedule_message(options)
    require_relative 'scheduledmessage'
    ScheduledMessage.new(@api, @api.do_request("POST", get_base_api_path() + "/scheduled", options))
end

#send_message(options) ⇒ Object

Sends one message (SMS or USSD request).

Arguments:

- options (Hash)
    * Required

  - content
      * Content of the message to send
      * Required if sending SMS message

  - to_number (string)
      * Phone number to send the message to
      * Required if contact_id not set

  - contact_id
      * ID of the contact to send the message to
      * Required if to_number not set

  - route_id
      * ID of the phone or route to send the message from
      * Default: default sender phone ID for your project

  - status_url
      * Webhook callback URL to be notified when message status changes

  - status_secret
      * POST parameter 'secret' passed to status_url

  - is_template (bool)
      * Set to true to evaluate variables like [[contact.name]] in message content. [(See
          available variables)](#variables)
      * Default: false

  - label_ids (array)
      * List of IDs of labels to add to this message

  - message_type
      * Type of message to send
      * Allowed values: sms, ussd
      * Default: sms

  - vars (Hash)
      * Custom variables to store with the message

  - priority (int)
      * Priority of the message (currently only observed for Android phones). Telerivet
          will attempt to send messages with higher priority numbers first (for example, so
          you can prioritize an auto-reply ahead of a bulk message to a large group).
      * Default: 1

Returns:

Telerivet::Message



85
86
87
88
 
# File 'lib/telerivet/project.rb', line 85

def send_message(options)
    require_relative 'message'
    Message.new(@api, @api.do_request("POST", get_base_api_path() + "/messages/send", options))
end

#send_messages(options) ⇒ Object

Sends an SMS message (optionally with mail-merge templates) to a group or a list of up to 500 phone numbers

Arguments:

- options (Hash)
    * Required

  - content
      * Content of the message to send
      * Required

  - group_id
      * ID of the group to send the message to
      * Required if to_numbers not set

  - to_numbers (array of strings)
      * List of up to 500 phone numbers to send the message to
      * Required if group_id not set

  - route_id
      * ID of the phone or route to send the message from
      * Default: default sender phone ID

  - status_url
      * Webhook callback URL to be notified when message status changes

  - label_ids (array)
      * Array of IDs of labels to add to all messages sent (maximum 5)

  - status_secret
      * POST parameter 'secret' passed to status_url

  - exclude_contact_id
      * Optionally excludes one contact from receiving the message (only when group_id is
          set)

  - is_template (bool)
      * Set to true to evaluate variables like [[contact.name]] in message content [(See
          available variables)](#variables)
      * Default: false

  - vars (Hash)
      * Custom variables to set for each message

Returns:

(associative array)
  - count_queued (int)
      * Number of messages queued to send



140
141
142
 
# File 'lib/telerivet/project.rb', line 140

def send_messages(options)
    return @api.do_request("POST", get_base_api_path() + "/messages/send_batch", options)
end

#timezone_id ⇒ Object 



909
910
911
 
# File 'lib/telerivet/project.rb', line 909

def timezone_id
    get('timezone_id')
end