class Telerivet::Service

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

- 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

- label_id
    * ID of the label containing messages sent or received by this service (currently only
        used for polls)
    * Read-only

- response_table_id
    * ID of the data table where responses to this service will be stored (currently only
        used for polls)
    * Read-only

- sample_group_id
    * ID of the group containing contacts that have been invited to interact with this
        service (currently only used for polls)
    * Read-only

- respondent_group_id
    * ID of the group containing contacts that have completed an interaction with this
        service (currently only used for polls)
    * Read-only

- questions (array)
    * Array of objects describing each question in a poll (only used for polls). Each
        object has the properties `"id"` (the question ID), `"content"` (the text of the
        question), and `"question_type"` (either `"multiple_choice"`, `"missed_call"`, or
        `"open"`).
    * Read-only

Public Instance Methods

active() click to toggle source
# File lib/telerivet/service.rb, line 291
def active
    get('active')
end
active=(value) click to toggle source
# File lib/telerivet/service.rb, line 295
def active=(value)
    set('active', value)
end
contexts() click to toggle source
# File lib/telerivet/service.rb, line 307
def contexts
    get('contexts')
end
get_base_api_path() click to toggle source
# File lib/telerivet/service.rb, line 335
def get_base_api_path()
    "/projects/#{get('project_id')}/services/#{get('id')}"
end
get_contact_state(contact) click to toggle source

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
# File lib/telerivet/service.rb, line 180
def get_contact_state(contact)
    require_relative 'contactservicestate'
    ContactServiceState.new(@api, @api.do_request('GET', get_base_api_path() + '/states/' + contact.id))
end
id() click to toggle source
# File lib/telerivet/service.rb, line 279
def id
    get('id')
end
invoke(options) click to toggle source

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.

  - 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 (Undefined if async=true.)

  - airtime_transactions (array of objects)
      * Array of airtime transactions sent by the service (Undefined if async=true.)
# File lib/telerivet/service.rb, line 147
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
label_id() click to toggle source
# File lib/telerivet/service.rb, line 315
def label_id
    get('label_id')
end
name() click to toggle source
# File lib/telerivet/service.rb, line 283
def name
    get('name')
end
name=(value) click to toggle source
# File lib/telerivet/service.rb, line 287
def name=(value)
    set('name', value)
end
priority() click to toggle source
# File lib/telerivet/service.rb, line 299
def priority
    get('priority')
end
priority=(value) click to toggle source
# File lib/telerivet/service.rb, line 303
def priority=(value)
    set('priority', value)
end
project_id() click to toggle source
# File lib/telerivet/service.rb, line 311
def project_id
    get('project_id')
end
query_contact_states(options = nil) click to toggle source

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)
# File lib/telerivet/service.rb, line 267
def query_contact_states(options = nil)
    require_relative 'contactservicestate'
    @api.cursor(ContactServiceState, get_base_api_path() + "/states", options)
end
questions() click to toggle source
# File lib/telerivet/service.rb, line 331
def questions
    get('questions')
end
reset_contact_state(contact) click to toggle source

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
# File lib/telerivet/service.rb, line 224
def reset_contact_state(contact)
    require_relative 'contactservicestate'
    ContactServiceState.new(@api, @api.do_request('DELETE', get_base_api_path() + '/states/' + contact.id))
end
respondent_group_id() click to toggle source
# File lib/telerivet/service.rb, line 327
def respondent_group_id
    get('respondent_group_id')
end
response_table_id() click to toggle source
# File lib/telerivet/service.rb, line 319
def response_table_id
    get('response_table_id')
end
sample_group_id() click to toggle source
# File lib/telerivet/service.rb, line 323
def sample_group_id
    get('sample_group_id')
end
save() click to toggle source

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

Calls superclass method Telerivet::Entity#save
# File lib/telerivet/service.rb, line 275
def save()
    super
end
set_contact_state(contact, options) click to toggle source

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
# File lib/telerivet/service.rb, line 208
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