Parameters required for US networks

Overview

OpenMarket now offers a RESTful and feature-rich Global SMS API. Compared to the existing MX Telecom APIs, the Global SMS API provides:

  • Automated originator selection, which selects the correct short code or VMN for any country or territory
  • Our highest level SLA and increased messaging capacity
  • Better security through Basic authentication
  • A test environment for new and migrating customers

as well as a host of other benefits. While we will continue to support our existing SMS APIs, we believe that our Global SMS API offers some exciting features and benefits that you'll want to take advantage of, and future feature development will be focused on the Global SMS API. For more information, see the Release Note on our Docs and Resources website.

Note that currently the Global SMS API does not support Premium Rate messaging. Existing Premium Rate customers should continue to use the MX Telecom APIs.

This page describes the parameters required when sending an SMS message to specific US networks:

For information about integrating with the SMS Gateway, see either Sending a Single SMS or Broadcasting an SMS.

Verizon consent management and purpose codes

Verizon consent management (VCM) is a system for managing both end user opt-in, and the help and stop messages for your service. To provide Premium services to Verizon end users, you must follow VCM.

For a guide on understanding and implementing VCM, see Verizon Consent Management.

ParameterDescription
managed_consent_typeIdentifies the request as a consent management request and identifies how the end user initiated opt-in. Note that this parameter is also used in AT&T ACM requests.
Default: No default
IVRThe end user initiated opt-in via an IVR service.
MOThe end user initiated opt-in via an MO SMS message.
WEBThe end user initiated opt-in via a website.
initial_optin_keywordThe keyword the end user entered (via SMS) that triggered the specific service. If the opt-in occurred via a web page, you may send any keyword. The maximum length is 20 characters. The initial opt-in keyword parameter is not required for IVR initiated purchases. Do not send the initial opt-in keyword parameter if you set the managed_consent_type parameter to IVR.
Default: No default

Verizon also requires you to identify the purpose of some standard rate messages sent as part of a premium rate campaign.

ParameterDescription
purposeIdentifies the specific purpose of the message.
Default: No default
opt_in_premiumUse for standard rate messages sent during the opt-in process.
premium_contentUse when delivering purchased premium content in a standard rate message.

T-Mobile opt in details

These parameters are required by T-Mobile in the United States only.

T-Mobile US requires you to send opt-in tracking data for certain transactions. The transaction types that require this data are:

Service typeMT message that requires opt-in details
One time Premium RateThe Premium Rate SMS message used to bill the end user.
Premium Rate subscriptionsThe monthly Premium Rate SMS message used to renew the subscription.

Transactions which do not include this data may fail, and T-Mobile may remove the associated services from their network.

To supply the required opt-in information when you send an SMS message, there are four parameters you may need to include. The parameters optin1 and optin2 are always mandatory. These specify the method used by the end user to opt in to your service. The parameters optints1 and optints2 specify the time these opt-ins occurred. If opt-in was carried out via SMS, you do not need to specify the time, as the SMS Gateway already has this information.

For example, the following request specifies that the first opt-in was web-based and occurred on the 5th of January 2010, and the second opt-in was via SMS:

http://sms.openmarket.com/sms/v1/send?user=MyTMobilePRAccount&pass=TMP4ssw0rD&smsto=12515550100&smsmsg=Subscription%20renewal%20message&optin1=url:http%2F%2Fwww.example.com&optin1ts=1262718000&optin2=sms:3999775791
ParameterDescription
optin1Describes how the first opt-in occurred. It takes the format source:sourceid, where both source and sourceid are mandatory.
sms:smsidThe SMS ID returned by the SMS Gateway that corresponds to the first Mobile Originated (MO) SMS opt-in message.
Example: optin1=sms:123455678
url:websiteThe URL where a web opt-in occurred.
Example: optin1=url:http://example.com
other:textDescription of any other opt-in scenario.
Example: optin1=other:at+point+of+sale
optin1tsThe time that the first opt-in occurred. This timestamp is in seconds since 01/01/1970 (also known as a Unix timestamp).
This parameter is optional if the end user's first opt in was through an SMS message, i.e., where the value of optin1 is sms:smsid.
Example (5th September 2010 @ 07:30:00): optin1ts=1283689800
optin2Describes how the second opt-in occurred.
pin:pinPIN used for PIN opt-in services.
Example: optin2=pin:1337
sms:smsidThe SMS ID returned by the SMS Gateway that corresponds to the second Mobile Originated (MO) SMS opt-in message.
Example: optin2=sms:123455678
url:websiteThe URL where a web opt-in occurred.
Example: optin2=url:http://example.com
other:textDescription of any other opt-in scenario.
Example: optin2=other:at+point+of+sale
optin2tsThe time that the second opt-in occurred. This timestamp is in seconds since 01/01/1970 (also known as a Unix timestamp).
This parameter is optional if the end user's second opt in was through an SMS message, i.e., where the value of optin2 is sms:smsid.
Example (5th September 2010 @ 07:30:00): optin1ts=1283689800

AT&T aggregator consent management

AT&T aggregator consent management (ACM) is a system for managing end user opt-in. To provide Premium services to AT&T end users, you must follow ACM.

For a guide on understanding and implementing ACM, see Consent Management.

ParameterDescription
managed_consent_typeIdentifies the request as a consent management request. This parameter is required for any request sent as part of the AT&T ACM workflow. Note that this parameter is also used in Verizon consent management requests.
Default: No default
MOInitiates a without-PIN opt in and identifies that the end user begun opt-in via an MO SMS message.
WEBInitiates a without-PIN opt in and identifies that the end user begun opt-in via a website.
PINAOCSIPInitiates a with-PIN opt in and identifies that it is for a single-item purchase.
PINAOCSUBInitiates a with-PIN opt in and identifies that it is for a subscription service.
PINIdentifies this request as the second message required for the with-PIN workflow. The request must also include the pin parameter.
IVRAvailable only to partners who are already running AT&T ACM with IVR opt-in. This initiates a without-PIN opt in and identifies that the end user begun opt-in via an IVR service.
pinThe PIN entered by the end user as part of the with-PIN opt in process.
Default: No default