AT&T In-App Messaging API Documentation
Introduction
The In-App Messaging API sends, receives, updates, and deletes MMS and SMS messages on behalf of a specific user after confirming explicit user consent.
Using this API, your app can send MMS and SMS messages to another phone number (AT&T and cross-carrier), short codes, or e-mail addresses.
API Quick Start
Get App Key & App Secret
To start working with AT&T APIs, create a developer account or sign in to your existing account on the AT&T Developer Program website.
Click on the My Apps selection and set up a new app account by providing an Application Name. Then, choose one or both of the following from the list of available APIs: In-App Messaging-IMMN, In-App Messaging-MIM and click submit to get an App Key and App Secret.
Get OAuth Access Token
AT&T uses the OAuth 2.0 framework to obtain an OAuth access token as shown in this call flow. To obtain an access token, use the following OAuth sample code:
# Obtain these from your app account on the AT&T Developer Program website. APP_KEY="" APP_SECRET="" # Set up the scopes for requesting API access. SCOPE="IMMN,MIM" # Set up the redirect URL for consent flow. # Note that this must be escaped REDIRECT_URI="http%3A%2F%2Flocalhost" # Step 1: Request the OAuth authorization code from the user. echo "https://api.att.com/oauth/v4/authorize?client_id=${APP_KEY}&scope=${SCOPE}&redirect_uri=${REDIRECT_URI}" # Input the OAuth authorization code obtained from user consent. OAUTH_AUTHORIZATION_CODE="ENTER_VALUE" # Set up the payload. DATA="grant_type=authorization_code&client_id=${APP_KEY}&client_secret=${APP_SECRET}&code=${OAUTH_AUTHORIZATION_CODE}" # Step 2: Request the OAuth access token by exchanging the OAuth authorization code. curl "https://api.att.com/oauth/v4/token" \ --insecure \ --header "Content-Type: application/x-www-form-urlencoded" \ --header "Accept: application/json" \ --data ${DATA}
For more information refer to the OAuth 2.0 API.
Make API Calls
- Get Started - Send a Message
This scenario shows the most basic flow. Use it to send a message from the AT&T customer's message inbox to a phone number, short code or e-mail address. The message will appear as to be sent through the messaging app on the user's mobile device.
# Enter the authentication code generated by the consent flow here. OAUTH_ACCESS_TOKEN="ENTER_VALUE" # Telephone number to which the message is sent. TEL="ENTER_VALUE" # Message text body. MESSAGE="Message text" # Message text subject. SUBJECT="Message Subject" # Format the body that will be sent via curl. BODY={"Addresses":[${TEL}],"Text":"${MESSAGE}","Subject":"${SUBJECT}"} # Step 2: Send a message using the API. curl "https://api.att.com/myMessages/v2/messages" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer ${OAUTH_ACCESS_TOKEN}" \ --header "Accept: application/json" \ --data "${BODY}" \ --request POST
- Read Inbox - Retrieve All Messages
This scenario shows how to retrieve all the messages from the user’s inbox. An index, on the message inbox, must exist before attempting to retrieve the messages. The index must be created once per inbox and may expire due to inactivity in the inbox. The offset parameter controls the starting position in the set of messages, and the limit parameter controls the number of messages retrieved.
# Enter the authentication code generated by the consent flow here. OAUTH_ACCESS_TOKEN="ENTER_VALUE" # Enter a valid number (<= 300) of messages to request MESSAGE_LIMIT="100" # Step 2: Get a list of messages using the Get Message List method. curl "${FQDN}/myMessages/v2/messages?limit=${MESSAGE_LIMIT}" \ --header "Authorization: Bearer ${OAUTH_ACCESS_TOKEN}" \ --header "Accept: application/json" \ --request GET
Considerations
You need to be aware of the following considerations when using this API.
For any of the methods of this API, if an HTTP Status Code 503 is returned in the response, you should check the Retry-After header. If it exists, then the value given in the header indicates when it is recommended to retry the request.
For the Send Message method.
- This method sends messages only to mobile devices on other carriers in the USA. Sending messages to international numbers is not currently supported.
- There are a few limitations related to cache that are related to initialization and expiration. Please see our FAQs for more details.
For all of the methods.
- The consent from the user is required.
- The methods are only available to AT&T Wireless post-paid mobile phone users.
Managing a user's inbox.
- In order to utilize this API, the user must be provisioned with the AT&T; Cloud Inbox. This provisioning is done during the user consent authorization process. In the event that a user is not provisioned the first time, they can self-remedy the situation by trying to complete the user consent authorization for the app again at a later time. However, if the error persists, the customer should be advised to call AT&T CARE.
- The AT&T backup and sync service stores a maximum of 1000 SMS and MMS messages on the cloud for 90 days. Messages that are stored locally on devices are not deleted after that period
Managing a user's message index.
- In order to manage and update a user's message inbox, a message index must be created and maintained. Once it is created, the index is persisted for a 30-day rolling period, and can be kept alive beyond that time by sending a Get Message Index Info request once every 24 hours. There are practices that should be followed when managing the index in order to achieve higher performance and a better experience while interacting with the user's inbox.
Note: Due to platform enhancements in the November 2016 release, your index cache that was created previous to that release will either be new or will need to be re-created. In either case, the use of a previously stored state value will no longer work for delta calls. Your application will need to re-synchronize messages as required. Message IDs will be different. You may be able to correlate previously stored messages by using the timestamp and from/recipients to uniquely identify messages.
The developer must be aware that there are inactivity timers.
- Once the cache status is set to INITIALIZED, the cache status is persisted per customer for a 30-day rolling period when the Get Message Index Info method request is sent unless an error occurs in the AT&T Messaging system that corrupts the cache.
- A cache status that is set to INITIALIZED is continuously kept up-to-date with the source platform if the Get Message Index Info method request is sent during the last 24 hours. This guarantees that a long-running app will continue to receive notifications for deltas in the customer's AT&T Message inbox.
The main way to keep an app synchronized with the customer's AT&T Message inbox is described as following.
- A developer is also able to implement message polling using the Get Delta method request. This method sends only a summary of the updates to an AT&T Message inbox.
In the event that a customer's AT&T Message inbox is not able to be provisioned, in most cases, the customer is able self-remedy the situation by simply trying to complete the user consent authorization for the app again at a later time. However, if the error persists, the customer should be advised to call CARE to determine if the issue stems from a different issue or will take time to correct. The error message that the customer receives is similar to the following.
Sorry, we were unable to set up AT&T Messages Backup and Sync Service. Please try again later. If the error persists, please call Customer Care by dialing 611 from your AT&T mobile phone.