AT&T SMS API Version 3 Documentation (2024)

cURL

# Obtain these from your account on the AT&T Developer Program website.APP_KEY=""APP_SECRET=""# Set up the scopes for requesting API access. API_SCOPES="SMS"curl "https://api.att.com/oauth/v4/token" \--insecure \--header "Accept: application/json" \--header "Content-Type: application/x-www-form-urlencoded" \--data "client_id=${APP_KEY}&client_secret=${APP_SECRET}&grant_type=client_credentials&scope=${API_SCOPES}"

cURL

# Step 1:# Authentication parameter. For directions on how to obtain the OAuth access# token, see the OAuth section.OAUTH_ACCESS_TOKEN="ENTER_VALUE"# Step 2:# Fully qualified domain name for the API Gateway.FQDN="https://api.att.com"# SMS message text body.SMS_MSG_TEXT="SMS Message Text"# Enter telephone number to which the SMS message will be sent.# For example: TEL="tel:+1234567890"TEL="ENTER_VALUE"# Send the Send SMS method request to the API Gateway.curl "${FQDN}/sms/v3/messaging/outbox" \--header "Content-Type: application/json" \--header "Accept: application/json" \--header "Authorization: Bearer ${OAUTH_ACCESS_TOKEN}" \--data "{\"outboundSMSRequest\":{\"address\":\"${TEL}\",\"message\":\"${SMS_MSG_TEXT}\"}}" \--request POST

cURL

# Step 1:# Authentication parameter. For directions directions on how to obtain the OAuth access# token, see the OAuth section.OAUTH_ACCESS_TOKEN="ENTER_VALUE"# Step 2:# Fully qualified domain name for the API Gateway.FQDN="https://api.att.com"# Enter the registration identifier used to get an SMS message.REGISTRATION_ID="ENTER_VALUE"# Send the Get SMS method request to the API Gateway.curl "${FQDN}/sms/v3/messaging/inbox/${REGISTRATION_ID}" \--header "Authorization: Bearer ${OAUTH_ACCESS_TOKEN}" \--header "Accept: application/json" \--request GET

Overview

The Get SMS method receives multiple SMS messages sent to the short code associated with the app account from the AT&T Wireless network.

Each time this method is requested all SMS messages are received for the short code associated with the app account.

This method removes the messages from AT&T and therefore it retrieves only those SMS messages received since the previous Get SMS method request.

If there are more messages than could fit into a single response, the app must invoke multiple method requests to retrieve the complete list of the messages.

The totalNumberOfPendingMessages parameter in the SMS API response indicates that there are any more messages left on the server that are not sent in the current response.

An app that supports receiving SMS messages must invoke this request at least once every 30 minutes; otherwise the messages are automatically removed from the API Gateway.

For apps that expect to receive a lot of SMS messages, it is recommended that the app invokes this request frequently, but with a maximum frequency of one every 5 minutes.

Note: If the developer's app is expecting a huge number of Mobile Originated (MO) messages, then it is recommended to use the Receive SMS callback by registering a listener URI for the app where the API Gateway immediately delivers the incoming messages as soon as each message arrives in the AT&T Wireless network.

Note: This method is only allowed for a short code that is set up as an offline short code.

The process to obtain an offline short code for your app is described below.

Add one or more offline short codes as follows.

1. Your first step depends upon your app account.

• If you have not created an SMS app account, then create an app account with the API set to SMS and click on the Manage Short Code link after submitting your app account.
• If you have already created an SMS app account, go to the My Apps page, click on the link to your SMS app account, and navigate to the Manage Short Code page.

Note: If you want the SMS messages sent from the user's mobile device to be forwarded to your app immediately by the API Gateway, then you must register your SMS listener URI after creating the SMS app.

This enables you to utilize the Receive SMS method.

Note: This method removes all of the messages for the registrationID parameter value that are stored on the AT&T Wireless network at the time that this method is requested.

Overview

The Get SMS method receives multiple SMS messages sent to the short code associated with the app account from the AT&T Wireless network.

Each time this method is requested all of the SMS messages are received for the short code associated with the app account.

This method removes the messages from AT&T and therefore it retrieves only those SMS messages received since the previous Get SMS method request.

If there are more messages than could fit into a single response, the app must invoke multiple method requests to retrieve the complete list of the messages.

The totalNumberOfPendingMessages parameter in the SMS API response indicates that there are any more messages left on the server that are not sent in the current response.

An app that supports receiving SMS messages must invoke this request at least once every 30 minutes; otherwise the messages are automatically removed from the API Gateway.

For apps that expect to receive a lot of SMS messages, it is recommended that the app invokes this request frequently, but with a maximum frequency of one every 5 minutes.

Note: If the developer's app is expecting a huge number of Mobile Originated (MO) messages, then it is recommended to use the Receive SMS callback by registering a listener URI for the app where the API Gateway immediately delivers the incoming messages as soon as each message arrives in the AT&T Wireless network.

Note: This method is only allowed for a short code that is set up as an offline short code.

The process to obtain an offline short code for your app is described below.

Add one or more offline short codes as follows.

1. Your first step depends upon your app account.

• If you have not created an SMS app account, then create an app account with the API set to SMS and click on the Manage Short Code link after submitting your app account.
• If you have already created an SMS app account, go to the My Apps page, click on the link to your SMS app account, and navigate to the Manage Short Code page.

Note: If you want the SMS messages sent from the user's mobile device to be forwarded to your app immediately by the API Gateway, then you must register your SMS listener URI after creating the SMS app.

This enables you to utilize the Receive SMS method.

Note: This method removes all of the messages for the registrationID parameter value that are stored on the AT&T Wireless network at the time that this method is requested.

Overview

The Get SMS Delivery Status method requests the status of a previously submitted SMS delivery request that was accepted by the API Gateway for delivery to the destination mobile device.

The Get SMS Delivery Status method is one of two ways in which the delivery status of a sent message may be obtained from the API Gateway.

The other way is to register an endpoint URI with the API Gateway which will be notified of the final status of the message. For a given message, only one of these mechanisms can be used.

The indicator of which mechanism will be used is the notifyDeliveryStatus parameter of the Send SMS method request.

To request the delivery status of a sent message using the Get SMS Delivery Status method, the notifyDeliveryStatus parameter of the Send SMS method must be set to false or should not be present in the request, this causes the messageId parameter value to be returned in the Send SMS method response.

The message identifier that was returned in the Send SMS method response must be provided in the Get SMS Delivery Status method request.

Note: The delivery status of the message is removed from the API Gateway and is not available for query, when one of the following events occurs.

• Thirty minutes have elapsed and the message has reached a final state of DeliveredToTerminal or DeliveryImpossible.
• The API Gateway responds to the first delivery status query after the message has reached the final state.

Request and Response Examples

JSON

Request

GET https://api.att.com/sms/v3/messaging/outbox/SMSa9b1927803784049Authorization: Bearer xyz123456789Accept: application/json

Response

{"DeliveryInfoList": {"DeliveryInfo": [{"Id": "msg0","Address": "+13500000992","DeliveryStatus": "DeliveredToTerminal"}],"ResourceUrl": "https://api.att.com/sms/v3/messaging/outbox/SMSa9b192780378404c"}}

Overview

The Get SMS Delivery Status method requests the status of a previously submitted SMS delivery request that was accepted by the API Gateway for delivery to the destination mobile device.

The message identifier returned in the response of the corresponding Send SMS method request must be provided in this method request.

Note: This method for polling for the delivery status message should work only when the notifyDeliveryStatus parameter is either set to false or not present in the Send SMS method request.

Note: The delivery status of the message is removed from the API Gateway and is not available for query, when one of the following events occurs.

• Thirty minutes have elapsed and the message has reached a final state of DeliveredToTerminal or DeliveryImpossible.
• The API Gateway responds to the first delivery status query after the message has reached the final state.

Request and Response Examples

JSON

Request

GET https://api.att.com/3/smsmessaging/outbound/requests/80712002/SMSa9b1927803784049/deliveryInfosAuthorization: Bearer xyz123456789Accept: appication/json

Response

{"deliveryInfoList": {"deliveryInfo": [{"address": "tel:+13500000992","deliveryStatus": "DeliveredToTerminal"}],"resourceURL": "https://api.att.com/3/smsmessaging/outbound/requests/80712002/SMSa9b1927803784049/deliveryInfos"}}

Overview

The Receive SMS callback receives the Mobile Originated (MO) SMS messages in the app immediately for messages that are destined for the specified short codes of the app account.

In this case, the API Gateway acts as a client and the developer's app acts as a server.

The developer exposes the app functionality to the API Gateway in the form of a URI listener. This URI is used by the API Gateway to forward the received messages.

Note: The developer must register the URI or the system will not be able push the notification to the app for the Mobile Originated (MO) Messages destined for the short code.

Note: If the URI provided is HTTPS and port is not defined, then the default SSL port 443 will be used. The use of a transport mechanism other than HTTPS is not supported in the URI.

When a user sends a message to AT&T short code, the system determines the app to which the short code is associated, and then forwards the message to the listener URI provisioned with the short code of the app account.

The messages are removed from the system after delivery is acknowledged by the app or until all the retries as per the retry configuration are exhausted.

The app must respond to the notification with an appropriate HTTP Status Code class of 2xx for positive acknowledgment.

The following explanation for the handling of the HTTP Status Codes sent by the user's app is sent in response to a notification from the API Gateway.

• In case of the HTTP Status Code class of 2xx, the server assumes positive acknowledgement that the notification has been sent successfully.
• In case of no response, timeout condition or HTTP Status Code classes other than 2xx, the server assumes that either the API Gateway is temporarily unavailable or cannot receive and process the notification at that point in time.

If the app SMS Mobile Originated (MO) URI listener is unavailable, busy, or otherwise unable to process and acknowledge the Mobile Originated (MO) message, then it will be retried as per the retry configuration set in the network.

Typically the retry period is 72 hours after which the message will be discarded and no further retries would be attempted.

Notification Examples

JSON

Notification

{"DateTime": "04-15-2011T12:00:00","MessageId": "","Message": "Hello world","SenderAddress": "tel:+12071111111","DestinationAddress": "52345678"}

Overview

The Receive SMS Delivery Status callback receives notifications of the final delivery status of the SMS messages sent by the app.

In this case, the API Gateway acts as a client and the developer's app acts as a server.

The developer provides the app listener endpoint URI to the API Gateway during the app account registration process or with an update to the app account against the appropriate short code associated with the app.

There exists a one-to-one association between the URI and a short code.

The URI is used by the API Gateway to notify the final delivery status of the SMS messages that were earlier accepted for delivery by the API Gateway against a specified short code.

Note: The delivery notification is delivered to the app only if requested in the Send SMS method request by setting the notifyDeliveryStatus parameter value to true.

Note: There is only one notification message per destination address when the SMS message is being delivered to multiple recipients in a single request.

Note: All of the notifications in this case might not be necessarily at the same time as it depends on the delivery of the SMS message to each recipient.

Note: If the URI provided is HTTPS and port is not defined, then the default SSL port 443 is used.

The use of a transport mechanism other than HTTPS is not supported in the URI.

When an SMS message that was earlier accepted for delivery reaches the final state and the app has requested for delivery notification in the Send SMS method request, a notification message is sent to the endpoint URI registered by the app for the specified short code.

The SMS message reaches the final status when it is delivered to the user's mobile device or when it expires in the network after multiple retries.

The number of retries is based on the Network retry configuration, which is currently set to 72 hours.

If the notifyDeliveryStatus parameter value is set to true in the Send SMS method request and if the notification endpoint URI is not provided or associated to the corresponding short code of the app in the app account, then the delivery notification status message might become lost.

The app listener is expected to respond to the notification with the appropriate HTTP Status Code class of 2xx for positive acknowledgement.

The following explanations describe the handling of HTTP Status Codes sent by the user's app, in response to a notification from the server.

• In case of the HTTP Status Code class of 2xx, the server assumes positive acknowledgement that the notification has been sent successfully.
• In case of no response, timeout condition or HTTP Status Code classes other than 2xx, the server assumes that either the API Gateway is temporarily unavailable or cannot receive and process the notification at that point in time.

If the registered app delivery notification URI listener is unavailable, busy or otherwise unable to process and acknowledge the delivery status notification message then it will be retried as per the retry configuration set in the AT&T Wireless network.

Typically the retry period is 72 hours after which the message will be discarded and no further retries would be attempted.

Notification Examples

JSON

Notification

{"deliveryInfoNotification": {"messageId": "0x181bce3883beadf85443215d6fL","deliveryInfo": {"address": "tel:+13500000012","deliveryStatus": "DeliveredToTerminal"}}}

Overview

The Send SMS method sends an SMS message to one or more AT&T Wireless mobile devices.

The SMS messages are processed synchronously and sent asynchronously to a destination on the AT&T Network.

A unique identifier (ID) is returned in the response that may be used to query the status of the message that has been sent.

Note: Using this provider of this method does not require you to specify the short code in your app account from which your SMS message will be originated.

The API Gateway uses the default short code associated with your app account as the originating sender address of the SMS message.

If you have more than one short code assigned to your app account and require the abilty to specify a specific short code as the originating sender address, then consider using the GSMA OneAPI provider of this method.

Request

POST https://api.att.com/sms/v3/messaging/outbox HTTP/1.1Host: api.att.comAuthorization: Bearer xyz123456789Accept: application/jsonContent-Type: application/json{"outboundSMSRequest": {"address":"tel:+13500000992","message":"Hello World",}}

Response

{"outboundSMSResponse": {"messageId": "SMSa9b4dd85737c0409","resourceReference": {"resourceURL": "https://api.att.com/sms/v3/messaging/outbox/SMSa9b4dd85737c0409"}}}

Request

POST https://api.att.com/sms/v3/messaging/outbox HTTP/1.1Host: api.att.comAuthorization: Bearer xyz123456789Accept: application/jsonContent-Type: application/json{"outboundSMSRequest": {"address":["tel:+13500000992","tel:+13500000993"],"message":"Hello World","notifyDeliveryStatus":true}}

Response

{"outboundSMSResponse": {"messageId": "0x183269c8f460D1B3A170DF153FL"}}

Request

POST https://api.att.com/sms/v3/messaging/outbox HTTP/1.1Host: api.att.comAuthorization: Bearer xyz123456789Accept: application/jsonContent-Type: application/json{"outboundSMSRequest": {"address":"tel:+13500000992","message":"Hello World"“notifydeliverystatus”:True}}

Response

{"outboundSMSResponse": {"messageId": "0x183269c8f460D1B3A170DF153FL",}}

Request

POST https://api.att.com/sms/v3/messaging/outbox HTTP/1.1Host: api.att.comAuthorization: Bearer xyz123456789Accept: application/jsonContent-Type: application/x-www-form-urlencodedaddress=tel%3A%2B13500000992%2Ctel%3A%2B13500000993&message=Hello%20World

Request

POST https://api.att.com/sms/v3/messaging/outbox HTTP/1.1Host: api.att.comAuthorization: Bearer xyz123456789Accept: application/jsonContent-Type: application/x-www-form-urlencodedaddress=tel%3A%2B13500000992%2Ctel%3A%2B13500000993&message=Hello%20World&notifyDeliveryStatus=True

Overview

The Send SMS method sends an SMS message to one or more AT&T Wireless mobile devices.

The SMS messages are processed synchronously and sent asynchronously to a destination on the AT&T Network.

A unique identifier (ID) is returned in the response that may be used to query the status of the message that has been sent.

Note: Using this provider of this method enables you to specify the sender originator address of the SMS message as a parameter in the URI, if you have one or more short codes assigned to your app account.