SMS Messages

Sending SMS Messages

With Mez:sms

The Mez:sms function takes three arguments.

1. The object instance representing the recipient of the message. This can, however, be any object containing a mobile number field and does not need to be a role.
2. The attribute on this object representing the mobile number of the recipient.
3. The key of a lang file entry that contains the message content. In this case the lang file entry simply references a function scoped variable.

uuid smsId = Mez:sms(farmer, "mobileNumber", "messaging.message_content");

In the above example the uuid being returned is a reference to Helium's internal id representing the SMS (see also the smsid field in the section below). It can be assigned as shown or it can be ignored by simply calling the function without assigning the result.

With {RoleObj}.notify

See User Roles#SendingNotifications  and the notify function under Collections#CollectionBuilt-inFunctions.

Inspecting Sent Message Results

The __sms_result__ Built-in Object

Represents SMS results that are duplicated in the app schema for easy access to app developers. Records belonging to this object can be queried using the standard selectors.

@NotTracked
persistent object __sms_result__ {
    datetime datetimestampStarted;
    datetime datetimestampFinished;
    string destination;    
    int attempt;
    bool success;
    string error;
    bool doneProcessing;
    uuid smsOutboundConfigurationVersionId;
    string smsOutboundConfigurationName;
    uuid smsId;
}

@OnSmsResultUpdate
void smsResultUpdateCallback(__sms_result__ smsResult) {
    if(smsResult.success == false) {
        FailedSms failedSms = FailedSms:new();
        failedSms.failureRecordedOn = Mez:now();
        failedSms.smsResultId = smsResult._id;
        failedSms.save();
    }
}

Receiving SMS Messages

The @ReceiveSms function annotation indicates that a function can receive an SMS.

@ReceiveSms("Test description")
void receiveSmsNumberText(string number, string text) { ... }

@ReceiveSms("Test description")
void receiveSmsNumberTextJson(string number, string text, json aggregatorFields) { ... }

Note that in the second example above, the aggregator fields represents additional fields or properties that are sent to Helium Rapid by the SMS aggregator or by Helium Flex.

At the time of writing the functionality to populate that parameter has only been implemented for the "Africa's Talking" inbound SMS driver.

Additional Mentions and References

• Quick Reference#MezBIFs
• Quick Reference#FunctionAnnotations
• Quick Reference#Built-inObjects
• Lesson 10: Scheduled Functions, Flow Control, Basic Messaging#SendinganSMS
• Lesson 18: SMS and Scheduled Function Result Callbacks#AnnotationsforScheduledFunctionandSMSResultUpdateCallbacks