SmsAutomation v1.2

Trigger powerful automation rules when an SMS message is sent to an smsDestination related to your account.

What can I do with smsAutomation?

An smsAutomation rule describes the Marketing Automation actions which take place after an SMS is sent to the related smsDestination:

  • The actions will be automatically triggered when an SMS message is sent to a destination containing the keyword specified in smsDestination.
  • Actions include subscription behaviours (such as adding an email address included in the SMS message to a list), contact, notifications and auto-responders.
  • For some actions you can specify when the action will execute. This can be as soon as possible, before/after a fixed period or at a specific time.

Actions may be queued when triggered by the event. Queued actions will complete when a rule is paused, but are aborted when a rule is deleted.

GET /smsAutomation or /smsAutomation/:id

AttributeTypeFilterSortDescription
id
intYesYesUnique ID of the resource.
email_list_id
null/intNoNoIf non-null, the ID of a list to which the sender's email address should be added, if the MO contains an email address.
keyword
null/stringNoNoSub-keyword on which to match, or null to catch all unmatched MO messages. Case-insensitive. Must be 1-32 characters in length.
list_id
intNoNoID of the list to which the message sender's MSISDN should be added.
message_id
null/intNoNoIf non-null, the ID of an SMS auto-responder campaign to be sent to the MO sender.
message_actionhour
null/stringNoNoIf non-null, the hour (format "HH:00:00") at which the SMS auto-responder campaign (if one has been set) should be sent to the MO sender.
message_actiontimediff
null/intNoNoIf non-null, the offset (in seconds) between receipt of a matching MO message and the despatch of an SMS auto-responder.
message_actiononweekend
null/boolNoNoDefaults to null. Whether the rule will trigger at weekends, for 'message_id'.
name
stringYesYesA free-form name used to identify the rule.
notifyemail
null/stringNoNoIf non-null, an email address to which the contents of a matching MO message will be sent.
notifymsisdn
null/stringNoNoIf non-null, a MSISDN to which a matching MO message will be forwarded.
notifyurl
null/stringNoNoIf non-null, a URL which will receive a GET request whenever a matching MO message is received.
paused
boolYesNoIf true, the rule is paused (i.e. matches will not occur); if false, the rule is active.
summary
string/nullNoNoEnglish-language description of the rule.
user_id
intYesNoUnique ID of the user who created this rule.
cdate
decimalNoYesCreation timestamp.
mdate
decimalNoNo

Last modification timestamp.

Rules will be paused if an associated list (or its containing folder) is deleted.

If keyword is "null", 'catch-all' behaviour will be applied for this rule. A case-insensitive match will be applied to the keyword when triggering the rule. The keyword must contain alphanumeric characters only and be between 1 characters and 32 characters in length (though we recommend using at least 4).

HEAD /smsAutomation or /smsAutomation/:id

AttributeTypePresenceDescription
id
intOptionalUnique ID of the resource.
name
stringOptionalA free-form name used to identify the rule.
paused
boolOptionalIf true, the rule is paused (i.e. matches will not occur); if false, the rule is active.
user_id
intOptionalUnique ID of the user who created this rule.

POST /smsAutomation

AttributeTypePresenceDescription
email_list_id
null/intOptionalIf non-null, the ID of a list to which the sender's email address should be added, if the MO contains an email address.
keyword
null/stringRequiredSub-keyword on which to match, or null to catch all unmatched MO messages. Case-insensitive. Must be 1-32 characters in length (though we recommend using at least 4).
list_id
int

Required

ID of the list to which the message sender's MSISDN should be added.
message_id
null/intOptionalIf non-null, the ID of an SMS auto-responder campaign to be sent to the MO sender.
message_actionhour
null/stringOptional*If non-null, the hour (format "HH:00:00") at which the SMS auto-responder campaign (if one has been set) should be sent to the MO sender.
message_actiontimediff
null/intOptional*If non-null, the offset (in seconds) between receipt of a matching MO message and the despatch of an SMS auto-responder.
message_actiononweekend
null/boolOptional*Defaults to null. Whether the rule will trigger at weekends, for 'message_id'.
name
stringRequiredA free-form name used to identify the rule.
notifyemail
null/stringOptionalIf non-null, an email address to which the contents of a matching MO message will be sent.
notifymsisdn
null/stringOptionalIf non-null, a MSISDN to which a matching MO message will be forwarded.
notifyurl
null/stringOptionalIf non-null, a URL which will receive a GET request whenever a matching MO message is received.
paused
boolOptionalIf true, the rule is paused (i.e. matches will not occur); if false, the rule is active.
summary
string/nullRequiredEnglish-language description of the rule.

* message_actionhour, message_actiontimediff and message_actiononweekend can only be set/modified if message_id is set.

If enabled for the company, folder restrictions will apply to this endpoint. Users will only be able to create list-related rules for lists in categories that they have access to.

Only rules created by the user can be modified/deleted by that user, unless the user has admin permissions.

Users will only be permitted to set/modify message_id to the message ID of an SMS message they have access to.

PUT /smsAutomation or /smsAutomation/:id

AttributeTypePresenceDescription
id
intRequiredUnique ID of the resource.
email_list_id
null/intOptionalIf non-null, the ID of a list to which the sender's email address should be added, if the MO contains an email address.
keyword
null/stringOptionalSub-keyword on which to match, or null to catch all unmatched MO messages. Case-insensitive. Must be 1-32 characters in length (though we recommend using at least 4).
list_id
intOptionalID of the list to which the message sender's MSISDN should be added.
message_id
null/intOptionalIf non-null, the ID of an SMS auto-responder campaign to be sent to the MO sender.
message_actionhour
null/stringOptional*If non-null, the hour (format "HH:00:00") at which the SMS auto-responder campaign (if one has been set) should be sent to the MO sender.
message_actiontimediff
null/intOptional*If non-null, the offset (in seconds) between receipt of a matching MO message and the despatch of an SMS auto-responder.
message_actiononweekend
null/boolOptional*Defaults to null. Whether the rule will trigger at weekends, for 'message_id'.
name
stringOptionalA free-form name used to identify the rule.
notifyemail
null/stringOptionalIf non-null, an email address to which the contents of a matching MO message will be sent.
notifymsisdn
null/stringOptionalIf non-null, a MSISDN to which a matching MO message will be forwarded.
notifyurl
null/stringOptionalIf non-null, a URL which will receive a GET request whenever a matching MO message is received.
paused
boolOptionalIf true, the rule is paused (i.e. matches will not occur); if false, the rule is active.
summary
string/nullOptionalEnglish-language description of the rule.

* message_actionhour, message_actiontimediff and message_actiononweekend can only be set/modified if message_id is set.

If message_id is set, message_actiontimediff must be 0 or greater. If message_actionhour is also set, message_actiontimediff must be 0 or divisible by 1440.

The message_actionhour should be set to a local time for the company's timezone.

message_actiononweekend can only be set to "false" if message_id and one or both of message_actionhour or message_actiontimediff are set. If only message_id is set, message_actiononweekend will implicitly be set to "true". If message_id is not set, message_actiononweekend will be "null".

If a rule is paused and the resource associated with its list_id, email_list_id or message_id is removed or becomes inaccessible, the user will not be permitted to un-pause the rule without changing the relevant argument to a valid resource (or to "null", if applicable).

DELETE /smsAutomation or /smsAutomation/:id

AttributeTypePresenceDescription
id
intRequiredUnique ID of the resource.
keyword
null/stringnoSub-keyword on which to match, or null to catch all unmatched MO messages. Case-insensitive. Must be 1-32 characters in length (though we recommend using at least 4).
list_id
intnoID of the list to which the message sender's MSISDN should be added.

Deletion of rules is restricted by user. Only rules created by the user can be deleted by that user, unless they are the admin user who can delete any rules.

Error codes

CodeSubcodeMessageDescription
409
12
Automation Rule $id cannot be unpaused: Dependent $resource resource $resource_id no longer existsIf an automation rule dependent resource (usually actiontarget, but for smsAutomation it could be list_id, email_list_id or message_id) is deleted, and the associated rule is paused, this error will be given if the user then tries to unpause the rule without changing the dependent resource.

Please see error handling for more information on error codes.

Examples

JSON response

{
    "id":                      12345,
    "email_list_id":           1234,
    "keyword":                 "demo",
    "list_id":                 1234,
    "message_id":              1234,
    "message_actionhour":      "15:00:00",
    "message_actiontimediff":  0,
    "message_actiononweekend": false,
    "name":                    "Demo request trigger",
    "notifyemail":             "mailbox@example.com",
    "notifymsisdn":            "447999000000",
    "notifyurl":               "https://www.example.com/moreceiver"
    "paused":                  false,
    "summary":                 "When a message containing the sub-keyword 'demo' is received, add the sender to list 1234 and send a responder message.",
    "user_id":                 23456,
    "cdate":                   1234966741,
    "mdate":                   1234966741,
 
}