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

- send_attempts (number)
    * The number of times Telerivet has attempted to send the message. Will be greater
        than 1 if the message has been resent. 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



273
274
275
276
 
# File 'lib/telerivet/message.rb', line 273

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 



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

def audio_url
    get('audio_url')
end

#broadcast_id ⇒ Object 



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

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



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

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

#contact_id ⇒ Object 



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

def contact_id
    get('contact_id')
end

#content ⇒ Object 



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

def content
    get('content')
end

#delete ⇒ Object

Deletes this message.



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

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

#direction ⇒ Object 



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

def direction
    get('direction')
end

#duration ⇒ Object 



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

def duration
    get('duration')
end

#error_code ⇒ Object 



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

def error_code
    get('error_code')
end

#error_message ⇒ Object 



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

def error_message
    get('error_message')
end

#error_message=(value) ⇒ Object 



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

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

#external_id ⇒ Object 



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

def external_id
    get('external_id')
end

#from_number ⇒ Object 



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

def from_number
    get('from_number')
end

#get_base_api_path ⇒ Object 



533
534
535
 
# File 'lib/telerivet/message.rb', line 533

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



306
307
308
 
# File 'lib/telerivet/message.rb', line 306

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) 


261
262
263
264
 
# File 'lib/telerivet/message.rb', line 261

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

#id ⇒ Object 



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

def id
    get('id')
end

#label_ids ⇒ Object 



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

def label_ids
    get('label_ids')
end

#media ⇒ Object 



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

def media
    get('media')
end

#message_type ⇒ Object 



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

def message_type
    get('message_type')
end

#mms_parts ⇒ Object 



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

def mms_parts
    get('mms_parts')
end

#network_code ⇒ Object 



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

def network_code
    get('network_code')
end

#num_parts ⇒ Object 



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

def num_parts
    get('num_parts')
end

#phone_id ⇒ Object 



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

def phone_id
    get('phone_id')
end

#price ⇒ Object 



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

def price
    get('price')
end

#price_currency ⇒ Object 



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

def price_currency
    get('price_currency')
end

#priority ⇒ Object 



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

def priority
    get('priority')
end

#project_id ⇒ Object 



529
530
531
 
# File 'lib/telerivet/message.rb', line 529

def project_id
    get('project_id')
end

#remove_label(label) ⇒ Object

Removes a label from the given message.

Arguments:

- label (Telerivet::Label)
    * Required



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

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



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

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

#ring_time ⇒ Object 



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

def ring_time
    get('ring_time')
end

#route_id ⇒ Object 



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

def route_id
    get('route_id')
end

#route_params ⇒ Object 



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

def route_params
    get('route_params')
end

#save ⇒ Object

Saves any fields that have changed for this message.



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

def save()
    super
end

#scheduled_id ⇒ Object 



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

def scheduled_id
    get('scheduled_id')
end

#send_attempts ⇒ Object 



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

def send_attempts
    get('send_attempts')
end

#service_id ⇒ Object 



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

def service_id
    get('service_id')
end

#set_data(data) ⇒ Object 



538
539
540
541
542
543
544
545
546
 
# File 'lib/telerivet/message.rb', line 538

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 



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

def short_urls
    get('short_urls')
end

#simulated ⇒ Object 



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

def simulated
    get('simulated')
end

#source ⇒ Object 



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

def source
    get('source')
end

#starred ⇒ Object 



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

def starred
    get('starred')
end

#starred=(value) ⇒ Object 



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

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

#status ⇒ Object 



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

def status
    get('status')
end

#time_clicked ⇒ Object 



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

def time_clicked
    get('time_clicked')
end

#time_created ⇒ Object 



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

def time_created
    get('time_created')
end

#time_sent ⇒ Object 



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

def time_sent
    get('time_sent')
end

#time_updated ⇒ Object 



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

def time_updated
    get('time_updated')
end

#to_number ⇒ Object 



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

def to_number
    get('to_number')
end

#track_clicks ⇒ Object 



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

def track_clicks
    get('track_clicks')
end

#tts_lang ⇒ Object 



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

def tts_lang
    get('tts_lang')
end

#tts_voice ⇒ Object 



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

def tts_voice
    get('tts_voice')
end

#user_id ⇒ Object 



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

def user_id
    get('user_id')
end