Class: Telerivet::Phone

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

Overview

Represents a basic route (i.e. a phone or gateway) that you use to send/receive messages via Telerivet.

Basic Routes were formerly referred to as "Phones" within Telerivet. API methods, parameters, and properties related to Basic Routes continue to use the term "Phone" to maintain backwards compatibility.

Fields:

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

- name
  * Name of the phone
  * Updatable via API

- phone_number (string)
  * Phone number or sender ID
  * Updatable via API

- phone_type
  * Type of this phone/route (e.g. android, twilio, nexmo, etc)
  * Read-only

- country
  * 2-letter country code (ISO 3166-1 alpha-2) where phone is from
  * Read-only

- send_paused (bool)
  * True if sending messages is currently paused, false if the phone can currently send
      messages
  * Updatable via API

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

- last_active_time (UNIX timestamp)
  * Approximate time this phone last connected to Telerivet
  * Read-only

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

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

- validate_recipient_numbers (bool)
  * Set to true to check that recipient phone numbers appear to be valid before sending
      messages. Messages to invalid phone numbers will fail without being sent. Only applies
      to phones capable of sending messages.
  * Updatable via API

- 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. When null, there is no restriction on recipient countries.
  * Updatable via API

- sent_message_limit (int)
  * Maximum number of messages that can be sent from this phone in a given period. When
      the sent_message_count reaches this limit, sending is automatically paused. Set to
      null to disable the limit.
  * Updatable via API

- sent_message_count (int)
  * Number of messages sent from this phone since the counter was last reset (see
      sent_message_epoch). This property is not updated if sent_message_limit is null.
  * Read-only

- sent_message_epoch (UNIX timestamp)
  * The UNIX timestamp when the sent_message_count was last reset to 0.
  * Read-only

- send_delay (number)
  * Number of seconds to wait after sending each message from this phone, to avoid
      exceeding carrier rate limits.
  * Updatable via API

- timezone_id (string)
  * A string specifying the time zone that will be used when implementing quiet hours or
      estimating send times; see [List of tz database time zones Wikipedia
      article](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones). When null, the
      project's default time zone is used.
  * Updatable via API

- quiet_mode (string)
  * Controls behavior during quiet hours (see quiet_start/quiet_end). Possible values
      are 'off' (quiet hours disabled), 'delay' (messages are delayed until quiet hours
      end), or 'confirm' (requires manual confirmation to send during quiet hours).
  * Allowed values: off, delay, confirm
  * Updatable via API

- quiet_start (string)
  * Time of day when quiet hours begin, in HH:MM format (24-hour time) in the phone's
      time zone. Messages sent during quiet hours are delayed or require confirmation
      depending on quiet_mode. Only applicable when quiet_mode is not 'off'.
  * Updatable via API

- quiet_end (string)
  * Time of day when quiet hours end, in HH:MM format (24-hour time) in the phone's time
      zone. Messages sent during quiet hours are delayed or require confirmation depending
      on quiet_mode. Only applicable when quiet_mode is not 'off'.
  * Updatable via API

- battery (int)
  * Current battery level, on a scale from 0 to 100, as of the last time the phone
      connected to Telerivet (only present for Android phones)
  * Read-only

- charging (bool)
  * True if the phone is currently charging, false if it is running on battery, as of
      the last time it connected to Telerivet (only present for Android phones)
  * Read-only

- internet_type
  * String describing the current type of internet connectivity for an Android phone,
      for example WIFI or MOBILE (only present for Android phones)
  * Read-only

- app_version
  * Currently installed version of Telerivet Android app (only present for Android
      phones)
  * Read-only

- android_sdk (int)
  * Android SDK level, indicating the approximate version of the Android OS installed on
      this phone; see [list of Android SDK
      levels](http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)
      (only present for Android phones)
  * Read-only

- mccmnc
  * Code indicating the Android phone's current country (MCC) and mobile network
      operator (MNC); see [Mobile country code Wikipedia
      article](https://en.wikipedia.org/wiki/Mobile_country_code) (only present for Android
      phones). Note this is a string containing numeric digits, not an integer.
  * Read-only

- manufacturer
  * Android phone manufacturer (only present for Android phones)
  * Read-only

- model
  * Android phone model (only present for Android phones)
  * Read-only

- send_limit (int)
  * Maximum number of SMS messages per hour that can be sent by this Android phone. To
      increase this limit, install additional SMS expansion packs in the Telerivet Gateway
      app. (only present for Android phones)
  * Read-only

- external_account_id (string)
  * Account ID for the external API (e.g. Twilio Account SID, Vonage API Key). Only
      present for routes that support external API configuration. See
      [createPhone](#Project.createPhone) for the meaning of this field for each phone type.
  * Updatable via API

- external_id (string)
  * External phone/resource ID within the external API account (if applicable). Only
      present for routes that support external API configuration.
  * Updatable via API

- external_config (Hash)
  * Additional configuration settings specific to the phone_type. Only present for
      routes that support external API configuration. See
      [createPhone](#Project.createPhone) for available settings for each phone type.
  * Updatable via API

- external_setup (Hash)
  * Configuration info for routes that require manual webhook setup. Only present for
      routes that require manual configuration of callback URLs with the external provider.
      Contains URL properties for each webhook type that needs to be configured (e.g.,
      `incoming_message_url`, `message_status_url`, `incoming_call_url`).
  * Read-only

- external_secret (string)
  * Secret/API key for the external API (e.g. Twilio Auth Token, Vonage API Secret).
      Only applicable for routes that support external API configuration. Write-only; not
      returned by the API when retrieving a phone.
  * Updatable via API

- url
  * URL to this phone 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

#allowed_recipient_countries ⇒ Object 



354
355
356
 
# File 'lib/telerivet/phone.rb', line 354

def allowed_recipient_countries
    get('allowed_recipient_countries')
end

#allowed_recipient_countries=(value) ⇒ Object 



358
359
360
 
# File 'lib/telerivet/phone.rb', line 358

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

#android_sdk ⇒ Object 



434
435
436
 
# File 'lib/telerivet/phone.rb', line 434

def android_sdk
    get('android_sdk')
end

#app_version ⇒ Object 



430
431
432
 
# File 'lib/telerivet/phone.rb', line 430

def app_version
    get('app_version')
end

#battery ⇒ Object 



418
419
420
 
# File 'lib/telerivet/phone.rb', line 418

def battery
    get('battery')
end

#charging ⇒ Object 



422
423
424
 
# File 'lib/telerivet/phone.rb', line 422

def charging
    get('charging')
end

#country ⇒ Object 



322
323
324
 
# File 'lib/telerivet/phone.rb', line 322

def country
    get('country')
end

#external_account_id ⇒ Object 



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

def 
    get('external_account_id')
end

#external_account_id=(value) ⇒ Object 



458
459
460
 
# File 'lib/telerivet/phone.rb', line 458

def (value)
    set('external_account_id', value)
end

#external_config ⇒ Object 



470
471
472
 
# File 'lib/telerivet/phone.rb', line 470

def external_config
    get('external_config')
end

#external_config=(value) ⇒ Object 



474
475
476
 
# File 'lib/telerivet/phone.rb', line 474

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

#external_id ⇒ Object 



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

def external_id
    get('external_id')
end

#external_id=(value) ⇒ Object 



466
467
468
 
# File 'lib/telerivet/phone.rb', line 466

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

#external_secret ⇒ Object 



482
483
484
 
# File 'lib/telerivet/phone.rb', line 482

def external_secret
    get('external_secret')
end

#external_secret=(value) ⇒ Object 



486
487
488
 
# File 'lib/telerivet/phone.rb', line 486

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

#external_setup ⇒ Object 



478
479
480
 
# File 'lib/telerivet/phone.rb', line 478

def external_setup
    get('external_setup')
end

#get_base_api_path ⇒ Object 



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

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

#id ⇒ Object 



298
299
300
 
# File 'lib/telerivet/phone.rb', line 298

def id
    get('id')
end

#internet_type ⇒ Object 



426
427
428
 
# File 'lib/telerivet/phone.rb', line 426

def internet_type
    get('internet_type')
end

#last_active_time ⇒ Object 



338
339
340
 
# File 'lib/telerivet/phone.rb', line 338

def last_active_time
    get('last_active_time')
end

#manufacturer ⇒ Object 



442
443
444
 
# File 'lib/telerivet/phone.rb', line 442

def manufacturer
    get('manufacturer')
end

#mccmnc ⇒ Object 



438
439
440
 
# File 'lib/telerivet/phone.rb', line 438

def mccmnc
    get('mccmnc')
end

#model ⇒ Object 



446
447
448
 
# File 'lib/telerivet/phone.rb', line 446

def model
    get('model')
end

#name ⇒ Object 



302
303
304
 
# File 'lib/telerivet/phone.rb', line 302

def name
    get('name')
end

#name=(value) ⇒ Object 



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

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

#phone_number ⇒ Object 



310
311
312
 
# File 'lib/telerivet/phone.rb', line 310

def phone_number
    get('phone_number')
end

#phone_number=(value) ⇒ Object 



314
315
316
 
# File 'lib/telerivet/phone.rb', line 314

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

#phone_type ⇒ Object 



318
319
320
 
# File 'lib/telerivet/phone.rb', line 318

def phone_type
    get('phone_type')
end

#project_id ⇒ Object 



342
343
344
 
# File 'lib/telerivet/phone.rb', line 342

def project_id
    get('project_id')
end

#query_messages(options = nil) ⇒ Object

Queries messages sent or received by this basic route.

Arguments:

- options (Hash)

- 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)



277
278
279
280
 
# File 'lib/telerivet/phone.rb', line 277

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

#quiet_end ⇒ Object 



410
411
412
 
# File 'lib/telerivet/phone.rb', line 410

def quiet_end
    get('quiet_end')
end

#quiet_end=(value) ⇒ Object 



414
415
416
 
# File 'lib/telerivet/phone.rb', line 414

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

#quiet_mode ⇒ Object 



394
395
396
 
# File 'lib/telerivet/phone.rb', line 394

def quiet_mode
    get('quiet_mode')
end

#quiet_mode=(value) ⇒ Object 



398
399
400
 
# File 'lib/telerivet/phone.rb', line 398

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

#quiet_start ⇒ Object 



402
403
404
 
# File 'lib/telerivet/phone.rb', line 402

def quiet_start
    get('quiet_start')
end

#quiet_start=(value) ⇒ Object 



406
407
408
 
# File 'lib/telerivet/phone.rb', line 406

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

#reset_sent_message_count ⇒ Object

Resets this route's sent_message_count to 0 and updates sent_message_epoch to the current time. If sending was automatically paused because the previous count reached the limit, sending will be resumed.



294
295
296
 
# File 'lib/telerivet/phone.rb', line 294

def reset_sent_message_count()
    @api.do_request("POST", get_base_api_path() + "/reset_sent_message_count")
end

#save ⇒ Object

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



285
286
287
 
# File 'lib/telerivet/phone.rb', line 285

def save()
    super
end

#send_delay ⇒ Object 



378
379
380
 
# File 'lib/telerivet/phone.rb', line 378

def send_delay
    get('send_delay')
end

#send_delay=(value) ⇒ Object 



382
383
384
 
# File 'lib/telerivet/phone.rb', line 382

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

#send_limit ⇒ Object 



450
451
452
 
# File 'lib/telerivet/phone.rb', line 450

def send_limit
    get('send_limit')
end

#send_paused ⇒ Object 



326
327
328
 
# File 'lib/telerivet/phone.rb', line 326

def send_paused
    get('send_paused')
end

#send_paused=(value) ⇒ Object 



330
331
332
 
# File 'lib/telerivet/phone.rb', line 330

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

#sent_message_count ⇒ Object 



370
371
372
 
# File 'lib/telerivet/phone.rb', line 370

def sent_message_count
    get('sent_message_count')
end

#sent_message_epoch ⇒ Object 



374
375
376
 
# File 'lib/telerivet/phone.rb', line 374

def sent_message_epoch
    get('sent_message_epoch')
end

#sent_message_limit ⇒ Object 



362
363
364
 
# File 'lib/telerivet/phone.rb', line 362

def sent_message_limit
    get('sent_message_limit')
end

#sent_message_limit=(value) ⇒ Object 



366
367
368
 
# File 'lib/telerivet/phone.rb', line 366

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

#time_created ⇒ Object 



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

def time_created
    get('time_created')
end

#timezone_id ⇒ Object 



386
387
388
 
# File 'lib/telerivet/phone.rb', line 386

def timezone_id
    get('timezone_id')
end

#timezone_id=(value) ⇒ Object 



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

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

#url ⇒ Object 



490
491
492
 
# File 'lib/telerivet/phone.rb', line 490

def url
    get('url')
end

#validate_recipient_numbers ⇒ Object 



346
347
348
 
# File 'lib/telerivet/phone.rb', line 346

def validate_recipient_numbers
    get('validate_recipient_numbers')
end

#validate_recipient_numbers=(value) ⇒ Object 



350
351
352
 
# File 'lib/telerivet/phone.rb', line 350

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