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

Attribute

Type

Filter

Sort

Description

id

int

Yes

Yes

Unique ID of the resource.

email_list_id

null/int

No

No

If 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/string

No

No

Sub-keyword on which to match, or null to catch all unmatched MO messages. Case-insensitive. Must be 1-32 characters in length.

list_id

int

No

No

ID of the list to which the message sender's MSISDN should be added.

message_id

null/int

No

No

If non-null, the ID of an SMS auto-responder campaign to be sent to the MO sender.

message_actionhour

null/string

No

No

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/int

No

No

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/bool

No

No

Defaults to null. Whether the rule will trigger at weekends, for 'message_id'.

name

string

Yes

Yes

A free-form name used to identify the rule.

notifyemail

null/string

No

No

If non-null, an email address to which the contents of a matching MO message will be sent.

notifymsisdn

null/string

No

No

If non-null, a MSISDN to which a matching MO message will be forwarded.

notifyurl

null/string

No

No

If non-null, a URL which will receive a GET request whenever a matching MO message is received.

paused

bool

Yes

No

If true, the rule is paused (i.e. matches will not occur); if false, the rule is active.

summary

string/null

No

No

English-language description of the rule.

user_id

int

Yes

No

Unique ID of the user who created this rule.

cdate

decimal

No

Yes

Creation timestamp.

mdate

decimal

No

No

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

Attribute

Type

Presence

Description

id

int

Optional

Unique ID of the resource.

name

string

Optional

A free-form name used to identify the rule.

paused

bool

Optional

If true, the rule is paused (i.e. matches will not occur); if false, the rule is active.

user_id

int

Optional

Unique ID of the user who created this rule.

POST /smsAutomation

Attribute

Type

Presence

Description

email_list_id

null/int

Optional

If 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/string

Required

Sub-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/int

Optional

If non-null, the ID of an SMS auto-responder campaign to be sent to the MO sender.

message_actionhour

null/string

Optional*

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/int

Optional*

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/bool

Optional*

Defaults to null. Whether the rule will trigger at weekends, for 'message_id'.

name

string

Required

A free-form name used to identify the rule.

notifyemail

null/string

Optional

If non-null, an email address to which the contents of a matching MO message will be sent.

notifymsisdn

null/string

Optional

If non-null, a MSISDN to which a matching MO message will be forwarded.

notifyurl

null/string

Optional

If non-null, a URL which will receive a GET request whenever a matching MO message is received.

paused

bool

Optional

If true, the rule is paused (i.e. matches will not occur); if false, the rule is active.

summary

string/null

Required

English-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

Attribute

Type

Presence

Description

id

int

Required

Unique ID of the resource.

email_list_id

null/int

Optional

If 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/string

Optional

Sub-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

Optional

ID of the list to which the message sender's MSISDN should be added.

message_id

null/int

Optional

If non-null, the ID of an SMS auto-responder campaign to be sent to the MO sender.

message_actionhour

null/string

Optional*

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/int

Optional*

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/bool

Optional*

Defaults to null. Whether the rule will trigger at weekends, for 'message_id'.

name

string

Optional

A free-form name used to identify the rule.

notifyemail

null/string

Optional

If non-null, an email address to which the contents of a matching MO message will be sent.

notifymsisdn

null/string

Optional

If non-null, a MSISDN to which a matching MO message will be forwarded.

notifyurl

null/string

Optional

If non-null, a URL which will receive a GET request whenever a matching MO message is received.

paused

bool

Optional

If true, the rule is paused (i.e. matches will not occur); if false, the rule is active.

summary

string/null

Optional

English-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

Attribute

Type

Presence

Description

id

int

Required

Unique ID of the resource.

keyword

null/string

no

Sub-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

no

ID 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

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