You can send an SMS from an MDriven application by calling an SMS provider's REST endpoint with RestPost, then using the returned status and message to update your modeled delivery state.
Before you begin
You need an account with an SMS provider that exposes a REST API. The provider supplies the endpoint URL, required authentication, request parameters, and response format. For example, the service previously known as Nexmo is now Vonage.
This page describes the MDriven-side pattern. Keep the provider-specific request definition in line with the provider's current API documentation.
Model the SMS send operation
Create an action that sends the message from the part of your application that owns the SMS. For example, an appointment reminder application can have an SMS object with values such as a recipient phone number, message text, and delivery state.
Use a state value to make the outcome visible to users and to prevent an unknown result from being treated as a successful send.
| Example state | Meaning |
|---|---|
| Pending | The application has not sent the request yet. |
| Sent | The SMS provider request completed with the expected successful result. |
| Failed | The request did not produce the expected successful result. Store enough information for an administrator or user to investigate. |
Send the REST request
- In MDriven Designer, select the class or ViewModel that performs the send operation.
- Create the action that will send the SMS. Run it only when the recipient number and message text have been validated by your application.
- Format the request according to your provider's REST API. This includes the provider endpoint and the values required for the recipient and message.
- Use
RestPostto post the formatted request to the provider. - Read the returned status and message, and update the SMS object's state based on that result.
For example, when a user chooses Send reminder, the action posts the recipient number and reminder text to the provider. If the response indicates success, set the reminder SMS to Sent. If it indicates an error, set it to Failed and retain the returned message so that the failed request can be diagnosed.
Check the response before changing state
Do not mark an SMS as sent merely because the action was started. The REST call can fail because the request is malformed, authentication is rejected, the provider is unavailable, or the provider rejects the recipient or message.
When an action uses RestPost, declare these string variables where you need to inspect the REST result:
| Variable | Use |
|---|---|
vReturnStatusCode:String
|
Receives the status from a REST query such as RestPost.
|
vReturnMessage:String
|
Receives the reason code or message from the REST call. |
Use these values in the action's decision logic. A concrete flow is:
- Set the SMS state to Pending before sending, if it is not already pending.
- Call
RestPostwith the provider-specific request. - Inspect
vReturnStatusCodeandvReturnMessage. - If the response is the expected success result, change the state to Sent.
- Otherwise, change the state to Failed and save or display the returned message according to your application's error-handling design.
The provider's response body may contain additional delivery information. Model and process that information only after you have confirmed its structure in the provider documentation.
Test the request separately
Test the request parameters outside the application before finalizing the action. This helps distinguish a provider request problem from application logic. When you are forming or troubleshooting a REST request, you can use postman-echo.com to understand what is being sent.
After the external request works, test the MDriven action with a known test recipient and verify each outcome:
- A successful provider response changes the modeled state to Sent.
- A rejected or unsuccessful response changes the modeled state to Failed.
- The returned status and message are available for diagnosis.
Keep provider details maintainable
SMS providers differ in their required request format and can change their APIs. Isolate provider-specific endpoint, authentication, and request-format decisions from the business decision that an SMS should be sent. Your modeled state flow should remain the same even if you later change provider.
For REST response variables and additional REST request and response behavior, see HowTos:Expose REST Service.