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 [List of tz database time zones Wikipedia
      article](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
  * Updatable via API

- url_slug
  * Unique string used as a component of the project's URL in the Telerivet web app
      (required length: 3-18 characters)
  * Updatable via API

- default_route_id
  * The ID of a basic route or custom route that will be used to send messages by
      default (via both the API and web app), unless a particular route ID is specified when
      sending the message.
  * Updatable via API

- auto_create_contacts (bool)
  * If true, a contact will be automatically created for each unique phone number that a
      message is sent to or received from. If false, contacts will not automatically be
      created (unless contact information is modified by an automated service). The
      Conversations tab in the web app will only show messages that are associated with a
      contact.
  * Updatable via API

- message_retention_days (int)
  * Number of days to retain messages in this project. Messages older than this will be
      automatically deleted. If null, messages will be retained forever.
  * Updatable via API

- short_link_scheme (bool)
  * If true (the default), short links in messages will include the scheme (e.g.,
      'https://rvt.me/xxxxxxxxx'). If false, short links will not include the scheme (e.g.,
      'rvt.me/xxxxxxxxx').
  * Updatable via API

- vars (Hash)
  * Custom variables stored for this project. 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

- organization_id (string, max 34 characters)
  * ID of the organization this project belongs to
  * Read-only

- url
  * URL to this project in the Telerivet web app
  * 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

#auto_create_contacts ⇒ Object 



3978
3979
3980
 
# File 'lib/telerivet/project.rb', line 3978

def auto_create_contacts
    get('auto_create_contacts')
end

#auto_create_contacts=(value) ⇒ Object 



3982
3983
3984
 
# File 'lib/telerivet/project.rb', line 3982

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

#create_campaign(options) ⇒ Object

Creates a new draft campaign, without sending it.

Arguments:

- options (Hash)
  * Required

- campaign_type
    * Type of campaign to create
    * Allowed values: broadcast_text, broadcast_call, broadcast_svc, relative,
        anniversary
    * Required

- name
    * Name of the campaign

- group_id
    * ID of the group of contacts to send the campaign to

- exclude_group_id
    * ID of a group of contacts to exclude from this campaign

- route_id
    * ID of the phone or route to send the campaign from

- timezone_id
    * ID of the timezone to use for scheduling

- label_ids (array)
    * IDs of labels to apply to messages sent by this campaign

- respondent_group_id
    * ID of the group to add contacts to after they respond

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

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

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

- content
    * 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)](#variables)

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

- route_params (Hash)
    * Route-specific parameters for the message (`broadcast_text` campaigns only). See
        [Route-Specific Parameters](#route_params).

- track_clicks (boolean)
    * Whether to shorten links and track link clicks (`broadcast_text` campaigns only).

- short_link_params (Hash)
    * Parameters for short links when `track_clicks` is enabled (`broadcast_text`
        campaigns only).

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

- tts_lang
    * Language for text-to-speech voice calls (`broadcast_call` campaigns only).
    * 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

- tts_voice
    * Voice for text-to-speech voice calls (`broadcast_call` campaigns only).
    * Allowed values: female, male

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

- items (array)
    * Array of campaign items (`relative` and `anniversary` campaigns only).

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

Returns: Telerivet::Campaign



1774
1775
1776
1777
 
# File 'lib/telerivet/project.rb', line 1774

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

#create_group(options) ⇒ Object

Creates a new group.

If the filters parameter is provided, the group will be a dynamic group whose members are determined by the filter conditions. Otherwise, it will be a normal group, initially empty, with the ability to manually add members via contact.addToGroup and remove members via contact.removeFromGroup.

Dynamic group filter conditions can later be updated via the filters property of the Group object; a group cannot be converted between a normal group and a dynamic group after it is created.

Arguments:

- options (Hash)
  * Required

- name (string)
    * Name of the group (must be unique within the project)
    * Required

- filters (Hash)
    * Key-value pairs of conditions that contacts must match to be members of a dynamic
        group. To filter by a custom variable, precede the variable name with 'vars.'
        (conditions on custom variables may also be provided as a nested object under a
        `vars` key, e.g. `{"vars": {"city": "Manila"}}`); other supported keys are `id`,
        `name`, `phone_number`, `time_created`, `time_updated`, `incoming_message_count`,
        `outgoing_message_count`, `last_incoming_message_time`,
        `last_outgoing_message_time`, `conversation_status`, `send_blocked`, `group` (ID of
        a normal group whose members should be included), `not_group` (ID of a normal group
        whose members should be excluded), and `q` (full-text search query matching contacts
        like the search box in the web app). Each value is either a value to match exactly,
        or an object with an operator such as `ne`, `prefix`, `gte`, `lt`, `exists`, or
        `not_exists` as the key (e.g. `{"gte": 10}`).

- allow_sending (bool)
    * True if messages can be sent to this group, false otherwise.
    * Default: 1

- add_time_variable (string)
    * Variable name of a custom contact field that will automatically be set to the
        current date/time on any contact that is added to the group. This variable will only
        be set if the contact does not already have a value for this variable.

- vars (Hash)
    * Custom variables and values to set for this group. 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.

Returns: Telerivet::Group



2178
2179
2180
2181
 
# File 'lib/telerivet/project.rb', line 2178

def create_group(options)
    require_relative 'group'
    Group.new(@api, @api.do_request("POST", get_base_api_path() + "/create_group", options))
end

#create_message_template(options) ⇒ Object

Creates a new message template that can be used when composing or scheduling messages.

Arguments:

- options (Hash)
  * Required

- name (string)
    * Name of the template (max 127 characters)
    * Required

- content (string)
    * Content of the message template (max 2000 characters)
    * Required

- track_clicks (bool)
    * If true, URLs in the content will be replaced with short links that track clicks.
        Requires a plan with click tracking enabled.
    * Default:

- short_link_params (Hash)
    * If `track_clicks` is true, `short_link_params` may be used to specify custom
        parameters for each short link.

- attachments (array)
    * List of attachment objects with file URLs to include with the template

- route_params (Hash)
    * Route-specific parameters to use when sending messages with this template.
        
        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](#route_params).

Returns: Telerivet::MessageTemplate



2379
2380
2381
2382
 
# File 'lib/telerivet/project.rb', line 2379

def create_message_template(options)
    require_relative 'messagetemplate'
    MessageTemplate.new(@api, @api.do_request("POST", get_base_api_path() + "/message_templates", options))
end

#create_phone(options) ⇒ Object

Creates a new basic route (phone) with external API credentials.

For some external API providers, this method automatically updates webhook URLs configured with the external provider so that incoming messages/calls and call status events are routed to Telerivet. In this case, if you have already configured a webhook URL with the external provider, it will be overwritten. For other external API providers, webhook URLs may require manual configuration in order for the route to be fully functional.

Note: This API can only create routes that connect to external gateway APIs using your own account credentials. To add Android phones, WhatsApp routes, or routes with Telerivet-managed billing, use the web app instead.

Credentials are passed via the external_account_id, external_id, external_secret, and external_config parameters. The meaning of these parameters for each phone type is as follows:

Twilio Virtual Number (phone_type: twilio):

  • external_id (optional): Twilio phone number SID (starts with 'PN'); looked up by phone_number if not provided
  • external_account_id (required): Twilio Account SID (starts with 'AC')
  • external_secret (required): Twilio Auth Token

Twilio Messaging Service (phone_type: twilio_messaging_service):

  • external_id (required): Twilio messaging service SID (starts with 'MG')
  • external_account_id (required): Twilio Account SID (starts with 'AC')
  • external_secret (required): Twilio Auth Token

Twilio Shortcode (phone_type: twilio_shortcode):

  • external_id (optional): Twilio shortcode SID (starts with 'SC'); looked up by phone_number if not provided
  • external_account_id (required): Twilio Account SID (starts with 'AC')
  • external_secret (required): Twilio Auth Token

Twilio Caller ID (phone_type: twilio_caller_id):

  • external_account_id (required): Twilio Account SID (starts with 'AC')
  • external_secret (required): Twilio Auth Token

Vonage Virtual Number (phone_type: nexmo):

  • external_account_id (required): Vonage API Key
  • external_secret (required): Vonage API Secret

Vonage Sender ID (phone_type: nexmo_sender_id):

  • external_account_id (required): Vonage API Key
  • external_secret (required): Vonage API Secret

Telesign SMS (phone_type: telesign):

  • external_account_id (required): Telesign Customer ID
  • external_secret (required): Telesign API Key
  • external_config.message_type: ARN, MKT, or OTP
  • external_config.sender_type: one_way (default) or two_way

Infobip SMS (phone_type: infobip):

  • external_account_id (required): Infobip username
  • external_secret (required): Infobip API key
  • external_config.sender_type: one_way (default) or two_way
  • external_config.india_dlt_principal_entity_id: India DLT Principal Entity ID (only for India)

Infobip USSD (phone_type: infobip_ussd):

  • No external credentials required

Africa's Talking SMS (phone_type: africas_talking):

  • external_account_id (required): Africa's Talking username
  • external_secret (required): Africa's Talking API key
  • external_config.sender_type: one_way (default) or two_way

Africa's Talking USSD (phone_type: africas_talking_ussd):

  • No external credentials required

Simulated Phone (phone_type: simulated):

  • No external credentials required
  • Messages are simulated locally and not sent to any external provider
  • Useful for testing

Webhook URL Setup

Some route types require manual configuration of callback URLs in the external provider's dashboard. When the Phone response includes an external_setup object, you will need to configure the webhook URLs in your provider's account settings.

The following phone types require manual webhook setup:

  • africas_talking: message_status_url (always), incoming_message_url (if two_way)
  • africas_talking_ussd: incoming_call_url
  • infobip_ussd: incoming_call_url
  • twilio_messaging_service: incoming_message_url
  • telesign (two_way only): incoming_message_url

Telerivet automatically configures webhooks for the following phone types as follows:

  • twilio - automatically updates incoming SMS and voice configuration for the Twilio virtual number associated with the phone_number or external_id parameter
  • twilio_shortcode - automatically updates incoming SMS configuration for the Twilio short code associated with the phone_number or external_id parameter
  • nexmo - automatically updates incoming SMS and voice configuration for the Vonage virtual number matching the phone_number parameter
  • infobip - automatically updates incoming SMS configuration for the Infobip virtual number matching the phone_number parameter or external_id parameter

Arguments:

- options (Hash)
  * Required

- name (string)
    * Name of the basic route to create

- phone_number (string)
    * Phone number or sender ID
    * Required

- phone_type (string)
    * Type of basic route to create. Supported values: twilio, twilio_messaging_service,
        twilio_shortcode, twilio_caller_id, nexmo, infobip, africas_talking,
        africas_talking_ussd, infobip_ussd, telesign, simulated. Other types of basic routes
        can only be created via the web app.
    * Required

- external_account_id (string)
    * Account ID for the external API (e.g. Twilio Account SID, Vonage API Key). See the
        description above for the meaning of this parameter for each phone type.

- external_id (string)
    * External phone/resource ID within the external API account (if applicable). For
        `twilio` and `twilio_shortcode` routes, this is optional and will be looked up
        automatically from the phone_number if not provided.

- external_secret (string)
    * Secret/API key for the external API (e.g. Twilio Auth Token, Vonage API Secret).
        This value is required when creating a new route but is never returned in API
        responses. See the description above for the meaning of this parameter for each
        phone type.

- external_config (Hash)
    * Additional configuration settings specific to the phone_type. See the description
        above for available settings for each phone type.

- country
    * 2-letter country code (ISO 3166-1 alpha-2) where phone is from. This country code
        is used to automatically convert phone numbers in local format to international
        format. If not provided, will be set to the organization's country by default.

- send_paused (bool)
    * True if sending messages should initially be paused, false otherwise
    * Default:

- timezone_id (string)
    * A string specifying the time zone used when sending messages; see [List of tz
        database time zones Wikipedia
        article](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones). When not
        provided, the project's default time zone is used.

- validate_recipient_numbers (bool)
    * Set to true to validate recipient phone numbers before sending. Messages to
        invalid numbers will fail without being sent.
    * Default:

- allowed_recipient_countries (array of strings)
    * Array of 2-letter country codes (ISO 3166-1 alpha-2) to which this phone is
        allowed to send messages. If not provided, there is no restriction.

- send_delay (number)
    * Number of seconds to wait after sending each message, to avoid exceeding carrier
        rate limits.

- quiet_mode (string)
    * Controls behavior during quiet hours. Possible values: 'off' (disabled), 'delay'
        (messages delayed until quiet hours end), 'confirm' (requires manual confirmation;
        worker-based routes only).
    * Allowed values: off, delay, confirm
    * Default: off

- quiet_start (string)
    * Time when quiet hours begin, in HH:MM format (24-hour time). Only applicable when
        quiet_mode is not 'off'.

- quiet_end (string)
    * Time when quiet hours end, in HH:MM format (24-hour time). Only applicable when
        quiet_mode is not 'off'.

- vars
    * Custom variables and values to set for this basic route

Returns: Telerivet::Phone



1374
1375
1376
1377
 
# File 'lib/telerivet/project.rb', line 1374

def create_phone(options)
    require_relative 'phone'
    Phone.new(@api, @api.do_request("POST", get_base_api_path() + "/phones", options))
end

#create_relative_scheduled_message(options) ⇒ Object

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.

Arguments:

- options (Hash)
  * Required

- message_type
    * Type of message to send
    * Allowed values: text, sms, mms, call, chat, service
    * Default: text

- content
    * Content of the message to schedule
    * Required if sending text message

- group_id
    * 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
    * Time of day when scheduled messages will be sent in HH:MM format (with hours from
        00 to 23)
    * Required

- timezone_id
    * TZ database timezone ID; see [List of tz database time zones Wikipedia
        article](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
    * Default: project default timezone

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

- offset_scale
    * The type of interval that will be used to adjust the scheduled date relative to
        the date stored in the contact's date_variable, when offset_count is non-zero
        (I=minutes, D=day, W=week, M=month, Y=year)
    * Allowed values: I, D, W, M, Y
    * Default: D

- offset_count (int)
    * The number of days/weeks/months/years to adjust the date of the scheduled message
        relative relative to the date stored in the custom contact variable identified by
        the date_variable parameter. May be positive, negative, or zero.
    * Default: 0

- 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 route ID

- service_id
    * Service to invoke for each recipient (when `message_type` is `call` or `service`)
    * Required if message_type is service

- audio_url
    * 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
    * The language of the text-to-speech voice (when `message_type` is `call`)
    * 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
    * Default: en-US

- tts_voice
    * The name of the text-to-speech voice (when message_type=call)
    * Allowed values: female, male
    * Default: female

- track_clicks (boolean)
    * If true, URLs in the message content will automatically be replaced with unique
        short URLs.
    * Default: false

- short_link_params (Hash)
    *
        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 (bool)
    * Set to true to evaluate variables like [[contact.name]] in message content. [(See
        available variables)](#variables)
    * Default: false

- media (array)
    * 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).
        
        Alternatively, you can use the `media_urls` parameter with an array of URL
        strings.

- route_params (Hash)
    * 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](#route_params).

- label_ids (array)
    * 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 (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

- vars (Hash)
    * Custom variables to set for this relative scheduled message, which will be copied
        to each message sent from this scheduled message

Returns: Telerivet::RelativeScheduledMessage



813
814
815
816
 
# File 'lib/telerivet/project.rb', line 813

def create_relative_scheduled_message(options)
    require_relative 'relativescheduledmessage'
    RelativeScheduledMessage.new(@api, @api.do_request("POST", get_base_api_path() + "/relative_scheduled", options))
end

#create_route(options) ⇒ Object

Creates a new custom route that can be used to send messages via one or more basic routes (phones).

The actions array defines the routing rules.

Arguments:

- options (Hash)
  * Required

- name (string)
    * Name of the custom route to create
    * Required

- actions (array of RoutingAction)
    * Array of routing action objects. Allowed action types: `use_phone` (select basic
        routes to send messages), `condition` (conditionally execute actions based on
        criteria).
    * Required

- vars
    * Custom variables and values to set for this route

Returns: Telerivet::Route



3335
3336
3337
3338
 
# File 'lib/telerivet/project.rb', line 3335

def create_route(options)
    require_relative 'route'
    Route.new(@api, @api.do_request("POST", get_base_api_path() + "/routes", options))
end

#create_service(options) ⇒ Object

Creates a new automated service.

Only certain types of automated services can be created via the API. Other types of services can only be created via the web app.

Arguments:

- options (Hash)
  * Required

- name (string)
    * Name of the service to create, which must be unique in the project. If a name is
        not provided, a unique default name will be generated.

- service_type (string)
    * Type of service to create.  The following service types can be created via the
        API:
        
        - incoming_message_actions
        - contact_actions
        - message_actions
        - project_actions
        - message_status_actions
        - voice_actions
        - ussd_actions
        - data_row_actions
        - incoming_message_webhook
        - optin_optout
        - keyword_auto_reply
        - messaging_poll
        - voice_poll
        - scheduled_actions
        - auto_reply
        - call_auto_reply
        - incoming_message_script
        - contact_script
        - message_script
        - data_row_script
        - scheduled_script
        - webhook_script
        - voice_script
        - ussd_script
        - project_script
        - opt_out_page
        - button_page
        - custom_template_instance
        
        Other types of services can only be created via the web app.
    * Required

- config (Hash)
    * Configuration specific to the `service_type`. See [Service Configuration
        Reference](#service_config) or the machine-readable [OpenAPI
        specification](https://api.telerivet.com/openapi.json) for complete documentation of
        configuration parameters for each service type.
    * Required

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

- active (bool)
    * Whether the service is initially active or inactive. Inactive services are not
        automatically triggered and cannot be invoked via the API.
    * Default: 1

- response_table_id
    * ID of a data table where responses will be stored, or null to disable
        automatically storing responses. If the response_table_id parameter is not provided,
        a data table may automatically be created with the same name as the service if the
        service collects responses.

- phone_ids (array)
    * IDs of phones (basic routes) to associate with this service, or null to associate
        this service with all routes. Only applies for service types that handle incoming
        messages, voice calls, or USSD sessions.

- message_types (array)
    * Types of messages that this service should handle. Only applies to services that
        handle incoming messages.
    * Allowed values: text, call, ussd

- table_ids (array)
    * IDs of data tables that this service applies to, or null to apply to all data
        tables. Only applies to data row services (`data_row_script` and
        `data_row_actions`).

- message_statuses (array of strings)
    * Message statuses that this service should handle. Only applies to
        `message_status_actions` services.
    * Allowed values: sent, delivered, failed, failed_queued, not_delivered

- tags (array of strings)
    * Tags used to organize this service. Each tag can be up to 32 characters in length,
        and up to 10 tags are allowed.

- show_action (bool)
    * Whether to show this service in the Actions menu within the Telerivet web app when
        the service is active. Only applies for service types that are manually triggered.
    * Default: 1

- contact_number_filter
    * If contact_number_filter is `long_number`, this service will only be triggered if
        the contact phone number has at least 7 digits (ignoring messages from shortcodes
        and alphanumeric senders). If contact_number_filter is `all`, the service will be
        triggered for all contact phone numbers.  Only applies to services that handle
        incoming messages.
    * Allowed values: long_number, all
    * Default: long_number

- direction
    * Determines whether the service handles incoming voice calls, outgoing voice calls,
        or both. Only applies to services that handle voice calls.
    * Allowed values: incoming, outgoing, both
    * Default: both

- priority (int)
    * A number that determines the order that services are triggered when an event
        occurs (e.g. when an incoming message is received). Smaller numbers are triggered
        first. The priority is ignored for services that are triggered directly.

- apply_mode
    * If apply_mode is `unhandled`, the service will not be triggered if another service
        has already handled the incoming message. If apply_mode is `always`, the service
        will always be triggered regardless of other services. Only applies to services that
        handle incoming messages.
    * Allowed values: always, unhandled
    * Default: unhandled

Returns: Telerivet::Service



3071
3072
3073
3074
 
# File 'lib/telerivet/project.rb', line 3071

def create_service(options)
    require_relative 'service'
    Service.new(@api, @api.do_request("POST", get_base_api_path() + "/services", options))
end

#create_task(options) ⇒ Object

Creates and starts an asynchronous task that is applied to all entities matching a filter (e.g. contacts, messages, or data rows). Tasks are designed to efficiently process a large number of entities. When processing a large number of entities, tasks are much faster than using the API to query and loop over all objects matching a filter.

Several different types of tasks are supported, including applying services to contacts, messages, or data rows; adding or removing contacts from a group; blocking or unblocking sending messages to a contact; updating a custom variable; deleting contacts, messages, or data rows; or exporting data to CSV.

When using a task to apply a Custom Actions or Cloud Script API service (apply_service_to_contacts, apply_service_to_rows, or apply_service_to_messages), the task variable will be available within the service. The service can use custom variables on the task object (e.g. task.vars.example), such as to store aggregate statistics for the rows matching the filter.

Arguments:

- options (Hash)
  * Required

- task_type
    * Type of task to create. Each `task_type` applies to a certain type of entity (such
        as a contact, message, or data row).
        
        Tasks for contacts:
        
        - update_contact_var
        - add_group_members
        - remove_group_members
        - set_conversation_status
        - set_send_blocked
        - apply_service_to_contacts
        - delete_contacts
        - export_contacts
        
        Tasks for data rows:
        
        - update_row_var
        - apply_service_to_rows
        - delete_rows
        - export_rows
        
        Tasks for messages:
        
        - cancel_messages
        - resend_messages
        - retry_message_services
        - apply_service_to_messages
        - add_label
        - remove_label
        - update_message_var
        - delete_messages
        - export_messages
    * Required

- task_params (Hash)
    * Parameters applied to all matching rows (specific to `task_type`).
        
        **apply_service_to_contacts**,
        **apply_service_to_messages**, **apply_service_to_rows**:
        <table>
        <tr><td> service_id </td> <td> The ID of the service
        to apply (string) </td></tr>
        <tr><td> variables </td> <td> Optional object
        containing up to 25 temporary variable names and their corresponding values to set
        when invoking the service. Values may be strings, numbers, or boolean (true/false).
        String values may be up to 4096 bytes in length. Arrays and objects are not
        supported. Within Custom Actions, each variable can be used like [[$name]] (with a
        leading $ character and surrounded by double square brackets). Within a Cloud Script
        API service or JavaScript action, each variable will be available as a global
        JavaScript variable like $name (with a leading $ character). (object) </td></tr>
        </table>
        <br />
        **update_contact_var**, **update_message_var**,
        **update_row_var**:
        <table>
        <tr><td> variable </td> <td> The custom variable
        name (string) </td></tr>
        <tr><td> value </td> <td> The value to set (string,
        boolean, float, null) </td></tr>
        </table>
        <br />
        **add_group_members**, **remove_group_members**:
        <table>
        <tr><td> group_id </td> <td> The ID of the group
        (string) </td></tr>
        </table>
        <br />
        **add_label**, **remove_label**:
        <table>
        <tr><td> label_id </td> <td> The ID of the label
        (string) </td></tr>
        </table>
        <br />
        **resend_messages**:
        <table>
        <tr><td> route_id </td> <td> ID of the new route to
        use, or null to use the original route (string) </td></tr>
        </table>
        <br />
        **set_send_blocked**:
        <table>
        <tr><td> send_blocked </td> <td> true to block
        sending messages, false to unblock sending messages (boolean) </td></tr>
        </table>
        <br />
        **set_conversation_status**:
        <table>
        <tr><td> conversation_status </td> <td> "active",
        "handled", or "closed" (string) </td></tr>
        </table>
        <br />
        **export_contacts**, **export_messages**,
        **export_rows**:
        <table>
        <tr><td>storage_id </td> <td> ID of a storage
        provider where the CSV file will be saved. (string)
        
        Currently only AWS S3 is supported as a storage
        provider.
        This requires creating a S3 bucket in your own
        AWS account, as well as an IAM user with access key and secret that has permission
        to write to that bucket.
        You can configure your own S3 bucket as a
        storage provider on the <a href="/dashboard/a/storage">Storage Providers</a> page.
        
        Direct downloads are not supported when
        exporting data via the API.
        (string) </td></tr>
        <tr><td>filename </td> <td> Path within the storage
        backend where the CSV file will be saved </td></tr>
        <tr><td>column_ids </td> <td> IDs of columns to save
        in the CSV file. If not provided, all default columns will be saved. (array of
        strings, optional) </td></tr>
        </table>
        <br />
        **delete_contacts**, **delete_messages**,
        **delete_rows**, **cancel_messages**, **retry_message_services**: <br />
        No parameters.

- filter_type
    * Type of filter defining the rows that the task is applied to.
        
        Each `filter_type` queries a certain type of
        entity (such as contacts, messages, or data rows).
        
        In general, the `task_type` and the
        `filter_type` must return the same type of entity; however, tasks applied to
        contacts (other than `export_contacts`) can also be applied
        when the filter returns entities that are
        associated with a contact, such as messages or data rows. (Note that in this case,
        it is possible for the task to be applied multiple times to an individual contact if
        multiple messages or data rows are associated with the same contact.)
    * Allowed values: query_contacts, contact_ids, query_rows, row_ids, query_messages,
        message_ids
    * Required

- filter_params (Hash)
    * Parameters defining the rows that the task is applied to (specific to
        `filter_type`).
        
        **`query_contacts`**: <br />
        The same filter parameters as used by
        [project.queryContacts](#Project.queryContacts). If you want to apply the task to
        all contacts, use the parameters {"all": true}.
        
        **`contact_ids`**:
        <table>
        <tr><td> `contact_ids` </td> <td> IDs of up to 100
        contacts to apply this task to (array of strings) </td></tr>
        </table>
        
        **`query_messages`**: <br />
        The same filter parameters as used by
        [project.queryMessages](#Project.queryMessages). If you want to apply the task to
        all messages, use the parameters {"all": true}.
        
        **`message_ids`**:
        <table>
        <tr><td> `message_ids` </td> <td> IDs of up to 100
        messages to apply this task to (array of strings) </td></tr>
        </table>
        
        **`query_rows`**: <br />
        The same filter parameters as used by
        [table.queryRows](#DataTable.queryRows). If you want to apply the task to all rows
        in the table, use the parameters {"all": true}.
        
        **`row_ids`**:
        <table>
        <tr><td> `row_ids` </td> <td> IDs of up to 100 data
        rows to apply this task to (array of strings) </td></tr>
        </table>
    * Required

- table_id (string, max 34 characters)
    * ID of the data table this task is applied to (if applicable).
        
        Required if filter_type is `query_rows` or `row_ids`.

- vars (Hash)
    * Initial custom variables to set for the task.
        
        If the task applies a service, the service can read
        and write custom variables on the task object (e.g. `task.vars.example`), such as
        to store aggregate statistics for the rows matching
        the filter.

Returns: Telerivet::Task



1996
1997
1998
1999
 
# File 'lib/telerivet/project.rb', line 1996

def create_task(options)
    require_relative 'task'
    Task.new(@api, @api.do_request("POST", get_base_api_path() + "/tasks", options))
end

#create_webhook(options) ⇒ Object

Creates a new webhook that will be triggered when specific events occur within the project.

Note: The Webhook object is not used for notifying your server when incoming messages are received. To notify a URL when incoming messages are received, you can configure a webhook by creating a Service with type incoming_message_webhook.

Arguments:

- options (Hash)
  * Required

- url
    * URL to send webhook requests to. Must start with https:// or http://.
    * Required

- secret
    * Secret to include when sending webhook requests (up to 200 characters). Telerivet
        will send the secret in the password field of HTTP basic auth (with username
        'telerivet').

- events (array of strings)
    * Array of event types to trigger this webhook. Valid event types are: `send_status`
        (message status updates), `send_broadcast` (broadcast sent), `contact_update`
        (contact added/updated/deleted), `message_metadata` (message metadata updated).

Returns: Telerivet::Webhook



3898
3899
3900
3901
 
# File 'lib/telerivet/project.rb', line 3898

def create_webhook(options)
    require_relative 'webhook'
    Webhook.new(@api, @api.do_request("POST", get_base_api_path() + "/webhooks", options))
end

#default_route_id ⇒ Object 



3970
3971
3972
 
# File 'lib/telerivet/project.rb', line 3970

def default_route_id
    get('default_route_id')
end

#default_route_id=(value) ⇒ Object 



3974
3975
3976
 
# File 'lib/telerivet/project.rb', line 3974

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

#get_airtime_stats(options) ⇒ Object

Retrieves statistics about airtime transactions sent via Telerivet. This endpoint returns historical data for successful transactions that is computed shortly after midnight each day in the project's time zone. If the date range includes the current day, it will include statistics for the current day so far.

Arguments:

- options (Hash)
  * Required

- start_date (string)
    * Start date of airtime statistics, in YYYY-MM-DD format
    * Required

- end_date (string)
    * End date of airtime statistics (inclusive), in YYYY-MM-DD format
    * Required

- rollup (string)
    * Date interval to group by
    * Allowed values: day, week, month, year, all
    * Default: day

- properties (string)
    * Comma separated list of properties to group by. The `provider_category` property
        combines the provider type and category ID (e.g. `main.airtime.dtone/1`); also group
        by `category_name` to return the category's display name.
    * Allowed values: country, operator_name, product_id, provider_id,
        provider_category, category_name

- metrics (string)
    * Comma separated list of metrics to return (summed for each distinct value of the
        requested properties). Supported metrics are `count` (the number of successful
        transactions), `value.<currency>` (the face value of the airtime received by the
        recipients, e.g. `value.KES`), and `price.<currency>` (the amount charged for the
        transactions, e.g. `price.USD`). Amounts are not converted between currencies: each
        `value`/`price` metric only includes transactions denominated in the specified ISO
        4217 currency, and transactions without a numeric currency value (such as bundles)
        are not included in any `value` metric.
    * Required

- filters (Hash)
    * Key-value pairs of properties and corresponding values; the returned statistics
        will only include successful airtime transactions where the property matches the
        provided value. Only the following properties are supported for filters: `country`,
        `operator_name`, `product_id`, `provider_id`, `provider_category`

Returns: (associative array) - intervals (array) * List of objects representing each date interval containing at least one successful airtime transaction matching the filters.



3832
3833
3834
3835
 
# File 'lib/telerivet/project.rb', line 3832

def get_airtime_stats(options)
    data = @api.do_request("GET", get_base_api_path() + "/airtime_stats", options)
    return data
end

#get_airtime_transaction_by_id(id) ⇒ Object

Gets an airtime transaction by ID

Arguments:

- id
  * ID of the airtime transaction
  * Required

Returns: Telerivet::AirtimeTransaction



3442
3443
3444
3445
 
# File 'lib/telerivet/project.rb', line 3442

def get_airtime_transaction_by_id(id)
    require_relative 'airtimetransaction'
    AirtimeTransaction.new(@api, @api.do_request("GET", get_base_api_path() + "/airtime_transactions/#{id}"))
end

#get_base_api_path ⇒ Object 



4010
4011
4012
 
# File 'lib/telerivet/project.rb', line 4010

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

#get_broadcast_by_id(id) ⇒ Object

Retrieves the broadcast with the given ID.

Arguments:

- id
  * ID of the broadcast
  * Required

Returns: Telerivet::Broadcast



1551
1552
1553
1554
 
# File 'lib/telerivet/project.rb', line 1551

def get_broadcast_by_id(id)
    require_relative 'broadcast'
    Broadcast.new(@api, @api.do_request("GET", get_base_api_path() + "/broadcasts/#{id}"))
end

#get_campaign_by_id(id) ⇒ Object

Retrieves the campaign with the given ID.

Arguments:

- id
  * ID of the campaign
  * Required

Returns: Telerivet::Campaign



1647
1648
1649
1650
 
# File 'lib/telerivet/project.rb', line 1647

def get_campaign_by_id(id)
    require_relative 'campaign'
    Campaign.new(@api, @api.do_request("GET", get_base_api_path() + "/campaigns/#{id}"))
end

#get_contact_by_id(id) ⇒ Object

Retrieves the contact with the given ID.

Arguments:

- id
  * ID of the contact
  * Required

Returns: Telerivet::Contact



1075
1076
1077
1078
 
# File 'lib/telerivet/project.rb', line 1075

def get_contact_by_id(id)
    require_relative 'contact'
    Contact.new(@api, @api.do_request("GET", get_base_api_path() + "/contacts/#{id}"))
end

#get_contact_fields ⇒ Object

Gets a list of all custom fields defined for contacts in this project. The return value is an array of objects with the properties 'name', 'variable', 'type', 'order', 'readonly', 'lookup_key', and 'show_on_conversation'. (Fields are automatically created any time a Contact's 'vars' property is updated.)

Returns: array



3472
3473
3474
 
# File 'lib/telerivet/project.rb', line 3472

def get_contact_fields()
    return @api.do_request("GET", get_base_api_path() + "/contact_fields")
end

#get_contact_stats(options) ⇒ Object

Retrieves statistics about the number of contacts in the project (total or in particular groups) over a date range. This endpoint returns historical data that is computed shortly after midnight each day in the project's time zone. If the date range includes the current day, it will include the current number of contacts.

To get historical statistics for the number of contacts matching a filter, use project.createGroup to create a dynamic group for each filter you want to track. However, the statistics will only be available for dates after the dynamic group was created.

Arguments:

- options (Hash)
  * Required

- start_date (string)
    * Start date of contact statistics, in YYYY-MM-DD format
    * Required

- end_date (string)
    * End date of contact statistics (inclusive), in YYYY-MM-DD format
    * Required

- rollup (string)
    * Date interval to group by
    * Allowed values: day, week, month, year
    * Default: day

- cumulative (bool)
    * If true, each interval contains the total number of contacts at the end of the
        interval; if false, each interval contains the change in the number of contacts
        during the interval.
    * Default: 1

- series (string)
    * Comma separated list of up to 10 data series to return, corresponding to the keys
        of the `values` object in the response. Each item is either `total` (the total
        number of contacts in the project) or a group ID (the number of contacts in that
        group).
    * Default: total

Returns: (associative array) - intervals (array) * List of objects representing each date interval.



3730
3731
3732
3733
 
# File 'lib/telerivet/project.rb', line 3730

def get_contact_stats(options)
    data = @api.do_request("GET", get_base_api_path() + "/contact_stats", options)
    return data
end

#get_data_table_by_id(id) ⇒ Object

Retrieves the data table with the given ID.

Arguments:

- id
  * ID of the data table
  * Required

Returns: Telerivet::DataTable



2625
2626
2627
2628
 
# File 'lib/telerivet/project.rb', line 2625

def get_data_table_by_id(id)
    require_relative 'datatable'
    DataTable.new(@api, @api.do_request("GET", get_base_api_path() + "/tables/#{id}"))
end

#get_data_table_stats(options) ⇒ Object

Retrieves statistics about the number of rows in particular data tables or data table views over a date range. This endpoint returns historical data that is computed shortly after midnight each day in the project's time zone. If the date range includes the current day, it will include the current number of rows.

Arguments:

- options (Hash)
  * Required

- start_date (string)
    * Start date of data table statistics, in YYYY-MM-DD format
    * Required

- end_date (string)
    * End date of data table statistics (inclusive), in YYYY-MM-DD format
    * Required

- rollup (string)
    * Date interval to group by
    * Allowed values: day, week, month, year
    * Default: day

- cumulative (bool)
    * If true, each interval contains the number of rows in each data table at the end
        of the interval; if false, each interval contains the change in the number of rows
        during the interval.
    * Default: 1

- series (string)
    * Comma separated list of up to 10 data table IDs and/or data table view IDs,
        corresponding to the keys of the `values` object in the response.
    * Required

Returns: (associative array) - intervals (array) * List of objects representing each date interval.



3774
3775
3776
3777
 
# File 'lib/telerivet/project.rb', line 3774

def get_data_table_stats(options)
    data = @api.do_request("GET", get_base_api_path() + "/data_table_stats", options)
    return data
end

#get_file_by_id(id) ⇒ Object

Retrieves the stored file with the given ID.

Arguments:

- id
  * ID of the stored file
  * Required

Returns: Telerivet::StoredFile



2540
2541
2542
2543
 
# File 'lib/telerivet/project.rb', line 2540

def get_file_by_id(id)
    require_relative 'storedfile'
    StoredFile.new(@api, @api.do_request("GET", get_base_api_path() + "/files/#{id}"))
end

#get_group_by_id(id) ⇒ Object

Retrieves the group with the given ID.

Arguments:

- id
  * ID of the group
  * Required

Returns: Telerivet::Group



2194
2195
2196
2197
 
# File 'lib/telerivet/project.rb', line 2194

def get_group_by_id(id)
    require_relative 'group'
    Group.new(@api, @api.do_request("GET", get_base_api_path() + "/groups/#{id}"))
end

#get_label_by_id(id) ⇒ Object

Retrieves the label with the given ID.

Arguments:

- id
  * ID of the label
  * Required

Returns: Telerivet::Label



2279
2280
2281
2282
 
# File 'lib/telerivet/project.rb', line 2279

def get_label_by_id(id)
    require_relative 'label'
    Label.new(@api, @api.do_request("GET", get_base_api_path() + "/labels/#{id}"))
end

#get_message_by_id(id) ⇒ Object

Retrieves the message with the given ID.

Arguments:

- id
  * ID of the message
  * Required

Returns: Telerivet::Message



1475
1476
1477
1478
 
# File 'lib/telerivet/project.rb', line 1475

def get_message_by_id(id)
    require_relative 'message'
    Message.new(@api, @api.do_request("GET", get_base_api_path() + "/messages/#{id}"))
end

#get_message_fields ⇒ Object

Gets a list of all custom fields defined for messages in this project. The return value is an array of objects with the properties 'name', 'variable', 'type', 'order', and 'hide_values'. (Fields are automatically created any time a Message's 'vars' property is updated.)

Returns: array



3558
3559
3560
 
# File 'lib/telerivet/project.rb', line 3558

def get_message_fields()
    return @api.do_request("GET", get_base_api_path() + "/message_fields")
end

#get_message_stats(options) ⇒ Object

Retrieves statistics about messages sent or received via Telerivet. This endpoint returns historical data that is computed shortly after midnight each day in the project's time zone. If the date range includes the current day, it will include statistics for the current day so far.

Arguments:

- options (Hash)
  * Required

- start_date (string)
    * Start date of message statistics, in YYYY-MM-DD format
    * Required

- end_date (string)
    * End date of message statistics (inclusive), in YYYY-MM-DD format
    * Required

- rollup (string)
    * Date interval to group by
    * Allowed values: day, week, month, year, all
    * Default: day

- properties (string)
    * Comma separated list of properties to group by
    * Allowed values: org_id, org_name, org_industry, project_id, project_name, user_id,
        user_email, user_name, phone_id, phone_name, phone_type, direction, source, status,
        network_code, network_name, message_type, service_id, service_name, simulated, link

- metrics (string)
    * Comma separated list of metrics to return (summed for each distinct value of the
        requested properties). Supported metrics are `count` (the number of messages),
        `num_parts` (the number of SMS parts), `duration` (the total duration of calls, in
        seconds), and `price.<currency>` (the total price of messages priced in the
        specified ISO 4217 currency, e.g. `price.USD`). Amounts are not converted between
        currencies: each `price.<currency>` metric only includes messages priced in the
        specified currency.
    * Required

- filters (Hash)
    * Key-value pairs of properties and corresponding values; the returned statistics
        will only include messages where the property matches the provided value. Only the
        following properties are supported for filters: `user_id`, `phone_id`, `direction`,
        `source`, `status`, `service_id`, `simulated`, `message_type`, `network_code`

Returns: (associative array) - intervals (array) * List of objects representing each date interval containing at least one message matching the filters.



3679
3680
3681
3682
 
# File 'lib/telerivet/project.rb', line 3679

def get_message_stats(options)
    data = @api.do_request("GET", get_base_api_path() + "/message_stats", options)
    return data
end

#get_message_template_by_id(id) ⇒ Object

Retrieves the message template with the given ID.

Arguments:

- id
  * ID of the message template
  * Required

Returns: Telerivet::MessageTemplate



2395
2396
2397
2398
 
# File 'lib/telerivet/project.rb', line 2395

def get_message_template_by_id(id)
    require_relative 'messagetemplate'
    MessageTemplate.new(@api, @api.do_request("GET", get_base_api_path() + "/message_templates/#{id}"))
end

#get_or_create_contact(options = nil) ⇒ Object

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

If a phone number is provided, by default, 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). This behavior can be modified by setting the lookup_key parameter to look up a contact by another field, including a custom variable.

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, vars, default_route_id, send_blocked, add_group_ids, remove_group_ids).

Arguments:

- options (Hash)

- name
    * Name of the contact

- phone_number
    * Phone number of the contact

- lookup_key
    * The field used to search for a matching contact, or 'none' to always create a new
        contact. To search by a custom variable, precede the variable name with 'vars.'.
    * Allowed values: phone_number, name, id, vars.variable_name, none
    * Default: phone_number

- send_blocked (bool)
    * True if Telerivet is blocked from sending messages to this contact

- default_route_id
    * ID of the route to use by default to send messages to this contact

- add_group_ids (array)
    * ID of one or more groups to add this contact as a member (max 20)

- id
    * ID of an existing contact (only used if `lookup_key` is 'id')

- remove_group_ids (array)
    * ID of one or more groups to remove this contact as a member (max 20)

- vars (Hash)
    * Custom variables and values to update on the contact. 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.

Returns: Telerivet::Contact



924
925
926
927
 
# File 'lib/telerivet/project.rb', line 924

def get_or_create_contact(options = nil)
    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



2609
2610
2611
2612
 
# File 'lib/telerivet/project.rb', line 2609

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. If a group with that name does not exist, a new normal group will be created, initially empty. (To create a dynamic group, use project.createGroup.)

Arguments:

- name
  * Name of the group
  * Required

Returns: Telerivet::Group



2118
2119
2120
2121
 
# File 'lib/telerivet/project.rb', line 2118

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



2263
2264
2265
2266
 
# File 'lib/telerivet/project.rb', line 2263

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 basic route with the given ID.

Arguments:

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

Returns: Telerivet::Phone



1155
1156
1157
1158
 
# File 'lib/telerivet/project.rb', line 1155

def get_phone_by_id(id)
    require_relative 'phone'
    Phone.new(@api, @api.do_request("GET", get_base_api_path() + "/phones/#{id}"))
end

#get_relative_scheduled_message_by_id(id) ⇒ Object

Retrieves the scheduled message with the given ID.

Arguments:

- id
  * ID of the relative scheduled message
  * Required

Returns: Telerivet::RelativeScheduledMessage



2782
2783
2784
2785
 
# File 'lib/telerivet/project.rb', line 2782

def get_relative_scheduled_message_by_id(id)
    require_relative 'relativescheduledmessage'
    RelativeScheduledMessage.new(@api, @api.do_request("GET", get_base_api_path() + "/relative_scheduled/#{id}"))
end

#get_route_by_id(id) ⇒ Object

Gets a custom route by ID

Arguments:

- id
  * ID of the route
  * Required

Returns: Telerivet::Route



3351
3352
3353
3354
 
# File 'lib/telerivet/project.rb', line 3351

def get_route_by_id(id)
    require_relative 'route'
    Route.new(@api, @api.do_request("GET", get_base_api_path() + "/routes/#{id}"))
end

#get_route_list ⇒ Object

Returns a list of all available routes for sending messages in a project, including both basic routes (phones) and custom routes.

Returns: array



3305
3306
3307
 
# File 'lib/telerivet/project.rb', line 3305

def get_route_list()
    return @api.do_request("GET", get_base_api_path() + "/route_list")
end

#get_scheduled_message_by_id(id) ⇒ Object

Retrieves the scheduled message with the given ID.

Arguments:

- id
  * ID of the scheduled message
  * Required

Returns: Telerivet::ScheduledMessage



2750
2751
2752
2753
 
# File 'lib/telerivet/project.rb', line 2750

def get_scheduled_message_by_id(id)
    require_relative 'scheduledmessage'
    ScheduledMessage.new(@api, @api.do_request("GET", get_base_api_path() + "/scheduled/#{id}"))
end

#get_scheduled_service_by_id(id) ⇒ Object

Retrieves the scheduled service with the given ID.

Arguments:

- id
  * ID of the scheduled service
  * Required

Returns: Telerivet::ScheduledService



2914
2915
2916
2917
 
# File 'lib/telerivet/project.rb', line 2914

def get_scheduled_service_by_id(id)
    require_relative 'scheduledservice'
    ScheduledService.new(@api, @api.do_request("GET", get_base_api_path() + "/scheduled_services/#{id}"))
end

#get_service_by_id(id) ⇒ Object

Retrieves the service with the given ID.

Arguments:

- id
  * ID of the service
  * Required

Returns: Telerivet::Service



3132
3133
3134
3135
 
# File 'lib/telerivet/project.rb', line 3132

def get_service_by_id(id)
    require_relative 'service'
    Service.new(@api, @api.do_request("GET", get_base_api_path() + "/services/#{id}"))
end

#get_task_by_id(id) ⇒ Object

Retrieves the task with the given ID.

Arguments:

- id
  * ID of the task
  * Required

Returns: Telerivet::Task



2044
2045
2046
2047
 
# File 'lib/telerivet/project.rb', line 2044

def get_task_by_id(id)
    require_relative 'task'
    Task.new(@api, @api.do_request("GET", get_base_api_path() + "/tasks/#{id}"))
end

#get_users ⇒ Object

Returns an array of user accounts that have access to this project. Each item in the array is an object containing id, email, and name properties. (The id corresponds to the user_id property of the Message object.)

Returns: array



3380
3381
3382
 
# File 'lib/telerivet/project.rb', line 3380

def get_users()
    return @api.do_request("GET", get_base_api_path() + "/users")
end

#get_webhook_by_id(id) ⇒ Object

Retrieves the webhook with the given ID.

Arguments:

- id
  * ID of the webhook
  * Required

Returns: Telerivet::Webhook



3914
3915
3916
3917
 
# File 'lib/telerivet/project.rb', line 3914

def get_webhook_by_id(id)
    require_relative 'webhook'
    Webhook.new(@api, @api.do_request("GET", get_base_api_path() + "/webhooks/#{id}"))
end

#id ⇒ Object 



3942
3943
3944
 
# File 'lib/telerivet/project.rb', line 3942

def id
    get('id')
end

#import_contacts(options) ⇒ Object

Creates and/or updates up to 200 contacts in a single API call. When creating or updating a large number of contacts, this method is significantly faster than sending a separate API request for each contact.

By default, if the phone number for any contact matches an existing contact, the existing contact will be updated with any information provided. This behavior can be modified by setting the lookup_key parameter to look up contacts by another field, including a custom variable.

If any contact was not found matching the provided lookup_key, a new contact will be created.

Arguments:

- options (Hash)
  * Required

- contacts (array)
    * Array of up to 200 objects which may contain the properties `name` (string),
        `phone_number` (string), `vars` (object), and `send_blocked` (boolean). All
        properties are optional, unless used as a lookup key; however, either a `name` or
        `phone_number` property must be provided for new contacts.
    * Required

- lookup_key
    * The field used to search for a matching contact, or 'none' to always create a new
        contact. To search by a custom variable, precede the variable name with 'vars.'.
    * Allowed values: phone_number, id, vars.variable_name, none
    * Default: phone_number

- add_group_ids (array)
    * ID of one or more groups to add these contacts as members (max 5)

- remove_group_ids (array)
    * ID of one or more groups to remove these contacts as members (max 5)

- default_route_id
    * ID of the route to use by default to send messages to these contacts

Returns: (associative array) - contacts (array) * List of objects representing each contact, with the same length and order as provided in the contacts parameter in the API request. Each object has a string id property.



975
976
977
978
 
# File 'lib/telerivet/project.rb', line 975

def import_contacts(options)
    data = @api.do_request("POST", get_base_api_path() + "/import_contacts", options)
    return data
end

#init_airtime_transaction_by_id(id) ⇒ Object

Initializes an airtime transaction by ID without making an API request.

Arguments:

- id
  * ID of the airtime transaction
  * Required

Returns: Telerivet::AirtimeTransaction



3458
3459
3460
3461
 
# File 'lib/telerivet/project.rb', line 3458

def init_airtime_transaction_by_id(id)
    require_relative 'airtimetransaction'
    return AirtimeTransaction.new(@api, {'project_id' => self.id, 'id' => id}, false)
end

#init_broadcast_by_id(id) ⇒ Object

Initializes the Telerivet broadcast with the given ID without making an API request.

Arguments:

- id
  * ID of the broadcast
  * Required

Returns: Telerivet::Broadcast



1567
1568
1569
1570
 
# File 'lib/telerivet/project.rb', line 1567

def init_broadcast_by_id(id)
    require_relative 'broadcast'
    return Broadcast.new(@api, {'project_id' => self.id, 'id' => id}, false)
end

#init_campaign_by_id(id) ⇒ Object

Initializes the Telerivet campaign with the given ID without making an API request.

Arguments:

- id
  * ID of the campaign
  * Required

Returns: Telerivet::Campaign



1663
1664
1665
1666
 
# File 'lib/telerivet/project.rb', line 1663

def init_campaign_by_id(id)
    require_relative 'campaign'
    return Campaign.new(@api, {'project_id' => self.id, 'id' => id}, false)
end

#init_contact_by_id(id) ⇒ Object

Initializes the Telerivet contact with the given ID without making an API request.

Arguments:

- id
  * ID of the contact
  * Required

Returns: Telerivet::Contact



1091
1092
1093
1094
 
# File 'lib/telerivet/project.rb', line 1091

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

#init_data_table_by_id(id) ⇒ Object

Initializes the data table with the given ID without making an API request.

Arguments:

- id
  * ID of the data table
  * Required

Returns: Telerivet::DataTable



2641
2642
2643
2644
 
# File 'lib/telerivet/project.rb', line 2641

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

#init_file_by_id(id) ⇒ Object

Initializes the stored file with the given ID without making an API request.

Arguments:

- id
  * ID of the stored file
  * Required

Returns: Telerivet::StoredFile



2556
2557
2558
2559
 
# File 'lib/telerivet/project.rb', line 2556

def init_file_by_id(id)
    require_relative 'storedfile'
    return StoredFile.new(@api, {'project_id' => self.id, 'id' => id}, false)
end

#init_group_by_id(id) ⇒ Object

Initializes the group with the given ID without making an API request.

Arguments:

- id
  * ID of the group
  * Required

Returns: Telerivet::Group



2210
2211
2212
2213
 
# File 'lib/telerivet/project.rb', line 2210

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

#init_label_by_id(id) ⇒ Object

Initializes the label with the given ID without making an API request.

Arguments:

- id
  * ID of the label
  * Required

Returns: Telerivet::Label



2295
2296
2297
2298
 
# File 'lib/telerivet/project.rb', line 2295

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

#init_message_by_id(id) ⇒ Object

Initializes the Telerivet message with the given ID without making an API request.

Arguments:

- id
  * ID of the message
  * Required

Returns: Telerivet::Message



1491
1492
1493
1494
 
# File 'lib/telerivet/project.rb', line 1491

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

#init_message_template_by_id(id) ⇒ Object

Initializes the message template with the given ID without making an API request.

Arguments:

- id
  * ID of the message template
  * Required

Returns: Telerivet::MessageTemplate



2411
2412
2413
2414
 
# File 'lib/telerivet/project.rb', line 2411

def init_message_template_by_id(id)
    require_relative 'messagetemplate'
    return MessageTemplate.new(@api, {'project_id' => self.id, 'id' => id}, false)
end

#init_phone_by_id(id) ⇒ Object

Initializes the basic route with the given ID without making an API request.

Arguments:

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

Returns: Telerivet::Phone



1171
1172
1173
1174
 
# File 'lib/telerivet/project.rb', line 1171

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

#init_relative_scheduled_message_by_id(id) ⇒ Object

Initializes the relative scheduled message with the given ID without making an API request.

Arguments:

- id
  * ID of the relative scheduled message
  * Required

Returns: Telerivet::RelativeScheduledMessage



2798
2799
2800
2801
 
# File 'lib/telerivet/project.rb', line 2798

def init_relative_scheduled_message_by_id(id)
    require_relative 'relativescheduledmessage'
    return RelativeScheduledMessage.new(@api, {'project_id' => self.id, 'id' => id}, false)
end

#init_route_by_id(id) ⇒ Object

Initializes a custom route by ID without making an API request.

Arguments:

- id
  * ID of the route
  * Required

Returns: Telerivet::Route



3367
3368
3369
3370
 
# File 'lib/telerivet/project.rb', line 3367

def init_route_by_id(id)
    require_relative 'route'
    return Route.new(@api, {'project_id' => self.id, 'id' => id}, false)
end

#init_scheduled_message_by_id(id) ⇒ Object

Initializes the scheduled message with the given ID without making an API request.

Arguments:

- id
  * ID of the scheduled message
  * Required

Returns: Telerivet::ScheduledMessage



2766
2767
2768
2769
 
# File 'lib/telerivet/project.rb', line 2766

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

#init_scheduled_service_by_id(id) ⇒ Object

Initializes the scheduled service with the given ID without making an API request.

Arguments:

- id
  * ID of the scheduled service
  * Required

Returns: Telerivet::ScheduledService



2930
2931
2932
2933
 
# File 'lib/telerivet/project.rb', line 2930

def init_scheduled_service_by_id(id)
    require_relative 'scheduledservice'
    return ScheduledService.new(@api, {'project_id' => self.id, 'id' => id}, false)
end

#init_service_by_id(id) ⇒ Object

Initializes the service with the given ID without making an API request.

Arguments:

- id
  * ID of the service
  * Required

Returns: Telerivet::Service



3148
3149
3150
3151
 
# File 'lib/telerivet/project.rb', line 3148

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

#init_task_by_id(id) ⇒ Object

Initializes the task with the given ID without making an API request.

Arguments:

- id
  * ID of the task
  * Required

Returns: Telerivet::Task



2060
2061
2062
2063
 
# File 'lib/telerivet/project.rb', line 2060

def init_task_by_id(id)
    require_relative 'task'
    return Task.new(@api, {'project_id' => self.id, 'id' => id}, false)
end

#init_webhook_by_id(id) ⇒ Object

Initializes the webhook with the given ID without making an API request.

Arguments:

- id
  * ID of the webhook
  * Required

Returns: Telerivet::Webhook



3930
3931
3932
3933
 
# File 'lib/telerivet/project.rb', line 3930

def init_webhook_by_id(id)
    require_relative 'webhook'
    return Webhook.new(@api, {'project_id' => self.id, 'id' => id}, false)
end

#message_retention_days ⇒ Object 



3986
3987
3988
 
# File 'lib/telerivet/project.rb', line 3986

def message_retention_days
    get('message_retention_days')
end

#message_retention_days=(value) ⇒ Object 



3990
3991
3992
 
# File 'lib/telerivet/project.rb', line 3990

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

#name ⇒ Object 



3946
3947
3948
 
# File 'lib/telerivet/project.rb', line 3946

def name
    get('name')
end

#name=(value) ⇒ Object 



3950
3951
3952
 
# File 'lib/telerivet/project.rb', line 3950

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

#organization_id ⇒ Object 



4002
4003
4004
 
# File 'lib/telerivet/project.rb', line 4002

def organization_id
    get('organization_id')
end

#query_airtime_transactions(options = nil) ⇒ Object

Returns information about each airtime transaction.

Arguments:

- options (Hash)

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

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

- contact_id
    * Filter transactions sent to a particular contact

- to_number
    * Filter transactions sent to a particular phone number

- service_id
    * Filter transactions sent by a particular service

- status
    * Filter transactions by status
    * Allowed values: pending, queued, processing, submitted, successful, failed,
        cancelled, pending_payment, pending_approval

- 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 500)
    * Default: 50

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

Returns: Telerivet::APICursor (of Telerivet::AirtimeTransaction)



3426
3427
3428
3429
 
# File 'lib/telerivet/project.rb', line 3426

def query_airtime_transactions(options = nil)
    require_relative 'airtimetransaction'
    @api.cursor(AirtimeTransaction, get_base_api_path() + "/airtime_transactions", options)
end

#query_broadcasts(options = nil) ⇒ Object

Queries broadcasts within the given project.

Arguments:

- options (Hash)

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

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

- last_message_time[min] (UNIX timestamp)
    * Filter broadcasts with most recent message on or after a particular time

- last_message_time[max] (UNIX timestamp)
    * Filter broadcasts with most recent message before a particular time

- sort
    * Sort the results based on a field
    * Allowed values: default, 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 500)
    * Default: 50

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

Returns: Telerivet::APICursor (of Telerivet::Broadcast)



1535
1536
1537
1538
 
# File 'lib/telerivet/project.rb', line 1535

def query_broadcasts(options = nil)
    require_relative 'broadcast'
    @api.cursor(Broadcast, get_base_api_path() + "/broadcasts", options)
end

#query_campaigns(options = nil) ⇒ Object

Queries campaigns within the given project.

Arguments:

- options (Hash)

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

- status
    * Filter campaigns by status
    * Allowed values: draft, scheduled, sent, pending_review

- campaign_type
    * Filter campaigns by type
    * Allowed values: broadcast_text, broadcast_call, broadcast_svc, relative,
        anniversary

- group_id
    * Filter campaigns by the recipient group

- label_id
    * Filter campaigns by an associated label

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

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

- schedule_time[min] (UNIX timestamp)
    * Filter broadcast campaigns scheduled on or after a particular time

- schedule_time[max] (UNIX timestamp)
    * Filter broadcast campaigns scheduled before a particular time

- sort
    * Sort the results based on a field
    * Allowed values: default, name, schedule_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 500)
    * Default: 50

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

Returns: Telerivet::APICursor (of Telerivet::Campaign)



1631
1632
1633
1634
 
# File 'lib/telerivet/project.rb', line 1631

def query_campaigns(options = nil)
    require_relative 'campaign'
    @api.cursor(Campaign, get_base_api_path() + "/campaigns", options)
end

#query_contacts(options = nil) ⇒ Object

Queries contacts within the given project.

Arguments:

- options (Hash)

- group_id
    * Filter contacts within a group

- 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], phone_number[exists]

- time_created (UNIX timestamp)
    * Filter contacts by time created
    * Allowed modifiers: 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[min], last_message_time[max],
        last_message_time[exists]

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

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

- incoming_message_count (int)
    * Filter contacts by number of messages received from the contact
    * Allowed modifiers: incoming_message_count[ne], incoming_message_count[min],
        incoming_message_count[max]

- outgoing_message_count (int)
    * Filter contacts by number of messages sent to the contact
    * Allowed modifiers: outgoing_message_count[ne], outgoing_message_count[min],
        outgoing_message_count[max]

- send_blocked (bool)
    * Filter contacts by blocked status

- vars (Hash)
    * Filter contacts by value of a custom variable (e.g. vars[email], vars[foo], etc.)
    * Allowed modifiers: 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], vars[foo][exists]

- 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 500)
    * Default: 50

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

Returns: Telerivet::APICursor (of Telerivet::Contact)



1059
1060
1061
1062
 
# File 'lib/telerivet/project.rb', line 1059

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 500)
    * Default: 50

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

Returns: Telerivet::APICursor (of Telerivet::DataTable)



2593
2594
2595
2596
 
# File 'lib/telerivet/project.rb', line 2593

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

#query_files(options = nil) ⇒ Object

Queries files stored within the given project.

Arguments:

- options (Hash)

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

- type
    * Filter files by MIME type. A type ending in `/*` matches any subtype (e.g.
        `image/*`).

- category
    * Filter files by category
    * Allowed values: outgoing_media, incoming_media, call_audio, test_recording,
        script_module, icon

- source
    * Filter files by how they were created
    * Allowed values: upload, recording, message, api

- size (int)
    * Filter files by size in bytes
    * Allowed modifiers: size[min], size[max]

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

- message_id
    * Filter files associated with a particular message

- sha256
    * Filter files by the SHA-256 hash of the file content (lowercase hex), e.g. to
        check whether a particular file has already been uploaded

- sort
    * Sort the results based on a field
    * Allowed values: default, filename, size, time_created
    * 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 500)
    * Default: 50

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

Returns: Telerivet::APICursor (of Telerivet::StoredFile)



2476
2477
2478
2479
 
# File 'lib/telerivet/project.rb', line 2476

def query_files(options = nil)
    require_relative 'storedfile'
    @api.cursor(StoredFile, get_base_api_path() + "/files", 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]

- dynamic (bool)
    * Filter groups by dynamic/non-dynamic

- 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 500)
    * Default: 50

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

Returns: Telerivet::APICursor (of Telerivet::Group)



2100
2101
2102
2103
 
# File 'lib/telerivet/project.rb', line 2100

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 500)
    * Default: 50

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

Returns: Telerivet::APICursor (of Telerivet::Label)



2247
2248
2249
2250
 
# File 'lib/telerivet/project.rb', line 2247

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

#query_message_templates(options = nil) ⇒ Object

Queries message templates within the given project.

Arguments:

- options (Hash)

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

- waba_id
    * Filter templates by WhatsApp Business Account ID

- 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 500)
    * Default: 50

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

Returns: Telerivet::APICursor (of Telerivet::MessageTemplate)



2335
2336
2337
2338
 
# File 'lib/telerivet/project.rb', line 2335

def query_message_templates(options = nil)
    require_relative 'messagetemplate'
    @api.cursor(MessageTemplate, get_base_api_path() + "/message_templates", options)
end

#query_messages(options = nil) ⇒ Object

Queries messages within the given project.

Arguments:

- options (Hash)

- label_id
    * Filter messages with a label

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

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

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

- 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, read

- 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

- external_id
    * Filter messages by ID from an external provider
    * Allowed modifiers: external_id[ne], external_id[exists]

- contact_id
    * ID of the contact who sent/received the message
    * Allowed modifiers: contact_id[ne], contact_id[exists]

- phone_id
    * ID of the phone (basic route) that sent/received the message

- broadcast_id
    * ID of the broadcast containing the message
    * Allowed modifiers: broadcast_id[ne], broadcast_id[exists]

- scheduled_id
    * ID of the scheduled message that created this message
    * Allowed modifiers: scheduled_id[ne], scheduled_id[exists]

- group_id
    * Filter messages sent or received by contacts in a particular group. The group must
        be a normal group, not a dynamic group.

- 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 500)
    * Default: 50

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

Returns: Telerivet::APICursor (of Telerivet::Message)



1459
1460
1461
1462
 
# File 'lib/telerivet/project.rb', line 1459

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

#query_phones(options = nil) ⇒ Object

Queries basic routes 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[min], last_active_time[max],
        last_active_time[exists]

- 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 500)
    * Default: 50

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

Returns: Telerivet::APICursor (of Telerivet::Phone)



1139
1140
1141
1142
 
# File 'lib/telerivet/project.rb', line 1139

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

#query_relative_scheduled_messages(options = nil) ⇒ Object

Queries relative scheduled messages within the given project.

Arguments:

- options (Hash)

- message_type
    * Filter relative scheduled messages by message_type
    * Allowed values: sms, mms, ussd, ussd_session, call, chat, service

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

- group_id
    * Filter relative scheduled messages sent to a group

- contact_id
    * Filter relative scheduled messages sent to an individual contact

- 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 500)
    * Default: 50

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

Returns: Telerivet::APICursor (of Telerivet::RelativeScheduledMessage)



2734
2735
2736
2737
 
# File 'lib/telerivet/project.rb', line 2734

def query_relative_scheduled_messages(options = nil)
    require_relative 'relativescheduledmessage'
    @api.cursor(RelativeScheduledMessage, get_base_api_path() + "/relative_scheduled", options)
end

#query_routes(options = nil) ⇒ Object

Queries custom routes that can be used to send messages (not including Phones).

Arguments:

- options (Hash)

- name
    * Filter routes 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 500)
    * Default: 50

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

Returns: Telerivet::APICursor (of Telerivet::Route)



3293
3294
3295
3296
 
# File 'lib/telerivet/project.rb', line 3293

def query_routes(options = nil)
    require_relative 'route'
    @api.cursor(Route, get_base_api_path() + "/routes", 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, ussd_session, call, chat, service

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

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

- relative_scheduled_id
    * Filter scheduled messages created for a relative scheduled message

- sort
    * Sort the results based on a field
    * Allowed values: default, next_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 500)
    * Default: 50

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

Returns: Telerivet::APICursor (of Telerivet::ScheduledMessage)



2688
2689
2690
2691
 
# File 'lib/telerivet/project.rb', line 2688

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

#query_scheduled_services(options = nil) ⇒ Object

Queries scheduled services within the given project.

Arguments:

- options (Hash)

- service_id
    * Filter scheduled services by the service ID

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

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

- sort
    * Sort the results based on a field
    * Allowed values: default, next_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 500)
    * Default: 50

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

Returns: Telerivet::APICursor (of Telerivet::ScheduledService)



2841
2842
2843
2844
 
# File 'lib/telerivet/project.rb', line 2841

def query_scheduled_services(options = nil)
    require_relative 'scheduledservice'
    @api.cursor(ScheduledService, get_base_api_path() + "/scheduled_services", options)
end

#query_service_logs(options = nil) ⇒ Object

Queries service log entries associated with this project.

Note: Service logs are automatically deleted and no longer available via the API after approximately one month.

Arguments:

- options (Hash)

- service_id
    * Filter logs generated by a particular service

- message_id
    * Filter service logs related to a particular message

- contact_id
    * Filter service logs related to a particular contact. Ignored if using the
        message_id parameter.

- time_created (UNIX timestamp)
    * Filter service logs by the time they were created
    * Allowed modifiers: time_created[min], time_created[max]

- execution_stats (bool)
    * Show detailed execution stats for each log entry, if available.

- 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 500)
    * Default: 50

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

Returns: Telerivet::APICursor (of Hash)

Returned Item Properties: - time_created (UNIX timestamp) * The time when the log entry was created

- content
    * The text logged

- elapsed_ms (int)
    * Elapsed time in milliseconds, if available.

- service_id
    * ID of the service associated with this log entry. Not returned when querying log
        entries for a particular service.

- message_id
    * ID of the message associated with this log entry. Not returned when querying log
        entries for a particular message.

- contact_id
    * ID of the contact associated with this log entry. Not returned when querying log
        entries for a particular message or contact.

- api_request_count (int)
    * The total number of API requests triggered via the Cloud Script API. (Only
        provided if execution_stats=true.)

- api_request_ms (int)
    * The total execution time of all API requests triggered via the Cloud Script API.
        (Only provided if execution_stats=true.)

- http_request_count (int)
    * The total number of external HTTP requests triggered via the Cloud Script API.
        (Only provided if execution_stats=true.)

- http_request_ms (int)
    * The total execution time of all external HTTP requests triggered via the Cloud
        Script API. (Only provided if execution_stats=true.)

- webhook_count (int)
    * The total number of Webhook API requests triggered. (Only provided if
        execution_stats=true.)

- requests (array)
    *  Details about each API request, external HTTP request, and Cloud Script Module
        loaded via the Cloud Script API. (Only provided if execution_stats=true.)
        
        Each item in the array has the following properties:
        
        - type (string): `api_request`, `http_request`, or
        `module_load`
        - resource (string): A string specific to the type of
        request.
        For module_load, this is the module path. For
        api_request, it contains the HTTP
        method, path, and query string. For http_request, it
        contains the HTTP method and
        URL.
        - elapsed_ms (int): Number of milliseconds elapsed in
        fetching
        this resource
        - status_code (int): Response status code, if available


3257
3258
3259
 
# File 'lib/telerivet/project.rb', line 3257

def query_service_logs(options = nil)
    @api.cursor(nil, get_base_api_path() + "/service_logs", 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, call, ussd_session, row, contact, project,
        airtime_transaction

- 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 500)
    * Default: 50

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

Returns: Telerivet::APICursor (of Telerivet::Service)



3116
3117
3118
3119
 
# File 'lib/telerivet/project.rb', line 3116

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

#query_tasks(options = nil) ⇒ Object

Queries batch tasks within the given project.

Arguments:

- options (Hash)

- 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 500)
    * Default: 50

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

Returns: Telerivet::APICursor (of Telerivet::Task)



2028
2029
2030
2031
 
# File 'lib/telerivet/project.rb', line 2028

def query_tasks(options = nil)
    require_relative 'task'
    @api.cursor(Task, get_base_api_path() + "/tasks", options)
end

#query_webhooks(options = nil) ⇒ Object

Queries webhooks within the given project.

Arguments:

- options (Hash)

- 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 500)
    * Default: 50

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

Returns: Telerivet::APICursor (of Telerivet::Webhook)



3864
3865
3866
3867
 
# File 'lib/telerivet/project.rb', line 3864

def query_webhooks(options = nil)
    require_relative 'webhook'
    @api.cursor(Webhook, get_base_api_path() + "/webhooks", options)
end

#receive_message(options) ⇒ Object

Add an incoming message to Telerivet. Acts the same as if the message was received by a phone. Also triggers any automated services that apply to the message.

Arguments:

- options (Hash)
  * Required

- content
    * Content of the incoming message
    * Required unless `message_type` is `call`

- message_type
    * Type of message
    * Allowed values: sms, call, chat
    * Default: sms

- from_number
    * Phone number that sent the incoming message
    * Required

- phone_id
    * ID of the phone (basic route) that received the message
    * Required

- to_number
    * Phone number that the incoming message was sent to
    * Default: phone number of the phone that received the message

- simulated (bool)
    * If true, Telerivet will not send automated replies to actual phones

- starred (bool)
    * True if this message should be starred

- label_ids (array)
    * Array of IDs of labels to add to this message (maximum 5)

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

Returns: Telerivet::Message



862
863
864
865
 
# File 'lib/telerivet/project.rb', line 862

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

#save ⇒ Object

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



3938
3939
3940
 
# File 'lib/telerivet/project.rb', line 3938

def save()
    super
end

#schedule_message(options) ⇒ Object

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

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) to be invoked for a group or an individual contact. Any service that can be triggered for a contact can be scheduled via this method, whether or not the service actually sends a message.

Arguments:

- options (Hash)
  * Required

- message_type
    * Type of message to send
    * Allowed values: text, sms, mms, ussd, call, chat, service
    * Default: text

- content
    * Content of the message to schedule
    * Required if sending text message

- group_id
    * ID of the group to send the message to

- to_number (string)
    * Phone number to send the message to

- contact_id (string)
    * ID of the contact to send the message to

- 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 route ID

- service_id
    * Service to invoke for each recipient (when `message_type` is `call` or `service`)
    * Required if message_type is service

- audio_url
    * 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
    * The language of the text-to-speech voice (when `message_type` is `call`)
    * 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
    * Default: en-US

- tts_voice
    * The name of the text-to-speech voice (when message_type=call)
    * Allowed values: female, male
    * Default: female

- track_clicks (boolean)
    * If true, URLs in the message content will automatically be replaced with unique
        short URLs.
    * Default: false

- short_link_params (Hash)
    *
        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 (bool)
    * Set to true to evaluate variables like [[contact.name]] in message content. [(See
        available variables)](#variables)
    * Default: false

- media (array)
    * 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).
        
        Alternatively, you can use the `media_urls` parameter with an array of URL
        strings.

- route_params (Hash)
    * 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](#route_params).

- label_ids (array)
    * 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.

- timezone_id
    * TZ database timezone ID; see [List of tz database time zones Wikipedia
        article](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

- vars (Hash)
    * Custom variables to set for this scheduled message, which will be copied to each
        message sent from this scheduled message

Returns: Telerivet::ScheduledMessage



644
645
646
647
 
# File 'lib/telerivet/project.rb', line 644

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

#schedule_service(options) ⇒ Object

Schedules a service to be triggered at a specified time.

Only services that can be triggered for the project context and handle the default event can be scheduled. This includes services with types scheduled_actions, scheduled_script, and other service types that support project-level triggering.

(Note: To schedule services that are triggered for a contact, project.scheduleMessage should be used instead with message_type=service.)

Arguments:

- options (Hash)
  * Required

- service_id
    * ID of the service to schedule
    * Required

- start_time (UNIX timestamp)
    * The time that the service will be triggered (or first triggered for recurring
        scheduled services)
    * Required if start_time_offset not set

- start_time_offset (int)
    * Number of seconds from now to trigger the service

- rrule
    * A recurrence rule describing 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 service, does not repeat)

- timezone_id
    * TZ database timezone ID; see [List of tz database time zones Wikipedia
        article](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
    * Default: project default timezone

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

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

- vars (Hash)
    * Custom variables to store for this scheduled service

Returns: Telerivet::ScheduledService



2898
2899
2900
2901
 
# File 'lib/telerivet/project.rb', line 2898

def schedule_service(options)
    require_relative 'scheduledservice'
    ScheduledService.new(@api, @api.do_request("POST", get_base_api_path() + "/scheduled_services", options))
end

#send_broadcast(options) ⇒ Object

Sends a text message (optionally with mail-merge templates) or voice call to a group or a list of up to 500 phone numbers.

With message_type=service, invokes an automated service (such as a poll) for a group or list of phone numbers. Any service that can be triggered for a contact can be invoked via this method, whether or not the service actually sends a message.

Arguments:

- options (Hash)
  * Required

- message_type
    * Type of message to send. If `text`, will use the default text message type for the
        selected route.
    * Allowed values: text, sms, mms, call, chat, service
    * Default: text

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

- 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 route ID

- title (string)
    * Title of the broadcast. If a title is not provided, a title will automatically be
        generated from the recipient group name or phone numbers.

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

- status_secret
    * POST parameter 'secret' passed to status_url

- label_ids (array)
    * Array of IDs of labels to add to all messages sent (maximum 5). Does not apply
        when `message_type`=`service`, since the labels are determined by the service
        itself.

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

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

- track_clicks (boolean)
    * If true, URLs in the message content will automatically be replaced with unique
        short URLs.
    * Default: false

- short_link_params (Hash)
    *
        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.

- media (array)
    * 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).
        
        Alternatively, you can use the `media_urls` parameter with an array of URL
        strings.

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

- route_params (Hash)
    * Route-specific parameters for the messages in the broadcast.
        
        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](#route_params).

- service_id
    * Service to invoke for each recipient (when `message_type` is `call` or `service`)
    * Required if message_type is service

- audio_url
    * 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
    * The language of the text-to-speech voice (when `message_type` is `call`)
    * 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
    * Default: en-US

- tts_voice
    * The name of the text-to-speech voice (when message_type=call)
    * Allowed values: female, male
    * Default: female

Returns: Telerivet::Broadcast



333
334
335
336
 
# File 'lib/telerivet/project.rb', line 333

def send_broadcast(options)
    require_relative 'broadcast'
    Broadcast.new(@api, @api.do_request("POST", get_base_api_path() + "/send_broadcast", options))
end

#send_message(options) ⇒ Object

Sends one message (SMS, MMS, chat app message, voice call, or USSD request).

Arguments:

- options (Hash)
  * Required

- message_type
    * Type of message to send. If `text`, will use the default text message type for the
        selected route.
    * Allowed values: text, sms, mms, ussd, call, chat, service
    * Default: text

- content
    * Content of the message to send (if `message_type` is `call`, the text will be
        spoken during a text-to-speech call)
    * 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 route 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

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

- track_clicks (boolean)
    * If true, URLs in the message content will automatically be replaced with unique
        short URLs.
    * Default: false

- short_link_params (Hash)
    *
        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.

- media (array)
    * 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).
        
        Alternatively, you can use the `media_urls` parameter with an array of URL
        strings.

- route_params (Hash)
    * Route-specific parameters for 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](#route_params).

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

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

- priority (int)
    * Priority of the message. 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).
    * Allowed values: 1, 2
    * Default: 1

- simulated (bool)
    * Set to true to test the Telerivet API without actually sending a message from the
        route
    * Default: false

- service_id
    * Service that defines the call flow of the voice call (when `message_type` is
        `call`)

- audio_url
    * 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
    * The language of the text-to-speech voice (when `message_type` is `call`)
    * 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
    * Default: en-US

- tts_voice
    * The name of the text-to-speech voice (when message_type=call)
    * Allowed values: female, male
    * Default: female

Returns: Telerivet::Message



200
201
202
203
 
# File 'lib/telerivet/project.rb', line 200

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

(Deprecated) Send a message a to group or a list of phone numbers. This method is only needed to maintain backward compatibility with code developed using previous versions of the client library. Use sendBroadcast or sendMulti instead.

Arguments:

- options (Hash)
  * Required

- message_type

- content
    * Required

- group_id

- to_numbers

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

  - broadcast_id
      * ID of broadcast created for this message batch.


493
494
495
496
 
# File 'lib/telerivet/project.rb', line 493

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

#send_multi(options) ⇒ Object

Sends up to 100 different messages in a single API request. This method is significantly faster than sending a separate API request for each message.

Arguments:

- options (Hash)
  * Required

- messages (array)
    * Array of up to 100 objects with `content` and `to_number` properties. Each object
        may also contain the optional properties `status_url`, `status_secret`, `vars`,
        and/or `priority`, which override the parameters of the same name defined below, to
        allow passing different values for each message.
    * Required

- message_type
    * Type of message to send. If `text`, will use the default text message type for the
        selected route.
    * Allowed values: text, sms, mms, call, chat, service
    * Default: text

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

- broadcast_id (string)
    * ID of an existing broadcast to associate the messages with

- broadcast_title (string)
    * Title of broadcast to create (when `broadcast_id` is not provided).
        When sending more than 100 messages over multiple API
        requests, you can associate all messages with the same broadcast by providing a
        `broadcast_title` parameter in the first
        API request, then retrieving the `broadcast_id` property
        from the API response, and passing it as the `broadcast_id` parameter in subsequent
        API requests.

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

- status_secret
    * POST parameter 'secret' passed to status_url

- label_ids (array)
    * Array of IDs of labels to add to each message (maximum 5)

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

- track_clicks (boolean)
    * If true, URLs in the message content will automatically be replaced with unique
        short URLs.
    * Default: false

- short_link_params (Hash)
    *
        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.

- media (array)
    * 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).
        
        Alternatively, you can use the `media_urls` parameter with an array of URL
        strings.

- route_params (Hash)
    * Route-specific parameters to apply to all messages.
        
        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](#route_params).

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

- priority (int)
    * Priority of the message. 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).
    * Allowed values: 1, 2
    * Default: 1

- simulated (bool)
    * Set to true to test the Telerivet API without actually sending a message from the
        route
    * Default: false

Returns: (associative array) - messages (array) * List of objects representing each newly created message, with the same length and order as provided in the messages parameter in the API request. Each object has the id and status properties, and may have the property error_message. (Other properties of the Message object are omitted in order to reduce the amount of redundant data sent in each API response.) If the messages parameter in the API request contains items with to_number values that are associated with blocked contacts, the id and status properties corresponding to those items will be null, and no messages will be sent to those numbers.

  - broadcast_id
      * ID of broadcast that these messages are associated with, if `broadcast_id` or
          `broadcast_title` parameter is provided in the API request.


461
462
463
464
 
# File 'lib/telerivet/project.rb', line 461

def send_multi(options)
    data = @api.do_request("POST", get_base_api_path() + "/send_multi", options)
    return data
end

#set_contact_field_metadata(variable, options) ⇒ Object

Allows customizing how a custom contact field is displayed in the Telerivet web app.

The variable path parameter can contain the characters a-z, A-Z, 0-9, and _, and may be up to 32 characters in length.

Arguments:

- variable
  * The variable name of the field to create or update.
  * Required

- options (Hash)
  * Required

- name (string, max 64 characters)
    * Display name for the field

- type (int)
    * Field type
    * Allowed values: text, long_text, secret, phone_number, email, url, audio, date,
        date_time, number, boolean, checkbox, select, radio, route

- order (int)
    * Order in which to display the field

- items (array)
    * Array of up to 100 objects containing `value` and `label` string properties to
        show when type is `select` or `radio`. Each `value` and `label` must be between 1
        and 256 characters in length.
    * Required if type is `select` or `radio`

- readonly (bool)
    * Set to true to prevent editing the field in the Telerivet web app

- lookup_key (bool)
    * Set to true to allow using this field as a lookup key when importing contacts via
        the Telerivet web app

- show_on_conversation (bool)
    * Set to true to show field on Conversations tab

Returns: object



3520
3521
3522
 
# File 'lib/telerivet/project.rb', line 3520

def set_contact_field_metadata(variable, options)
    return @api.do_request("POST", get_base_api_path() + "/contact_fields/#{variable}", options)
end

#set_message_field_metadata(variable, options) ⇒ Object

Allows customizing how a custom message field is displayed in the Telerivet web app.

The variable path parameter can contain the characters a-z, A-Z, 0-9, and _, and may be up to 32 characters in length.

Arguments:

- variable
  * The variable name of the field to create or update.
  * Required

- options (Hash)
  * Required

- name (string, max 64 characters)
    * Display name for the field

- type (string)
    * Field type
    * Allowed values: text, long_text, secret, phone_number, email, url, audio, date,
        date_time, number, boolean, checkbox, select, radio, route

- order (int)
    * Order in which to display the field

- items (array)
    * Array of up to 100 objects containing `value` and `label` string properties to
        show when type is `select` or `radio`. Each `value` and `label` must be between 1
        and 256 characters in length.
    * Required if type is `select` or `radio`

- hide_values (bool)
    * Set to true to avoid showing values of this field on the Messages page

Returns: object



3599
3600
3601
 
# File 'lib/telerivet/project.rb', line 3599

def set_message_field_metadata(variable, options)
    return @api.do_request("POST", get_base_api_path() + "/message_fields/#{variable}", options)
end

#short_link_scheme ⇒ Object 



3994
3995
3996
 
# File 'lib/telerivet/project.rb', line 3994

def short_link_scheme
    get('short_link_scheme')
end

#short_link_scheme=(value) ⇒ Object 



3998
3999
4000
 
# File 'lib/telerivet/project.rb', line 3998

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

#timezone_id ⇒ Object 



3954
3955
3956
 
# File 'lib/telerivet/project.rb', line 3954

def timezone_id
    get('timezone_id')
end

#timezone_id=(value) ⇒ Object 



3958
3959
3960
 
# File 'lib/telerivet/project.rb', line 3958

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

#update_contact_fields(options) ⇒ Object

Updates metadata for one or more custom contact fields. Only the specified fields are updated; other fields are not affected.

To delete a field, include an object with the variable and delete properties set (e.g. {"variable": "my_field", "delete": true}). Deleting a field will also clear the corresponding variable on all contacts in the project.

Arguments:

- options (Hash)
  * Required

- metadata (array)
    * Array of up to 100 objects describing the fields to create, update, or delete.
        Each object must contain a `variable` property. Only the properties provided for
        each field will be updated.
    * Required

Returns: array



3545
3546
3547
 
# File 'lib/telerivet/project.rb', line 3545

def update_contact_fields(options)
    return @api.do_request("POST", get_base_api_path() + "/contact_fields", options)
end

#update_message_fields(options) ⇒ Object

Updates metadata for one or more custom message fields. Only the specified fields are updated; other fields are not affected.

To delete a field, include an object with the variable and delete properties set (e.g. {"variable": "my_field", "delete": true}). Deleting a field removes the metadata only; values stored on individual messages are not affected.

Arguments:

- options (Hash)
  * Required

- metadata (array)
    * Array of up to 100 objects describing the fields to create, update, or delete.
        Each object must contain a `variable` property. Only the properties provided for
        each field will be updated.
    * Required

Returns: array



3624
3625
3626
 
# File 'lib/telerivet/project.rb', line 3624

def update_message_fields(options)
    return @api.do_request("POST", get_base_api_path() + "/message_fields", options)
end

#upload_file(options) ⇒ Object

Uploads a file to be stored by Telerivet.

After uploading a file, it can be attached to an outgoing message by passing its ID as a file_id item in the media parameter of project.sendMessage, project.sendBroadcast, or project.sendMulti. This makes it possible to upload a media file once and attach it to many messages, instead of including the file content in every API request.

The file content is provided inline via the data parameter, encoded via Base64, with a maximum decoded file size of 5 MB. Image, video, audio, PDF, and vCard files are supported.

Files are deduplicated by content: if a file previously uploaded via the API in the same project has the same content and MIME type, the existing stored file is returned instead of creating a duplicate.

Arguments:

- options (Hash)
  * Required

- data (string)
    * Base64-encoded file content (max 5 MB decoded). Alternatively, a Base64 data URI
        such as `data:image/jpeg;base64,...`, in which case the `type` parameter may be
        omitted.
    * Required

- filename (string, max 127 characters)
    * Filename of the stored file. If not provided, the filename is generated
        automatically.

- type (string)
    * MIME type of the file, e.g. `image/jpeg`. If `data` is a data URI, the type may be
        omitted, but must match the MIME type of the data URI if provided.
    * Required unless `data` is a data URI

- description (string, max 1000 characters)
    * Description of the file

Returns: Telerivet::StoredFile



2524
2525
2526
2527
 
# File 'lib/telerivet/project.rb', line 2524

def upload_file(options)
    require_relative 'storedfile'
    StoredFile.new(@api, @api.do_request("POST", get_base_api_path() + "/files", options))
end

#url ⇒ Object 



4006
4007
4008
 
# File 'lib/telerivet/project.rb', line 4006

def url
    get('url')
end

#url_slug ⇒ Object 



3962
3963
3964
 
# File 'lib/telerivet/project.rb', line 3962

def url_slug
    get('url_slug')
end

#url_slug=(value) ⇒ Object 



3966
3967
3968
 
# File 'lib/telerivet/project.rb', line 3966

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