Messaging

A Message instance resource represents an SMS or MMS Message sent between FreeClimb and a remote endpoint.

The Message may be inbound (when a person messages a FreeClimb number ) or outbound (when an Application initiates sending the Message, either via the REST API or the PerCL Sms command). The Messages list resource represents the set of all Messages made to and from an Account.

Resource properties

Property	Type	Description
accountId	string	ID of the Account that sent or received this Message.
dateCreated	string date-time	Date that this resource was created (GMT) in RFC 1123 format (e.g., Mon, 15 Jun 2009 20:45:30 GMT).
dateUpdated	string date-time	Date that this resource was last updated (GMT) in RFC 1123 format (e.g., Mon, 15 Jun 2009 20:45:30 GMT).
direction	string	Direction of the message: inbound for incoming messages, outbound for Messages initiated via the REST API or by the `Sms` PerCL command during a Call.
from	string	inbound: Phone number that sent this Message. outbound: FreeClimb phone number that is sending the message. Must be associated with the `accountId`. Note: number must be in e.164 format (e.g. +13125551212).
messageId	string	String that uniquely identifies this Message resource.
notificationUrl	string	URL to which FreeClimb will make a POST request when the status of an outbound message changes.
revision	integer	Revision count for the resource. Set to `1` on creation and is incremented at every update.
status	string	The status of the message. See Message Lifecycle below for valid status values.
text	string	Text body of this message.
to	string	inbound: FreeClimb phone number that received this Message. outbound: Recipient of the Message Note: number must be in e.164 format (e.g. +13125551212)
mediaUrls	array of string	The array of mediaUrls that were sent with the MMS message
uri	string	The URI for this resource, relative to the API base URL.

Supported File Types

MMS File Size

Each file size must take into consideration a base64 encoding overhead that is added to the content to translate into MM7 format in compliance with 3GPP TS 23.140 specifications. Base64 encoding can add as much as 30-40% of the size

To ensure a uniform experience across all US operators and accommodation of the variances in handset types, FreeClimb recommends that all MMS content sent via a shortcode should not be more than 500KB.

MMS Content type

FreeClimb MMS supports various content types which includes text messages upto 1000 character or bytes, images, video and audio files. FreeClimb supports sending image/video/audio file + text in one single message. Please note that there are variations in performance between handsets and between the various MMS clients.

Supported MIME types:

image/jpeg

image/png

image/gif : 87A, 89A

image/bmp

Audio Types:

audio/QCELP

audio/wav

audio/x-wav

audio/midi

audio/SP-midi

audio/mid

audio/amr

audio/mp3

audio/mp4

audio/aac or aac+

Video types:

video/mpeg-4/mp4

video/h.263/h264

video/motion jpeg

video/asf

video/3gpp

video/3gpp2

video/mp4v-es

video/mp4-es

Others:

text/vcard

application/gzip

application/rtf

Note that if a video is part of a message, the following guidelines needs to be met:

Video file format: 3gpp or 3gpp2

Video file extension: 3gp,3gpp,3g2,3gpp2

Video Mime Type: video/3gpp, video/3gp, video/3g2, video/3gpp2

Max number of frames: 225d

Max Frame rate : 15fps

Min Frame rate: >0.5fps

Max Video Duration/FPS: upt [email protected], upto 15s@15fps

Max video Bit rate: upto256K

Video encoding: Mpeg-4 VSP L0,L1,L2 h.263 profile 3 Level 10, H.263 Profile 0 Level 10

Audio encoding: AMR-NB, AMR-WB, AAC LC, QCELP -13K 9for 3g2 files)

Audio Bit rate :QCELP =14400, AMR-NM = 6400, AMR-WB = 7200, AAC LC= 29500

Please note that certain MIME types may not work on some Operators or device types.

Message lifecycle

Messages can exist in one of the following states:

Outbound status lifecycle

Status	Description
new	The status is `new` for as long as FreeClimb is processing a request to send an outbound Message. If the Message is valid, the status is changed to `queued`, otherwise it is changed to `rejected`. Examples of invalid Messages: `from` doesn't belong to the requesting Account. `to` not in service area, `text` too long, or includes invalid characters.
queued	The status is changed to `queued` until the platform is ready to transmit it. The Message status is changed to `sending`.
rejected	The status is changed to `rejected` if there was something about the request that made it invalid when sending it to the upstream carriers. Freeclimb might also set the status of 'rejected' due to rate limiting.
sending	The status is changed to `sending` while FreeClimb is actively processing the outbound message. Once FreeClimb processing is complete, the status changes to `sent`. If there is a communication issue with the message recipient, the status will change to `failed`.
sent	The status is changed to `sent` once the outbound Message has successfully left FreeClimb. If there is a communication issue with the message recipient, the status will change to `failed`. Otherwise, no further status changes will occur.
failed	The status is `failed` if an outbound Message could not be delivered due to communication issues with the message recipient. This status could indicate a temporary or permanent inability to deliver to a specified recipient, and the sending application may wish to try again.
expired	The status is changed to `expired` when the message failed to send within a certain period of time (usually within 24-48 hours). This status could indicate that the recipient's phone has been turned off or without battery for a period of time.
deleted	The status is changed to `deleted` when the carrier deleted the message.
unknown	The status is changed to `unknown` when no official response was received from the carrier. In this scenario the message has most likely expired.

Inbound status lifecycle

Status	Description
received	Inbound Message status is `received` once the Message has been captured by FreeClimb. FreeClimb will send a request to the Account's `smsUrl` webhook if configured.
undelivered	Inbound Message status is `undelivered` once the Message has been captured by FreeClimb but the platform was unable to deliver a request to the Account's `smsUrl` webhook.