Messaging

📗
MMS capabilities are only available for registered A2P traffic. For information on the registration process, please see Non-Consumer (A2P) SMS Messaging on FreeClimb or contact FreeClimb Sales.

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).
dateCreatedISO	string date-time	Date that this resource was created (UTC) in RFC3339 format (e.g., 2024-10-09T15:05:03.358Z).
dateUpdatedISO	string date-time	Date that this resource was last updated (UTC) in RFC3339 format (e.g., 2024-10-09T15:05:03.358Z).
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
segmentCount	int (nullable)	The number of segments our carrier partners have split up the `text` of the message when sending it. This field will be `null` if we did not receive any information from our carrier partners.
applicationId	string (nullable)	The applicationId of the `from` number used to send the Message.
phoneNumberId	string	The phoneNumberId of the `from` number used to send the Message.
tfn	object	Information about the Toll-Free Registration. Only applies to TFNs
brandId	string (nullable)	The Id of the Brand used to send the 10DLC Messages. Will be `null` otherwise
campaignId	string (nullable)	The Id of the Campaign used to send the 10DLC Messages. Will be `null` otherwise
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, MMS content sent via a shortcode should not exceed 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.

📗MMS capabilities are only available for registered A2P traffic. For information on the registration process, please see Non-Consumer (A2P) SMS Messaging on FreeClimb or contact FreeClimb Sales.

Resource properties

Supported File Types

MMS File Size

MMS Content type

Message lifecycle

Outbound status lifecycle

Inbound status lifecycle

📗
MMS capabilities are only available for registered A2P traffic. For information on the registration process, please see Non-Consumer (A2P) SMS Messaging on FreeClimb or contact FreeClimb Sales.