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,
      mcp
  * 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)
  * Array of media attachments for the text message. This property is undefined for
      messages that do not contain media files.
  * 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

- url
  * URL to the message detail page in the Telerivet web app
  * 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


275
276
277
278
 
# File 'lib/telerivet/message.rb', line 275

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 



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

def audio_url
    get('audio_url')
end

#broadcast_id ⇒ Object 



535
536
537
 
# File 'lib/telerivet/message.rb', line 535

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



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

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

#contact_id ⇒ Object 



527
528
529
 
# File 'lib/telerivet/message.rb', line 527

def contact_id
    get('contact_id')
end

#content ⇒ Object 



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

def content
    get('content')
end

#delete ⇒ Object

Deletes this message.



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

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

#direction ⇒ Object 



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

def direction
    get('direction')
end

#duration ⇒ Object 



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

def duration
    get('duration')
end

#error_code ⇒ Object 



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

def error_code
    get('error_code')
end

#error_message ⇒ Object 



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

def error_message
    get('error_message')
end

#error_message=(value) ⇒ Object 



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

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

#external_id ⇒ Object 



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

def external_id
    get('external_id')
end

#from_number ⇒ Object 



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

def from_number
    get('from_number')
end

#get_base_api_path ⇒ Object 



555
556
557
 
# File 'lib/telerivet/message.rb', line 555

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



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

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) 


263
264
265
266
 
# File 'lib/telerivet/message.rb', line 263

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

#id ⇒ Object 



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

def id
    get('id')
end

#label_ids ⇒ Object 



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

def label_ids
    get('label_ids')
end

#media ⇒ Object 



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

def media
    get('media')
end

#message_type ⇒ Object 



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

def message_type
    get('message_type')
end

#mms_parts ⇒ Object 



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

def mms_parts
    get('mms_parts')
end

#network_code ⇒ Object 



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

def network_code
    get('network_code')
end

#num_parts ⇒ Object 



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

def num_parts
    get('num_parts')
end

#phone_id ⇒ Object 



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

def phone_id
    get('phone_id')
end

#price ⇒ Object 



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

def price
    get('price')
end

#price_currency ⇒ Object 



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

def price_currency
    get('price_currency')
end

#priority ⇒ Object 



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

def priority
    get('priority')
end

#project_id ⇒ Object 



547
548
549
 
# File 'lib/telerivet/message.rb', line 547

def project_id
    get('project_id')
end

#remove_label(label) ⇒ Object

Removes a label from the given message.

Arguments:

- label (Telerivet::Label)
  * Required


287
288
289
290
291
292
 
# File 'lib/telerivet/message.rb', line 287

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



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

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

#ring_time ⇒ Object 



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

def ring_time
    get('ring_time')
end

#route_id ⇒ Object 



531
532
533
 
# File 'lib/telerivet/message.rb', line 531

def route_id
    get('route_id')
end

#route_params ⇒ Object 



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

def route_params
    get('route_params')
end

#save ⇒ Object

Saves any fields that have changed for this message.



315
316
317
 
# File 'lib/telerivet/message.rb', line 315

def save()
    super
end

#scheduled_id ⇒ Object 



539
540
541
 
# File 'lib/telerivet/message.rb', line 539

def scheduled_id
    get('scheduled_id')
end

#send_attempts ⇒ Object 



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

def send_attempts
    get('send_attempts')
end

#send_read_receipt ⇒ Object

Sends a read receipt for this message. Currently only supported for incoming WhatsApp messages.



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

def send_read_receipt()
    @api.do_request("POST", get_base_api_path() + "/send_read_receipt")
end

#send_typing_indicator ⇒ Object

Sends a typing indicator for this message. Currently only supported for incoming WhatsApp messages.



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

def send_typing_indicator()
    @api.do_request("POST", get_base_api_path() + "/send_typing_indicator")
end

#service_id ⇒ Object 



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

def service_id
    get('service_id')
end

#set_data(data) ⇒ Object 



560
561
562
563
564
565
566
567
568
 
# File 'lib/telerivet/message.rb', line 560

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 



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

def short_urls
    get('short_urls')
end

#simulated ⇒ Object 



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

def simulated
    get('simulated')
end

#source ⇒ Object 



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

def source
    get('source')
end

#starred ⇒ Object 



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

def starred
    get('starred')
end

#starred=(value) ⇒ Object 



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

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

#status ⇒ Object 



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

def status
    get('status')
end

#time_clicked ⇒ Object 



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

def time_clicked
    get('time_clicked')
end

#time_created ⇒ Object 



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

def time_created
    get('time_created')
end

#time_sent ⇒ Object 



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

def time_sent
    get('time_sent')
end

#time_updated ⇒ Object 



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

def time_updated
    get('time_updated')
end

#to_number ⇒ Object 



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

def to_number
    get('to_number')
end

#track_clicks ⇒ Object 



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

def track_clicks
    get('track_clicks')
end

#tts_lang ⇒ Object 



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

def tts_lang
    get('tts_lang')
end

#tts_voice ⇒ Object 



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

def tts_voice
    get('tts_voice')
end

#url ⇒ Object 



551
552
553
 
# File 'lib/telerivet/message.rb', line 551

def url
    get('url')
end

#user_id ⇒ Object 



543
544
545
 
# File 'lib/telerivet/message.rb', line 543

def user_id
    get('user_id')
end