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 messages.
Inbound messages occur when a message is sent to a number associated with a FreeClimb application. Outbound 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
Sms commandYour 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.
FreeClimb Messaging API
The FreeClimb Messaging 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 messages
Inbound 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 messageDelivery.
Message Lifecycle
The message lifecycle features several status values indicating where in the lifecycle a message is.
Outbound Status Lifecycle
| Status | Description |
|---|---|
| New | Applies only to outbound messages. Messages will be marked as new while FreeClimb is processing the send request. |
| Queued | Status of messages that are ready to be sent (but have not yet been sent). |
| Rejected | Requests that are invalid (e.g., the From number isn’t associated with an application registered to your account). |
| 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 | 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. |
| Failed | An 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. |
| Expired | Indicates 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. |
| Deleted | The carrier deleted the inbound message for an unknown reason. |
| Unknown | No official response was received from the carrier. In this scenario the message has most likely expired. |
Inbound Status Lifecycle
| Status | Description |
|---|---|
| Received | Applies to inbound messages only. Indicates that a message has been received by FreeClimb. |
| Undelivered | An inbound message has been captured by FreeClimb but the platform was unable to deliver a request to the Account's smsUrl webhook. |
Updated 5 months ago
