Sending and Receiving Messages

Learn the basics of how to send and receive messages using FreeClimb.

FreeClimb is capable of handling both inbound and outbound SMS messages.

Inbound SMS messages occur when a message is sent to a number associated with a FreeClimb application. Outbound SMS messages occur when the FreeClimb application initiates the send process via the RESTful API or the Sms PerCL command and the message is intended for receipt by a remote endpoint.


Use cases

FreeClimb allows you to send messages as part of a call using PerCL, the Performance Command Language, or by themselves using the API.

  • Sending messages during a call: Suppose a user calls into a phone number to request information. During the call, the user can indicate they want a written confirmation of the information they’re hearing. You can then send them a text message of the information they’re receiving (e.g., payment confirmation, movie showing times, etc.)

  • Sending messages, but not as part of a call: You can use FreeClimb to send messages to individuals or to multiple recipients.

📘

Trial accounts can only send outbound messages to verified numbers. Verified numbers can be added through your dashboard.


The PerCL Sms command

Your client application can return a call control script (written using PerCL) that contains instructions to send an SMS message using the Sms command. This command accepts four attributes, each of which will modify the command’s behavior:

  • To: the phone number to which the message will be sent, in the E.164 format
  • From: the phone number that will be shown as the sender. Note that outbound SMS messages must originate from a valid phone number assigned to the originating FreeClimb account
  • Text: the text to contain in the message
  • Notification URL: the URL invoked when the messages’ status changes

At this time, FreeClimb only offers outbound SMS functionality using PerCL in the context of a call.


SMS messages and the FreeClimb API

The FreeClimb SMS API offers three message-related endpoints to handle outbound SMS messages and provide you with the ability to review messages that have been processed by FreeClimb:

  • Get an SMS Message: retrieves a specific SMS message that’s been processed by FreeClimb
  • List SMS Messages: retrieves a list of the SMS messages sent to and originating from the account
  • Send an SMS Message: sends an SMS message based on the parameters provided

Webhooks for SMS messages

Inbound SMS messages to FreeClimb are handled via webhooks. FreeClimb “listens” for inbound messages. Then, it delivers the messages to the application that is associated with the destination number.

FreeClimb also uses webhooks to listen for status changes indicating that an outgoing message has been handed over to a destination messaging provider.

For more information on the webhooks related to messaging, see SMS.


Message Lifecycle

The message lifecycle features several status values indicating where in the lifecycle a message is.

Outbound Status Lifecycle

StatusDescription
NewApplies only to outbound messages. Messages will be marked as new while FreeClimb is processing the send request.
QueuedStatus of messages that are ready to be sent (but have not yet been sent).
RejectedRequests that are invalid (e.g., the From number isn’t associated with an application registered to your account).
SendingThe 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.
SentIndicates the message was successfully sent by FreeClimb. Note, however, that the message is now being processed by another provider, so FreeClimb is unable to provide further updates.
FailedAn outbound message that was unable to be delivered. This status could indicate a temporary or permanent inability to deliver to a specified recipient, and the sending application may wish to try again.
ExpiredIndicates that 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.
DeletedThe carrier deleted the inbound message for an unknown reason.
UnknownNo official response was received from the carrier. In this scenario the message has most likely expired.

Inbound Status Lifecycle

StatusDescription
ReceivedApplies to inbound messages only. Indicates that a message has been received by FreeClimb.
UndeliveredAn inbound message has been captured by FreeClimb but the platform was unable to deliver a request to the Account's smsUrl webhook.