Class: Telerivet::Contact

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

Overview

Fields:

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

- name
    * Name of the contact
    * Updatable via API

- phone_number (string)
    * Phone number of the contact
    * Updatable via API

- time_created (UNIX timestamp)
    * Time the contact was added in Telerivet
    * Read-only

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

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

- conversation_status
    * Current status of the conversation with this contact
    * Allowed values: closed, active, handled
    * Updatable via API

- last_message_time (UNIX timestamp)
    * Last time the contact sent or received a message (null if no messages have been sent
        or received)
    * Read-only

- last_incoming_message_time (UNIX timestamp)
    * Last time a message was received from this contact
    * Read-only

- last_outgoing_message_time (UNIX timestamp)
    * Last time a message was sent to this contact
    * Read-only

- message_count (int)
    * Total number of non-deleted messages sent to or received from this contact
    * Read-only

- incoming_message_count (int)
    * Number of messages received from this contact
    * Read-only

- outgoing_message_count (int)
    * Number of messages sent to this contact
    * Read-only

- last_message_id
    * ID of the last message sent to or received from this contact (null if no messages
        have been sent or received)
    * Read-only

- default_route_id
    * ID of the basic route (phone) or custom route that Telerivet will use by default to
        send messages to this contact (null if using project default route)
    * Updatable via API

- group_ids (array of strings)
    * List of IDs of groups that this contact belongs to
    * Read-only

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

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

Instance Method Summary collapse

Methods inherited from Entity

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

Constructor Details

This class inherits a constructor from Telerivet::Entity

Instance Method Details

#add_to_group(group) ⇒ Object

Adds this contact to a group.

Arguments:

- group (Telerivet::Group)
    * Required



111
112
113
114
 
# File 'lib/telerivet/contact.rb', line 111

def add_to_group(group)
    @api.do_request("PUT", group.get_base_api_path() + "/contacts/" + get('id'));
    @group_ids_set[group.id] = true
end

#conversation_status ⇒ Object 



429
430
431
 
# File 'lib/telerivet/contact.rb', line 429

def conversation_status
    get('conversation_status')
end

#conversation_status=(value) ⇒ Object 



433
434
435
 
# File 'lib/telerivet/contact.rb', line 433

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

#default_route_id ⇒ Object 



465
466
467
 
# File 'lib/telerivet/contact.rb', line 465

def default_route_id
    get('default_route_id')
end

#default_route_id=(value) ⇒ Object 



469
470
471
 
# File 'lib/telerivet/contact.rb', line 469

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

#delete ⇒ Object

Deletes this contact.



389
390
391
 
# File 'lib/telerivet/contact.rb', line 389

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

#get_base_api_path ⇒ Object 



481
482
483
 
# File 'lib/telerivet/contact.rb', line 481

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

#group_ids ⇒ Object 



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

def group_ids
    get('group_ids')
end

#id ⇒ Object 



393
394
395
 
# File 'lib/telerivet/contact.rb', line 393

def id
    get('id')
end

#incoming_message_count ⇒ Object 



453
454
455
 
# File 'lib/telerivet/contact.rb', line 453

def incoming_message_count
    get('incoming_message_count')
end

#is_in_group?(group) ⇒ Boolean

Returns true if this contact is in a particular group, false otherwise.

Arguments:

- group (Telerivet::Group)
    * Required

Returns:

bool

Returns:

  • (Boolean) 


99
100
101
102
 
# File 'lib/telerivet/contact.rb', line 99

def is_in_group?(group)
    load()
    return @group_ids_set.has_key?(group.id)
end

#last_incoming_message_time ⇒ Object 



441
442
443
 
# File 'lib/telerivet/contact.rb', line 441

def last_incoming_message_time
    get('last_incoming_message_time')
end

#last_message_id ⇒ Object 



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

def last_message_id
    get('last_message_id')
end

#last_message_time ⇒ Object 



437
438
439
 
# File 'lib/telerivet/contact.rb', line 437

def last_message_time
    get('last_message_time')
end

#last_outgoing_message_time ⇒ Object 



445
446
447
 
# File 'lib/telerivet/contact.rb', line 445

def last_outgoing_message_time
    get('last_outgoing_message_time')
end

#message_count ⇒ Object 



449
450
451
 
# File 'lib/telerivet/contact.rb', line 449

def message_count
    get('message_count')
end

#name ⇒ Object 



397
398
399
 
# File 'lib/telerivet/contact.rb', line 397

def name
    get('name')
end

#name=(value) ⇒ Object 



401
402
403
 
# File 'lib/telerivet/contact.rb', line 401

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

#outgoing_message_count ⇒ Object 



457
458
459
 
# File 'lib/telerivet/contact.rb', line 457

def outgoing_message_count
    get('outgoing_message_count')
end

#phone_number ⇒ Object 



405
406
407
 
# File 'lib/telerivet/contact.rb', line 405

def phone_number
    get('phone_number')
end

#phone_number=(value) ⇒ Object 



409
410
411
 
# File 'lib/telerivet/contact.rb', line 409

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

#project_id ⇒ Object 



477
478
479
 
# File 'lib/telerivet/contact.rb', line 477

def project_id
    get('project_id')
end

#query_data_rows(options = nil) ⇒ Object

Queries data rows associated with this contact (in any data table).

Arguments:

- options (Hash)

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

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



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

def query_data_rows(options = nil)
    require_relative 'datarow'
    @api.cursor(DataRow, get_base_api_path() + "/rows", options)
end

#query_groups(options = nil) ⇒ Object

Queries groups for which this contact is a member.

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)



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

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

#query_messages(options = nil) ⇒ Object

Queries messages sent or received by this contact.

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

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



207
208
209
210
 
# File 'lib/telerivet/contact.rb', line 207

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

#query_scheduled_messages(options = nil) ⇒ Object

Queries messages scheduled to this contact (not including messages scheduled to groups that this contact is a member of)

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)



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

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

#query_service_states(options = nil) ⇒ Object

Queries this contact’s current states for any service

Arguments:

- options (Hash)

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

  - vars (Hash)
      * Filter states 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
      * 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::ContactServiceState)



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

def query_service_states(options = nil)
    require_relative 'contactservicestate'
    @api.cursor(ContactServiceState, get_base_api_path() + "/states", options)
end

#remove_from_group(group) ⇒ Object

Removes this contact from a group.

Arguments:

- group (Telerivet::Group)
    * Required



123
124
125
126
127
128
 
# File 'lib/telerivet/contact.rb', line 123

def remove_from_group(group)
    @api.do_request("DELETE", group.get_base_api_path() + "/contacts/" + get('id'))
    if @group_ids_set.has_key?(group.id)
        @group_ids_set.delete(group.id)
    end
end

#save ⇒ Object

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



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

def save()
    super
end

#send_blocked ⇒ Object 



421
422
423
 
# File 'lib/telerivet/contact.rb', line 421

def send_blocked
    get('send_blocked')
end

#send_blocked=(value) ⇒ Object 



425
426
427
 
# File 'lib/telerivet/contact.rb', line 425

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

#set_data(data) ⇒ Object 



486
487
488
489
490
491
492
493
494
 
# File 'lib/telerivet/contact.rb', line 486

def set_data(data)
    super
    
    @group_ids_set = {}
    
    if data.has_key?('group_ids')
        data['group_ids'].each { |id| @group_ids_set[id] = true }
    end
end

#time_created ⇒ Object 



413
414
415
 
# File 'lib/telerivet/contact.rb', line 413

def time_created
    get('time_created')
end

#time_updated ⇒ Object 



417
418
419
 
# File 'lib/telerivet/contact.rb', line 417

def time_updated
    get('time_updated')
end