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.

        When sending messages via chat apps such as WhatsApp, the route_params
        parameter can be used to send messages with app-specific features such as quick
        replies and link buttons.

        For more details, see [Route-Specific Parameters](#route_params).
    * Read-only

- vars (Hash)
    * Custom variables stored for this message. 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

- 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

- error_code
    * A route-specific error code encountered while sending a message. The error code
        values depend on the provider and may be described in the provider's API
        documentation. Error codes may be strings or numbers, depending on the provider. (This
        field is omitted from the API response if there is no error code.)
    * Read-only

- 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



268
269
270
271
 
# File 'lib/telerivet/message.rb', line 268

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 



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

def audio_url
    get('audio_url')
end

#broadcast_id ⇒ Object 



508
509
510
 
# File 'lib/telerivet/message.rb', line 508

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



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

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

#contact_id ⇒ Object 



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

def contact_id
    get('contact_id')
end

#content ⇒ Object 



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

def content
    get('content')
end

#delete ⇒ Object

Deletes this message.



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

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

#direction ⇒ Object 



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

def direction
    get('direction')
end

#duration ⇒ Object 



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

def duration
    get('duration')
end

#error_code ⇒ Object 



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

def error_code
    get('error_code')
end

#error_message ⇒ Object 



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

def error_message
    get('error_message')
end

#error_message=(value) ⇒ Object 



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

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

#external_id ⇒ Object 



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

def external_id
    get('external_id')
end

#from_number ⇒ Object 



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

def from_number
    get('from_number')
end

#get_base_api_path ⇒ Object 



524
525
526
 
# File 'lib/telerivet/message.rb', line 524

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



301
302
303
 
# File 'lib/telerivet/message.rb', line 301

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) 


256
257
258
259
 
# File 'lib/telerivet/message.rb', line 256

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

#id ⇒ Object 



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

def id
    get('id')
end

#label_ids ⇒ Object 



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

def label_ids
    get('label_ids')
end

#media ⇒ Object 



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

def media
    get('media')
end

#message_type ⇒ Object 



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

def message_type
    get('message_type')
end

#mms_parts ⇒ Object 



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

def mms_parts
    get('mms_parts')
end

#network_code ⇒ Object 



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

def network_code
    get('network_code')
end

#num_parts ⇒ Object 



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

def num_parts
    get('num_parts')
end

#phone_id ⇒ Object 



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

def phone_id
    get('phone_id')
end

#price ⇒ Object 



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

def price
    get('price')
end

#price_currency ⇒ Object 



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

def price_currency
    get('price_currency')
end

#priority ⇒ Object 



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

def priority
    get('priority')
end

#project_id ⇒ Object 



520
521
522
 
# File 'lib/telerivet/message.rb', line 520

def project_id
    get('project_id')
end

#remove_label(label) ⇒ Object

Removes a label from the given message.

Arguments:

- label (Telerivet::Label)
    * Required



280
281
282
283
284
285
 
# File 'lib/telerivet/message.rb', line 280

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



327
328
329
330
 
# File 'lib/telerivet/message.rb', line 327

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

#ring_time ⇒ Object 



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

def ring_time
    get('ring_time')
end

#route_id ⇒ Object 



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

def route_id
    get('route_id')
end

#route_params ⇒ Object 



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

def route_params
    get('route_params')
end

#save ⇒ Object

Saves any fields that have changed for this message.



308
309
310
 
# File 'lib/telerivet/message.rb', line 308

def save()
    super
end

#scheduled_id ⇒ Object 



512
513
514
 
# File 'lib/telerivet/message.rb', line 512

def scheduled_id
    get('scheduled_id')
end

#service_id ⇒ Object 



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

def service_id
    get('service_id')
end

#set_data(data) ⇒ Object 



529
530
531
532
533
534
535
536
537
 
# File 'lib/telerivet/message.rb', line 529

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 



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

def short_urls
    get('short_urls')
end

#simulated ⇒ Object 



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

def simulated
    get('simulated')
end

#source ⇒ Object 



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

def source
    get('source')
end

#starred ⇒ Object 



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

def starred
    get('starred')
end

#starred=(value) ⇒ Object 



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

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

#status ⇒ Object 



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

def status
    get('status')
end

#time_clicked ⇒ Object 



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

def time_clicked
    get('time_clicked')
end

#time_created ⇒ Object 



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

def time_created
    get('time_created')
end

#time_sent ⇒ Object 



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

def time_sent
    get('time_sent')
end

#time_updated ⇒ Object 



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

def time_updated
    get('time_updated')
end

#to_number ⇒ Object 



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

def to_number
    get('to_number')
end

#track_clicks ⇒ Object 



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

def track_clicks
    get('track_clicks')
end

#tts_lang ⇒ Object 



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

def tts_lang
    get('tts_lang')
end

#tts_voice ⇒ Object 



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

def tts_voice
    get('tts_voice')
end

#user_id ⇒ Object 



516
517
518
 
# File 'lib/telerivet/message.rb', line 516

def user_id
    get('user_id')
end