Class: Telerivet::Service

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

Overview

Represents an automated service on Telerivet, for example a poll, auto-reply, webhook service, etc.

A service, generally, defines some automated behavior that can be invoked/triggered in a particular context, and may be invoked either manually or when a particular event occurs.

Most commonly, services work in the context of a particular message, when the message is originally received by Telerivet.

Fields:

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

- name
  * Name of the service
  * Updatable via API

- service_type
  * Type of the service.
  * Read-only

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

- priority (int)
  * A number that determines the order that services are triggered when a particular
      event occurs (smaller numbers are triggered first). Any service can determine whether
      or not execution "falls-through" to subsequent services (with larger priority values)
      by setting the return_value variable within Telerivet's Rules Engine.
  * Updatable via API

- contexts (Hash)
  * A key/value map where the keys are the names of contexts supported by this service
      (e.g. message, contact), and the values are themselves key/value maps where the keys
      are event names and the values are all true. (This structure makes it easy to test
      whether a service can be invoked for a particular context and event.)
  * Read-only

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

- url
  * URL to this service in the Telerivet web app
  * Read-only

- url_edit
  * URL to edit the service in the Telerivet web app
  * Read-only

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

- response_table_id
  * ID of the data table where responses to this service will be stored
  * Updatable via API

- phone_ids (array)
  * IDs of phones (basic routes) associated with this service, or null if the service is
      associated with all routes. Only applies for service types that handle incoming
      messages, voice calls, or USSD sessions.
  * Updatable via API

- message_types (array of strings)
  * Types of messages that this service handles. Only provided for service types that
      handle incoming messages.
  * Allowed values: text, call, ussd
  * Updatable via API

- table_ids (array)
  * IDs of data tables that this service applies to, or null if this service applies to
      all data tables. Only provided for data row services (`data_row_script` and
      `data_row_actions`).
  * Updatable via API

- message_statuses (array of strings)
  * Message statuses that this service handles. Only provided for
      `message_status_actions` services.
  * Allowed values: sent, delivered, failed, failed_queued, not_delivered
  * Updatable via API

- tags (array)
  * Tags used to organize this service. Each tag can be up to 32 characters in length.
  * Updatable via API

- 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
  * Updatable via API

- 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
  * Updatable via API

- show_action (bool)
  * Whether this service is shown in the 'Actions' menu within the Telerivet web app
      when the service is active. Only provided for service types that are manually
      triggered.
  * Updatable via API

- 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
  * Updatable via API

- webhook_url
  * URL that a third-party can invoke to trigger this service. Only provided for
      services that are triggered by a webhook request.
  * Read-only

- is_custom_template (bool)
  * Whether this service was created from a custom service template
  * 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

#active ⇒ Object 



419
420
421
 
# File 'lib/telerivet/service.rb', line 419

def active
    get('active')
end

#active=(value) ⇒ Object 



423
424
425
 
# File 'lib/telerivet/service.rb', line 423

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

#apply_mode ⇒ Object 



499
500
501
 
# File 'lib/telerivet/service.rb', line 499

def apply_mode
    get('apply_mode')
end

#apply_mode=(value) ⇒ Object 



503
504
505
 
# File 'lib/telerivet/service.rb', line 503

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

#contact_number_filter ⇒ Object 



507
508
509
 
# File 'lib/telerivet/service.rb', line 507

def contact_number_filter
    get('contact_number_filter')
end

#contact_number_filter=(value) ⇒ Object 



511
512
513
 
# File 'lib/telerivet/service.rb', line 511

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

#contexts ⇒ Object 



435
436
437
 
# File 'lib/telerivet/service.rb', line 435

def contexts
    get('contexts')
end

#delete ⇒ Object

Deletes this service.



399
400
401
 
# File 'lib/telerivet/service.rb', line 399

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

#direction ⇒ Object 



523
524
525
 
# File 'lib/telerivet/service.rb', line 523

def direction
    get('direction')
end

#direction=(value) ⇒ Object 



527
528
529
 
# File 'lib/telerivet/service.rb', line 527

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

#get_base_api_path ⇒ Object 



539
540
541
 
# File 'lib/telerivet/service.rb', line 539

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

#get_config ⇒ Object

Gets configuration specific to the type of automated service.

Only certain types of services provide their configuration via the API. See Service Configuration Reference or the machine-readable OpenAPI specification for available configuration options.

Returns: object



361
362
363
 
# File 'lib/telerivet/service.rb', line 361

def get_config()
    return @api.do_request("GET", get_base_api_path() + "/config")
end

#get_contact_state(contact) ⇒ Object

Gets the current state for a particular contact for this service.

If the contact doesn't already have a state, this method will return a valid state object with id=null. However this object would not be returned by queryContactStates() unless it is saved with a non-null state id.

Arguments:

- contact (Telerivet::Contact)
  * The contact whose state you want to retrieve.
  * Required

Returns: Telerivet::ContactServiceState



254
255
256
257
 
# File 'lib/telerivet/service.rb', line 254

def get_contact_state(contact)
    require_relative 'contactservicestate'
    ContactServiceState.new(@api, @api.do_request('GET', get_base_api_path() + '/states/' + contact.id))
end

#id ⇒ Object 



403
404
405
 
# File 'lib/telerivet/service.rb', line 403

def id
    get('id')
end

#invoke(options) ⇒ Object

Manually invoke this service in a particular context.

For example, to send a poll to a particular contact (or resend the current question), you can invoke the poll service with context=contact, and contact_id as the ID of the contact to send the poll to. (To trigger a service to multiple contacts, use project.sendBroadcast. To schedule a service in the future, use project.scheduleMessage.)

Or, to manually apply a service for an incoming message, you can invoke the service with context=message, event=incoming_message, and message_id as the ID of the incoming message. (This is normally not necessary, but could be used if you want to override Telerivet's standard priority-ordering of services.)

Arguments:

- options (Hash)
  * Required

- context
    * The name of the context in which this service is invoked
    * Allowed values: message, call, ussd_session, row, contact, project,
        airtime_transaction
    * Required

- event
    * The name of the event that is triggered (must be supported by this service)
    * Default: default

- message_id
    * The ID of the message this service is triggered for
    * Required if context is 'message'

- contact_id
    * The ID of the contact this service is triggered for (either `contact_id` or
        `phone_number` is required if `context` is 'contact')

- phone_number
    * The phone number of the contact this service is triggered for (either `contact_id`
        or `phone_number` is required if `context` is 'contact'). If no  contact exists with
        this phone number, a new contact will be created.

- row_id
    * The ID of the data row this service is triggered for
    * Required if context is 'row'

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

- route_id
    * The ID of the phone or route that the service will use for sending messages by
        default

- async (bool)
    * If set to true, the service will be invoked asynchronously. By default, queued
        services will be invoked one at a time for each project.

Returns: (associative array) - return_value (any) * Return value of the service. May be any JSON type (boolean, number, string, array, object, or null). (Undefined if async=true.)

  - log_entries (array)
      * Array of log entry strings generated by the service. (Undefined if async=true.)
  
  - errors (array)
      * Array of error message strings generated by the service. (Undefined if
          async=true.)
  
  - sent_messages (array of objects)
      * Array of messages sent by the service.
  
  - airtime_transactions (array of objects)
      * Array of airtime transactions sent by the service (Undefined if async=true.)


221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
 
# File 'lib/telerivet/service.rb', line 221

def invoke(options)        
    invoke_result = @api.do_request('POST', get_base_api_path() + '/invoke', options)
    
    if invoke_result.has_key?('sent_messages')
        require_relative 'message'
    
        sent_messages = []
        
        invoke_result['sent_messages'].each { |sent_message_data|
            sent_messages.push(Message.new(@api, sent_message_data))
        }
        
        invoke_result['sent_messages'] = sent_messages
    end
        
    return invoke_result
end

#is_custom_template ⇒ Object 



535
536
537
 
# File 'lib/telerivet/service.rb', line 535

def is_custom_template
    get('is_custom_template')
end

#message_statuses ⇒ Object 



483
484
485
 
# File 'lib/telerivet/service.rb', line 483

def message_statuses
    get('message_statuses')
end

#message_statuses=(value) ⇒ Object 



487
488
489
 
# File 'lib/telerivet/service.rb', line 487

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

#message_types ⇒ Object 



467
468
469
 
# File 'lib/telerivet/service.rb', line 467

def message_types
    get('message_types')
end

#message_types=(value) ⇒ Object 



471
472
473
 
# File 'lib/telerivet/service.rb', line 471

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

#name ⇒ Object 



407
408
409
 
# File 'lib/telerivet/service.rb', line 407

def name
    get('name')
end

#name=(value) ⇒ Object 



411
412
413
 
# File 'lib/telerivet/service.rb', line 411

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

#phone_ids ⇒ Object 



459
460
461
 
# File 'lib/telerivet/service.rb', line 459

def phone_ids
    get('phone_ids')
end

#phone_ids=(value) ⇒ Object 



463
464
465
 
# File 'lib/telerivet/service.rb', line 463

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

#priority ⇒ Object 



427
428
429
 
# File 'lib/telerivet/service.rb', line 427

def priority
    get('priority')
end

#priority=(value) ⇒ Object 



431
432
433
 
# File 'lib/telerivet/service.rb', line 431

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

#project_id ⇒ Object 



447
448
449
 
# File 'lib/telerivet/service.rb', line 447

def project_id
    get('project_id')
end

#query_contact_states(options = nil) ⇒ Object

Query the current states of contacts for this 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)



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

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

#reset_contact_state(contact) ⇒ Object

Resets the current state for a particular contact for the given service.

Arguments:

- contact (Telerivet::Contact)
  * The contact whose state you want to reset.
  * Required

Returns: Telerivet::ContactServiceState



303
304
305
306
 
# File 'lib/telerivet/service.rb', line 303

def reset_contact_state(contact)
    require_relative 'contactservicestate'
    ContactServiceState.new(@api, @api.do_request('DELETE', get_base_api_path() + '/states/' + contact.id))
end

#response_table_id ⇒ Object 



451
452
453
 
# File 'lib/telerivet/service.rb', line 451

def response_table_id
    get('response_table_id')
end

#response_table_id=(value) ⇒ Object 



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

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

#save ⇒ Object

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



392
393
394
 
# File 'lib/telerivet/service.rb', line 392

def save()
    super
end

#service_type ⇒ Object 



415
416
417
 
# File 'lib/telerivet/service.rb', line 415

def service_type
    get('service_type')
end

#set_config(options) ⇒ Object

Updates configuration specific to the type of automated service.

Only certain types of services support updating their configuration via the API.

Note: when updating a service of type custom_template_instance, the validation script will be invoked when calling this method.

Arguments:

- options (Hash)
  * Configuration for this service type. See [Service Configuration
      Reference](#service_config) or the machine-readable [OpenAPI
      specification](https://api.telerivet.com/openapi.json) for available configuration
      options.
  * Required

Returns: object



385
386
387
 
# File 'lib/telerivet/service.rb', line 385

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

#set_contact_state(contact, options) ⇒ Object

Initializes or updates the current state for a particular contact for the given service. If the state id is null, the contact's state will be reset.

Arguments:

- contact (Telerivet::Contact)
  * The contact whose state you want to update.
  * Required

- options (Hash)
  * Required

- id (string, max 63 characters)
    * Arbitrary string representing the contact's current state for this service, e.g.
        'q1', 'q2', etc.
    * Required

- vars (Hash)
    * Custom variables stored for this contact's state. 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::ContactServiceState



287
288
289
290
 
# File 'lib/telerivet/service.rb', line 287

def set_contact_state(contact, options)
    require_relative 'contactservicestate'
    ContactServiceState.new(@api, @api.do_request('POST', get_base_api_path() + '/states/' + contact.id, options))
end

#show_action ⇒ Object 



515
516
517
 
# File 'lib/telerivet/service.rb', line 515

def show_action
    get('show_action')
end

#show_action=(value) ⇒ Object 



519
520
521
 
# File 'lib/telerivet/service.rb', line 519

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

#table_ids ⇒ Object 



475
476
477
 
# File 'lib/telerivet/service.rb', line 475

def table_ids
    get('table_ids')
end

#table_ids=(value) ⇒ Object 



479
480
481
 
# File 'lib/telerivet/service.rb', line 479

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

#tags ⇒ Object 



491
492
493
 
# File 'lib/telerivet/service.rb', line 491

def tags
    get('tags')
end

#tags=(value) ⇒ Object 



495
496
497
 
# File 'lib/telerivet/service.rb', line 495

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

#url ⇒ Object 



439
440
441
 
# File 'lib/telerivet/service.rb', line 439

def url
    get('url')
end

#url_edit ⇒ Object 



443
444
445
 
# File 'lib/telerivet/service.rb', line 443

def url_edit
    get('url_edit')
end

#webhook_url ⇒ Object 



531
532
533
 
# File 'lib/telerivet/service.rb', line 531

def webhook_url
    get('webhook_url')
end