Follow

Subscribe to SMS (SMS Save)

The SMS Save or Subscribe to SMS command allows you to add a Contact to send SMS messages.  The Subscribe to SMS command requires the following arguments: Command, Data with Country, SMS Contact Phone, and SMS Sender Code in the following order.

cmd=smssave&data=country,phone,sender^US,5555091000,12016270164

The command is ‘smssave', and a subscription for the US phone number '5555091000' will be added to SMS Sender Code '12016270164' currently defined in the realm.

You can add one or many contacts with the same subscribe command.  To add multiple contacts, include additional contacts separated by the carat (^) character.  Each additional contact must have the same number of data fields defined.

The SMS Save command expects as least three fields in the Data argument: the SMS sender, SMS Contact phone number and country code are always required to create an SMS subscription record.  A normal Contact record is not necessary. The optional SMS Group ID can also be included in a command for SMS Contacts that do not correspond to an email Contact.

cmd=smssave&data=country,phone,sender,sms_group_id^US,5555091000,12016270164,21

The Phone number must be unique to a single SMS Contact.  Attempting to add an SMS Subscription using the same Phone number for multiple contacts will result in a failure.  The SMS subscription will also fail when attempting to add with a Contact email that does not exist.  If multiple contacts have the same email address, you must include the first name with the email address, or use the contact ID, in order to associate the SMS subscription to the correct contact.

The Data fields supported include:

Name  Field Description
SMS Sender  sender

Sender Code representing the message sender.  A Sender Code is either a short code or number. It represents the 'from' field when deploying an SMS. The message recipient will see this sender on their mobile device when a message is received. The Sender Code must be define in the SMS UI prior to adding SMS Contacts.

Contact Phone   phone

Numeric phone number for the Contact.  Do not include special characters (such as parenthesis or dash). This SMS Phone number does not need to match that of the Phone number stored for the Contact Data Fields.

Country  country

Two letter country code for the Contact phone carrier.  Only US is supported at this time.

Contact ID  subscriber_id

Contact ID of the Contact to subscribe to SMS. Can be used in place of Email+First or Customer Key.

First Name  first

First name of the Contact to subscribe to SMS.  Must be used with Email. 

Email  email

Email address of the Contact to subscribe to SMS. Contact must already exist as a regular Email contact, even if not subscribed to any List.

Customer Key  customer_key

Customer Key of the Contact to subscribe. Contact must already exist as a regular Email contact, even if not subscribed to any List.

SMS Group   sms_group_id 

Group to associate SMS Subscription for sending batch messages.  Group is optional.  

Resubscribe

When an SMS Contact opts out of future messages by sending a STOP request, an Opt Out record is created which prevents both future subscriptions and sending future messages.  To override an opt out you must use the force_subscribe argument in the header of your FTP file.  This should only be used in very specific cases in which you have verified the contact's desire to opt in to your list.  To learn more about Force Subscribe, see the FTP API Conventions.

Example

Using all commands and arguments (please note the command is wrapped for display purposes only, and the field order is required):

cmd=smssave&data=country,phone,subscriber_id,sender,first,email,sms_group_id^US,5555555008,555,120162701645,Jane,jane@domain.com,12

The normal Contact, ‘jane@domain.com’, will be subscribed to SMS Sender ‘18005559999’ in the SMS Group with ID '12'. 

You can also identify the Contact using email and first name or contact ID only.

cmd=smssave&data=country,phone,subscriber_id,sender,first,email,sms_group_id^US,5555555008,,120162701645,Jane,jane@domain.com,12

cmd=smssave&data=country,phone,subscriber_id,sender,first,email,sms_group_id^US,5555555008,555,120162701645,,12

Customer Key Example

Some systems have the ability to define a unique Customer Key per contact.  If your realm has Customer Key enabled, then you can use the customer_key in the data argument to identify the Contact. For example:

cmd=smssave&data=country,phone,subscriber_id,sender,first,email,customer_key,sms_group_id^US,5555555008,,120162701645,,,555Jane,12

You can also identify the Contact using email and first name or contact ID.

cmd=smssave&data=country,phone,subscriber_id,sender,first,email,customer_key,sms_group_id^US,5555555008,,120162701645,Jane,jane@domain.com,,12

cmd=smssave&data=country,phone,subscriber_id,sender,first,email,customer_key,sms_group_id^US,5555555008,555,120162701645,,,12

Errors

The SMS Save command will fail if the SMS feature is not enabled for the realm.  It will also fail if an invalid SMS sender code, contact, or SMS group is specified or if an optout is encountered for the phone number.  The command will also fail if the Contact does not exist or an SMS subscription already exists for the specified phone number.  It does not validate that the Contacts Phone matches the SMS Phone.  Several example errors include:

  • SMS Sender could not be found for sender code
  • An SMS Subscription already exists
  • Country, Sender Code, Phone cannot be empty
  • Phone should only contain numeric digits
  • SMS Group could not be found with ID
  • Country Code is not supported (only US is supported at this time)
  • Email Contact could not be retrieved with the provided information.
  • Array index out of range (number of fields defined does not match number of data fields in command)

Arguments

The SMS Save command supports the following arguments:

Name

Req?

Description

Argument

Command

Yes

Defines the command to use.

cmd=smssave

Data Yes

Contact related data.  Phone, Country, and Sender are always required, and additional fields are optional.

data=[fields]

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

Powered by Zendesk