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

- 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

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 



367
368
369
 
# File 'lib/telerivet/service.rb', line 367

def active
    get('active')
end

#active=(value) ⇒ Object 



371
372
373
 
# File 'lib/telerivet/service.rb', line 371

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

#apply_mode ⇒ Object 



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

def apply_mode
    get('apply_mode')
end

#apply_mode=(value) ⇒ Object 



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

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

#contact_number_filter ⇒ Object 



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

def contact_number_filter
    get('contact_number_filter')
end

#contact_number_filter=(value) ⇒ Object 



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

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

#contexts ⇒ Object 



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

def contexts
    get('contexts')
end

#delete ⇒ Object

Deletes this service.



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

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

#direction ⇒ Object 



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

def direction
    get('direction')
end

#direction=(value) ⇒ Object 



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

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

#get_base_api_path ⇒ Object 



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

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.

Returns:

object



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

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



210
211
212
213
 
# File 'lib/telerivet/service.rb', line 210

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 



351
352
353
 
# File 'lib/telerivet/service.rb', line 351

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
      * 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.

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



177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
 
# File 'lib/telerivet/service.rb', line 177

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

#name ⇒ Object 



355
356
357
 
# File 'lib/telerivet/service.rb', line 355

def name
    get('name')
end

#name=(value) ⇒ Object 



359
360
361
 
# File 'lib/telerivet/service.rb', line 359

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

#phone_ids ⇒ Object 



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

def phone_ids
    get('phone_ids')
end

#phone_ids=(value) ⇒ Object 



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

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

#priority ⇒ Object 



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

def priority
    get('priority')
end

#priority=(value) ⇒ Object 



379
380
381
 
# File 'lib/telerivet/service.rb', line 379

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

#project_id ⇒ Object 



387
388
389
 
# File 'lib/telerivet/service.rb', line 387

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)



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

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



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

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 



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

def response_table_id
    get('response_table_id')
end

#response_table_id=(value) ⇒ Object 



395
396
397
 
# File 'lib/telerivet/service.rb', line 395

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.



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

def save()
    super
end

#service_type ⇒ Object 



363
364
365
 
# File 'lib/telerivet/service.rb', line 363

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
        [project.createService](#Project.createService) for available configuration options.
    * Required

Returns:

object



333
334
335
 
# File 'lib/telerivet/service.rb', line 333

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

Returns:

Telerivet::ContactServiceState



238
239
240
241
 
# File 'lib/telerivet/service.rb', line 238

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 



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

def show_action
    get('show_action')
end

#show_action=(value) ⇒ Object 



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

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

#webhook_url ⇒ Object 



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

def webhook_url
    get('webhook_url')
end