AT&T Aggregator Consent Management

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.

To provide Premium services to AT&T end users, you must follow AT&T aggregator consent management (ACM). This page is a guide to understanding ACM, including the workflow options. For information on the specific HTTP parameters used for ACM, please see Parameters for US carriers. For information on the specific SMPP TLVs for ACM, please see SMPP Interface Details.

Contents

What is AT&T aggregator consent management?

AT&T aggregator consent management (ACM) is a system for managing end user opt-in. The goal of ACM is to reduce customer service inquiries and refund request by ensuring that end users receive the correct opt-in information during the double opt-in process. All Premium rate services to AT&T customers, including both single-item and subscription, must comply with ACM. AT&T end users can opt-in to your services via a website or an SMS message.

ACM works by OpenMarket managing part of the opt-in process on behalf of your services. Your service will still need to initiate the process through a message request. However, the request message text only specifies a product description; it does not specify the HELP or STOP regulatory information you would normally include in an opt-in message. On receiving the request, OpenMarket takes the product description and amends it with the correct regulatory information and then sends this as an "advice of charge" (AOC) message to the end user. If the charge is successful, OpenMarket sends a "receipt" message that once again uses the product description amended with regulatory information.

To support a range of different end user opt-in scenarios and services, there are two message workflows your services can use: without PIN and with PIN.

Opt-in without PIN

The opt-in without PIN user experience is:

  1. The end user opts in via SMS or web.
  2. They receive a text message asking them to respond with "Y" to opt in.
  3. After responding Y back, they receive a receipt message.

This workflow is primarily intended for services using SMS opt-in. You can also use it for web services that don't require continuity after the purchase completes; for example, an online advertisement that signs users to a SMS alert subscription. Services that do require continuity should use the with PIN workflow.

This opt-in process only requires you to send one request. The workflow is the same for both single-item and subscription purchases:

  1. The end user initiates opt-in.
  2. You send a request to OpenMarket via your Premium rate AT&T account. In the request:

  3. http://sms.openmarket.com/sms/v1/send?user=attpremiumaccount&pass=P4ssw0rD&smsto=12515550100&smsmsg=ACME%20Music%20Store%3A%201%20song.&managed_consent_type=MO&report=7&response=text
  4. OpenMarket sends an AOC opt-in message to the end user. The message contents are the product description appended with the AOC information for that product. For example:

    ACME Music Store: 1 song. @$0.99. Reply HELP for help. Reply Y to confirm. Msg&data rates may apply.


  5. The end user responds with "Y" back (if they agree to the terms).
  6. OpenMarket charges the end user.
  7. Once the carrier has confirmed the charge, OpenMarket sends you a delivery report confirming the purchase (if requested).
  8. OpenMarket sends a receipt message to the end user (for successful transactions). This combines the product description and the "purchase receipt" information for the product. For example:

    ACME Music Store: 1 song. Purchased@$0.99 billed to cell. Reply HELP for help, STOP to cancel. Msg&data rates may apply.

Opt-in with PIN

The opt-in with PIN process involves a PIN generated by OpenMarket. The user experience is:

  1. The end user opts in via a website.
  2. They receive a text message asking them to enter a PIN into the website.
  3. After entering the PIN, they receive a receipt message.

This workflow is primarily intended for web services that require continuity after the purchase completes; for example, a music download site that gives end users access to content after the PIN is entered.

This process requires you to send two requests; the initial opt-in request and another request that returns the PIN to OpenMarket. The workflow is the same for both single-item and subscription purchases:

  1. The end user initiates opt-in.
  2. You send a request to OpenMarket via your Premium rate AT&T account. In the request:

  3. http://sms.openmarket.com/sms/v1/send?user=attpremiumaccount&pass=P4ssw0rD&smsto=12515550100&smsmsg=ACME%20Music%20Store%3A%201%20song.&managed_consent_type=PINAOCSIP&report=7&response=text
  4. OpenMarket sends an AOC opt-in message to the end user. The message contents are the product description appended with the AOC information, including a unique PIN, for that product. For example:

    ACME Music Store: 1 song. @$0.99. Your PIN is:1234. Reply HELP for help. Msg&data rates may apply.


  5. If the end user agrees to the terms, they enter the PIN into your website.
  6. You send another request to OpenMarket via your Premium rate AT&T account. In the request:
    • The message text is a short product description no more than 60 characters long.
    • The request includes the managed_consent_type parameter (or SMPP TLV) that identifies it as an AT&T ACM message containing a PIN.
    • The request includes the pin parameter (or SMPP TLV) that contains the PIN sent by the end user.
      Example HTTP request:

    http://sms.openmarket.com/sms/v1/send?user=attpremiumaccount&pass=P4ssw0rD&smsto=12515550100&smsmsg=ACME%20Music%20Store%3A%201%20song.&managed_consent_type=PIN&pin=1234&report=7&response=text
  7. OpenMarket confirms that the PIN is correct, then charges the end user.
  8. Once the carrier has confirmed the charge, OpenMarket sends you a delivery report confirming the purchase (if requested).
  9. OpenMarket sends a receipt message to the end user (for successful transactions). This combines the product description and the "purchase receipt" information for the product. For example:

    ACME Music Store: 1 song. Purchased@$0.99 billed to cell. Reply HELP for help, STOP to cancel. Msg&data rates may apply.

Each PIN expires five minutes after it was generated by OpenMarket. If the AT&T subscriber loses the PIN, a new PIN must be generated and sent in a new AOC message.

Product description

You must specify the following in the product information:

  • Sponsor
  • Product disclosure
  • For subscriptions, the frequency of receiving content

You cannot use binary encoding for the message text.

Message length

The maximum character length of the product information is different depending on the request:

  • The initial request for a without-PIN workflow - 60 characters
  • The initial request for a with-PIN workflow - 80 characters
  • The second request (that includes the PIN) for a with-PIN workflow - 60 characters

Examples

Subscription example:

  ACME News Alerts: Sign up & receive ACME Info Alts! 5msgs/week.

Single-item example:

  ACME Music Store: 1 song.

Advice of charge (AOC) and receipt messages

The two message types that the Gateway will send on behalf of your service are:

  • Advice of charge (AOC) message
    This asks the end user to confirm the charge.
    This message is created from your product description and the regulatory text required at the AOC stage.
  • Receipt message
    This provides the end user with a receipt of a successful charge.
    This message is created from your product description and the regulatory text required at the receipt stage.

All other messaging to the end user remain your service's responsibility. For example, if the end user responds "Y" to the opt-in process, but the charge fails (at which point you'll be notified via a delivery report), you may wish to message the user to advise them of the charge failure.

AOC message — format and examples:

Message typeFormatExample full message
Subscription AOC - without PIN @charge-amount/mo. Reply HELP for help. Reply Y to confirm. Msg&data rates may apply. ACME News Alerts: Sign up & receive ACME Info Alts! 5msgs/week. @$9.99/mo. Reply HELP for help. Reply Y to confirm. Msg&data rates may apply.
Single-item purchase AOC - without PIN @charge-amount. Reply HELP for help. Reply Y to confirm. Msg&data rates may apply. ACME Music Store: 1 song. @$0.99. Reply HELP for help. Reply Y to confirm. Msg&data rates may apply.
Subscription AOC - with PIN @charge-amount/mo. Your PIN is:pin. Reply HELP for help. Msg&data rates may apply. ACME News Alerts: Sign up & receive ACME Info Alts! 5msgs/week. @$9.99/mo. Your PIN is:1234. Reply HELP for help. Msg&data rates may apply.
Single-item purchase AOC - with PIN @charge-amount. Your PIN is:pin. Reply HELP for help. Msg&data rates may apply. ACME Music Store: 1 song. @$0.99. Your PIN is:1234. Reply HELP for help. Msg&data rates may apply.

Receipt message — format and examples:

Message typeFormatExample full message
Subscription receipt Purchased@charge-amount/mo billed to cell. Reply HELP for help, STOP to cancel. Msg&data rates may apply. ACME News Alerts: Sign up & receive ACME Info Alts! 5msgs/week. Purchased@$9.99/mo billed to cell. Reply HELP for help, STOP to cancel. Msg&data rates may apply.
Single-item purchase receipt Purchased@charge-amount billed to cell. Reply HELP for help, STOP to cancel. Msg&data rates may apply. ACME Music Store: 1 song. Purchased@$0.99 billed to cell. Reply HELP for help, STOP to cancel. Msg&data rates may apply.

For more information, please contact us at 1-877-698-3532 or via email at sales@uk.openmarket.com.