Class: Telerivet::Contact

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

Overview

A contact represents a person or other entity that can be communicated with via phone number or other messaging channel within a project.

Each contact has a name, phone number, and custom variables that can be used to personalize messages. Contacts can belong to one or more groups, and can be used as recipients for broadcasts, campaigns, and other messaging operations.

Contacts can be imported or created individually via the API or web app. If the project's auto_create_contacts setting is enabled, a contact will be automatically created for each unique phone number that a message is sent to or received from.

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

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


126
127
128
129
 
# File 'lib/telerivet/contact.rb', line 126

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 



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

def conversation_status
    get('conversation_status')
end

#conversation_status=(value) ⇒ Object 



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

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

#default_route_id ⇒ Object 



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

def default_route_id
    get('default_route_id')
end

#default_route_id=(value) ⇒ Object 



484
485
486
 
# File 'lib/telerivet/contact.rb', line 484

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

#delete ⇒ Object

Deletes this contact.



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

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

#get_base_api_path ⇒ Object 



500
501
502
 
# File 'lib/telerivet/contact.rb', line 500

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

#group_ids ⇒ Object 



488
489
490
 
# File 'lib/telerivet/contact.rb', line 488

def group_ids
    get('group_ids')
end

#id ⇒ Object 



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

def id
    get('id')
end

#incoming_message_count ⇒ Object 



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

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) 


114
115
116
117
 
# File 'lib/telerivet/contact.rb', line 114

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

#last_incoming_message_time ⇒ Object 



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

def last_incoming_message_time
    get('last_incoming_message_time')
end

#last_message_id ⇒ Object 



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

def last_message_id
    get('last_message_id')
end

#last_message_time ⇒ Object 



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

def last_message_time
    get('last_message_time')
end

#last_outgoing_message_time ⇒ Object 



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

def last_outgoing_message_time
    get('last_outgoing_message_time')
end

#message_count ⇒ Object 



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

def message_count
    get('message_count')
end

#name ⇒ Object 



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

def name
    get('name')
end

#name=(value) ⇒ Object 



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

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

#outgoing_message_count ⇒ Object 



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

def outgoing_message_count
    get('outgoing_message_count')
end

#phone_number ⇒ Object 



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

def phone_number
    get('phone_number')
end

#phone_number=(value) ⇒ Object 



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

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

#project_id ⇒ Object 



492
493
494
 
# File 'lib/telerivet/contact.rb', line 492

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)



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

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)



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

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



222
223
224
225
 
# File 'lib/telerivet/contact.rb', line 222

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)



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

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)



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

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


138
139
140
141
142
143
 
# File 'lib/telerivet/contact.rb', line 138

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.



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

def save()
    super
end

#send_blocked ⇒ Object 



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

def send_blocked
    get('send_blocked')
end

#send_blocked=(value) ⇒ Object 



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

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

#set_data(data) ⇒ Object 



505
506
507
508
509
510
511
512
513
 
# File 'lib/telerivet/contact.rb', line 505

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 



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

def time_created
    get('time_created')
end

#time_updated ⇒ Object 



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

def time_updated
    get('time_updated')
end

#url ⇒ Object 



496
497
498
 
# File 'lib/telerivet/contact.rb', line 496

def url
    get('url')
end