Class: Telerivet::Message

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

Overview

Represents a single message.

Fields:

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

- direction
    * Direction of the message: incoming messages are sent from one of your contacts to
        your phone; outgoing messages are sent from your phone to one of your contacts
    * Allowed values: incoming, outgoing
    * Read-only

- status
    * Current status of the message
    * Allowed values: ignored, processing, received, sent, queued, failed, failed_queued,
        cancelled, delivered, not_delivered, read
    * Read-only

- message_type
    * Type of the message
    * Allowed values: sms, mms, ussd, ussd_session, call, chat, service
    * Read-only

- source
    * How the message originated within Telerivet
    * Allowed values: phone, provider, web, api, service, webhook, scheduled, integration
    * Read-only

- time_created (UNIX timestamp)
    * The time that the message was created on Telerivet's servers
    * Read-only

- time_sent (UNIX timestamp)
    * The time that the message was reported to have been sent (null for incoming messages
        and messages that have not yet been sent)
    * Read-only

- time_updated (UNIX timestamp)
    * The time that the message was last updated in Telerivet.
    * Read-only

- from_number (string)
    * The phone number that the message originated from (your number for outgoing
        messages, the contact's number for incoming messages)
    * Read-only

- to_number (string)
    * The phone number that the message was sent to (your number for incoming messages,
        the contact's number for outgoing messages)
    * Read-only

- content (string)
    * The text content of the message (null for USSD messages and calls)
    * Read-only

- starred (bool)
    * Whether this message is starred in Telerivet
    * Updatable via API

- simulated (bool)
    * Whether this message was simulated within Telerivet for testing (and not actually
        sent to or received by a real phone)
    * Read-only

- label_ids (array)
    * List of IDs of labels applied to this message
    * Read-only

- route_params (Hash)
    * Route-specific parameters for the message. The parameters object may have keys
        matching the `phone_type` field of a phone (basic route) that may be used to send the
        message. The corresponding value is an object with route-specific parameters to use
        when the message is sent by that type of route.
    * Read-only

- vars (Hash)
    * Custom variables stored for this message
    * Updatable via API

- priority (int)
    * Priority of this message. Telerivet will attempt to send messages with higher
        priority numbers first. Only defined for outgoing messages.
    * Read-only

- error_message
    * A description of the error encountered while sending a message. (This field is
        omitted from the API response if there is no error message.)
    * Updatable via API

- external_id
    * The ID of this message from an external SMS gateway provider (e.g. Twilio or
        Vonage), if available.
    * Read-only

- num_parts (number)
    * The number of SMS parts associated with the message, if applicable and if known.
    * Read-only

- price (number)
    * The price of this message, if known.
    * Read-only

- price_currency
    * The currency of the message price, if applicable.
    * Read-only

- duration (number)
    * The duration of the call in seconds, if known, or -1 if the call was not answered.
    * Read-only

- ring_time (number)
    * The length of time the call rang in seconds before being answered or hung up, if
        known.
    * Read-only

- audio_url
    * For voice calls, the URL of an MP3 file to play when the contact answers the call
    * Read-only

- tts_lang
    * For voice calls, the language of the text-to-speech voice
    * Allowed values: en-US, en-GB, en-GB-WLS, en-AU, en-IN, da-DK, nl-NL, fr-FR, fr-CA,
        de-DE, is-IS, it-IT, pl-PL, pt-BR, pt-PT, ru-RU, es-ES, es-US, sv-SE
    * Read-only

- tts_voice
    * For voice calls, the text-to-speech voice
    * Allowed values: female, male
    * Read-only

- track_clicks (boolean)
    * If true, URLs in the message content are short URLs that redirect to a destination
        URL.
    * Read-only

- short_urls (array)
    * For text messages containing short URLs, this is an array of objects with the
        properties `short_url`, `link_type`, `time_clicked` (the first time that URL was
        clicked), and `expiration_time`. If `link_type` is "redirect", the object also
        contains a `destination_url` property. If `link_type` is "media", the object also
        contains an `media_index` property (the index in the media array). If `link_type` is
        "service", the object also contains a `service_id` property. This property is
        undefined for messages that do not contain short URLs.
    * Read-only

- network_code (string)
    * A string identifying the network that sent or received the message, if known. For
        mobile networks, this string contains the 3-digit mobile country code (MCC) followed
        by the 2- or 3-digit mobile network code (MNC), which results in a 5- or 6-digit
        number. For lists of mobile network operators and their corresponding MCC/MNC values,
        see [Mobile country code Wikipedia
        article](https://en.wikipedia.org/wiki/Mobile_country_code). The network_code property
        may be non-numeric for messages not sent via mobile networks.
    * Read-only

- media (array)
    * For text messages containing media files, this is an array of objects with the
        properties `url`, `type` (MIME type), `filename`, and `size` (file size in bytes).
        Unknown properties are null. This property is undefined for messages that do not
        contain media files. Note: For files uploaded via the Telerivet web app, the URL is
        temporary and may not be valid for more than 1 day.
    * Read-only

- mms_parts (array)
    * A list of parts in the MMS message (only for incoming MMS messages received via
        Telerivet Gateway Android app).

        Each MMS part in the list is an object with the following
        properties:

        - cid: MMS content-id
        - type: MIME type
        - filename: original filename
        - size (int): number of bytes
        - url: URL where the content for this part is stored (secret but
        publicly accessible, so you could link/embed it in a web page without having to
        re-host it yourself)

        In general, the `media` property of the message is recommended for
        retrieving information about MMS media files, instead of `mms_parts`.
        The `mms_parts` property is also only present when retrieving an
        individual MMS message by ID, not when querying a list of messages.
    * Read-only

- time_clicked (UNIX timestamp)
    * If the message contains any short URLs, this is the first time that a short URL in
        the message was clicked.  This property is undefined for messages that do not contain
        short URLs.
    * Read-only

- service_id (string, max 34 characters)
    * ID of the service that handled the message (for voice calls, the service defines the
        call flow)
    * Read-only

- phone_id (string, max 34 characters)
    * ID of the phone (basic route) that sent or received the message
    * Read-only

- contact_id (string, max 34 characters)
    * ID of the contact that sent or received the message
    * Read-only

- route_id (string, max 34 characters)
    * ID of the custom route that sent the message (if applicable)
    * Read-only

- broadcast_id (string, max 34 characters)
    * ID of the broadcast that this message is part of (if applicable)
    * Read-only

- scheduled_id (string, max 34 characters)
    * ID of the scheduled message that created this message is part of (if applicable)
    * Read-only

- user_id (string, max 34 characters)
    * ID of the Telerivet user who sent the message (if applicable)
    * Read-only

- project_id
    * ID of the project this contact belongs to
    * 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_label(label) ⇒ Object

Adds a label to the given message.

Arguments:

- label (Telerivet::Label)
    * Required



253
254
255
256
 
# File 'lib/telerivet/message.rb', line 253

def add_label(label)
    @api.do_request("PUT", label.get_base_api_path() + "/messages/" + get('id'));
    @label_ids_set[label.id] = true
end

#audio_url ⇒ Object 



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

def audio_url
    get('audio_url')
end

#broadcast_id ⇒ Object 



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

def broadcast_id
    get('broadcast_id')
end

#cancel ⇒ Object

Cancels sending a message that has not yet been sent. Returns the updated message object. Only valid for outgoing messages that are currently in the queued, retrying, or cancelled states. For other messages, the API will return an error with the code ‘not_cancellable’.

Returns:

Telerivet::Message



325
326
327
328
 
# File 'lib/telerivet/message.rb', line 325

def cancel()
    require_relative 'message'
    Message.new(@api, @api.do_request("POST", get_base_api_path() + "/cancel"))
end

#contact_id ⇒ Object 



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

def contact_id
    get('contact_id')
end

#content ⇒ Object 



377
378
379
 
# File 'lib/telerivet/message.rb', line 377

def content
    get('content')
end

#delete ⇒ Object

Deletes this message.



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

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

#direction ⇒ Object 



341
342
343
 
# File 'lib/telerivet/message.rb', line 341

def direction
    get('direction')
end

#duration ⇒ Object 



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

def duration
    get('duration')
end

#error_message ⇒ Object 



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

def error_message
    get('error_message')
end

#error_message=(value) ⇒ Object 



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

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

#external_id ⇒ Object 



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

def external_id
    get('external_id')
end

#from_number ⇒ Object 



369
370
371
 
# File 'lib/telerivet/message.rb', line 369

def from_number
    get('from_number')
end

#get_base_api_path ⇒ Object 



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

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

#get_mmsparts ⇒ Object

(Deprecated) Retrieves a list of MMS parts for this message (only for incoming MMS messages received via Telerivet Gateway Android app). Note: This only works for MMS messages received via the Telerivet Gateway Android app. In general, the ‘media` property of the message is recommended for retrieving information about MMS media files.

The return value has the same format as the ‘mms_parts` property of the Message object.

Returns:

array



286
287
288
 
# File 'lib/telerivet/message.rb', line 286

def get_mmsparts()
    return @api.do_request("GET", get_base_api_path() + "/mms_parts")
end

#has_label?(label) ⇒ Boolean

Returns true if this message has a particular label, false otherwise.

Arguments:

- label (Telerivet::Label)
    * Required

Returns:

bool

Returns:

  • (Boolean) 


241
242
243
244
 
# File 'lib/telerivet/message.rb', line 241

def has_label?(label)
    load()
    return @label_ids_set.has_key?(label.id)
end

#id ⇒ Object 



337
338
339
 
# File 'lib/telerivet/message.rb', line 337

def id
    get('id')
end

#label_ids ⇒ Object 



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

def label_ids
    get('label_ids')
end

#media ⇒ Object 



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

def media
    get('media')
end

#message_type ⇒ Object 



349
350
351
 
# File 'lib/telerivet/message.rb', line 349

def message_type
    get('message_type')
end

#mms_parts ⇒ Object 



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

def mms_parts
    get('mms_parts')
end

#network_code ⇒ Object 



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

def network_code
    get('network_code')
end

#num_parts ⇒ Object 



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

def num_parts
    get('num_parts')
end

#phone_id ⇒ Object 



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

def phone_id
    get('phone_id')
end

#price ⇒ Object 



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

def price
    get('price')
end

#price_currency ⇒ Object 



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

def price_currency
    get('price_currency')
end

#priority ⇒ Object 



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

def priority
    get('priority')
end

#project_id ⇒ Object 



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

def project_id
    get('project_id')
end

#remove_label(label) ⇒ Object

Removes a label from the given message.

Arguments:

- label (Telerivet::Label)
    * Required



265
266
267
268
269
270
 
# File 'lib/telerivet/message.rb', line 265

def remove_label(label)
    @api.do_request("DELETE", label.get_base_api_path() + "/messages/" + get('id'))
    if @label_ids_set.has_key?(label.id)
        @label_ids_set.delete(label.id)
    end
end

#resend(options = nil) ⇒ Object

Resends a message, for example if the message failed to send or if it was not delivered. If the message was originally in the queued, retrying, failed, or cancelled states, then Telerivet will return the same message object. Otherwise, Telerivet will create and return a new message object.

Arguments:

- options (Hash)

  - route_id
      * ID of the phone or route to send the message from

Returns:

Telerivet::Message



312
313
314
315
 
# File 'lib/telerivet/message.rb', line 312

def resend(options = nil)
    require_relative 'message'
    Message.new(@api, @api.do_request("POST", get_base_api_path() + "/resend", options))
end

#ring_time ⇒ Object 



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

def ring_time
    get('ring_time')
end

#route_id ⇒ Object 



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

def route_id
    get('route_id')
end

#route_params ⇒ Object 



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

def route_params
    get('route_params')
end

#save ⇒ Object

Saves any fields that have changed for this message.



293
294
295
 
# File 'lib/telerivet/message.rb', line 293

def save()
    super
end

#scheduled_id ⇒ Object 



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

def scheduled_id
    get('scheduled_id')
end

#service_id ⇒ Object 



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

def service_id
    get('service_id')
end

#set_data(data) ⇒ Object 



510
511
512
513
514
515
516
517
518
 
# File 'lib/telerivet/message.rb', line 510

def set_data(data)
    super
    
    @label_ids_set = {}
    
    if data.has_key?('label_ids')
        data['label_ids'].each { |id| @label_ids_set[id] = true }
    end
end

#short_urls ⇒ Object 



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

def short_urls
    get('short_urls')
end

#simulated ⇒ Object 



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

def simulated
    get('simulated')
end

#source ⇒ Object 



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

def source
    get('source')
end

#starred ⇒ Object 



381
382
383
 
# File 'lib/telerivet/message.rb', line 381

def starred
    get('starred')
end

#starred=(value) ⇒ Object 



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

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

#status ⇒ Object 



345
346
347
 
# File 'lib/telerivet/message.rb', line 345

def status
    get('status')
end

#time_clicked ⇒ Object 



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

def time_clicked
    get('time_clicked')
end

#time_created ⇒ Object 



357
358
359
 
# File 'lib/telerivet/message.rb', line 357

def time_created
    get('time_created')
end

#time_sent ⇒ Object 



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

def time_sent
    get('time_sent')
end

#time_updated ⇒ Object 



365
366
367
 
# File 'lib/telerivet/message.rb', line 365

def time_updated
    get('time_updated')
end

#to_number ⇒ Object 



373
374
375
 
# File 'lib/telerivet/message.rb', line 373

def to_number
    get('to_number')
end

#track_clicks ⇒ Object 



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

def track_clicks
    get('track_clicks')
end

#tts_lang ⇒ Object 



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

def tts_lang
    get('tts_lang')
end

#tts_voice ⇒ Object 



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

def tts_voice
    get('tts_voice')
end

#user_id ⇒ Object 



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

def user_id
    get('user_id')
end