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 |
| 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. |
