Sending and Receiving Messages

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.


Outbound Messages for Trial Accounts

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 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 the following seven states/status values indicating where in the lifecycle a message is:




Applies only to outbound messages. Messages will be marked as new while FreeClimb is processing the send request.


Status of messages that are ready to be sent (but have not yet been sent).


Requests that are invalid (e.g., the From number isn’t associated with an application registered to your account).


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.


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


An outbound message that was unable to be delivered.


Applies to inbound messages only. Indicates that a message has been received by FreeClimb.

Updated 2 months ago

Sending and Receiving Messages

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.