SMS

A Message instance resource represents an SMS 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)
uri	string	The URI for this resource, relative to the API base URL.

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.