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

- 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 



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

def active
    get('active')
end

#active=(value) ⇒ Object 



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

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

#apply_mode ⇒ Object 



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

def apply_mode
    get('apply_mode')
end

#apply_mode=(value) ⇒ Object 



485
486
487
 
# File 'lib/telerivet/service.rb', line 485

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

#contact_number_filter ⇒ Object 



489
490
491
 
# File 'lib/telerivet/service.rb', line 489

def contact_number_filter
    get('contact_number_filter')
end

#contact_number_filter=(value) ⇒ Object 



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

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

#contexts ⇒ Object 



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

def contexts
    get('contexts')
end

#delete ⇒ Object

Deletes this service.



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

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

#direction ⇒ Object 



505
506
507
 
# File 'lib/telerivet/service.rb', line 505

def direction
    get('direction')
end

#direction=(value) ⇒ Object 



509
510
511
 
# File 'lib/telerivet/service.rb', line 509

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

#get_base_api_path ⇒ Object 



521
522
523
 
# File 'lib/telerivet/service.rb', line 521

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](#service_config) for available configuration options.

Returns:

object



353
354
355
 
# File 'lib/telerivet/service.rb', line 353

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



246
247
248
249
 
# File 'lib/telerivet/service.rb', line 246

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 



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

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](#Project.sendBroadcast). To schedule a service in the future, use [project.scheduleMessage](#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.)



213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
 
# File 'lib/telerivet/service.rb', line 213

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 



517
518
519
 
# File 'lib/telerivet/service.rb', line 517

def is_custom_template
    get('is_custom_template')
end

#message_statuses ⇒ Object 



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

def message_statuses
    get('message_statuses')
end

#message_statuses=(value) ⇒ Object 



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

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

#message_types ⇒ Object 



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

def message_types
    get('message_types')
end

#message_types=(value) ⇒ Object 



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

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

#name ⇒ Object 



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

def name
    get('name')
end

#name=(value) ⇒ Object 



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

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

#phone_ids ⇒ Object 



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

def phone_ids
    get('phone_ids')
end

#phone_ids=(value) ⇒ Object 



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

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

#priority ⇒ Object 



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

def priority
    get('priority')
end

#priority=(value) ⇒ Object 



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

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

#project_id ⇒ Object 



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

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)



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

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



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

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 



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

def response_table_id
    get('response_table_id')
end

#response_table_id=(value) ⇒ Object 



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

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.



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

def save()
    super
end

#service_type ⇒ Object 



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

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) for available configuration options.
    * Required

Returns:

object



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

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



279
280
281
282
 
# File 'lib/telerivet/service.rb', line 279

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 



497
498
499
 
# File 'lib/telerivet/service.rb', line 497

def show_action
    get('show_action')
end

#show_action=(value) ⇒ Object 



501
502
503
 
# File 'lib/telerivet/service.rb', line 501

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

#table_ids ⇒ Object 



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

def table_ids
    get('table_ids')
end

#table_ids=(value) ⇒ Object 



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

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

#tags ⇒ Object 



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

def tags
    get('tags')
end

#tags=(value) ⇒ Object 



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

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

#webhook_url ⇒ Object 



513
514
515
 
# File 'lib/telerivet/service.rb', line 513

def webhook_url
    get('webhook_url')
end