AT&T SMS API FAQs
Am I able to send messages using a common short code (five or six digits) that I already have?
It is possible to use custom short codes (including common short codes) with an application; provided that they are leased or owned by you from Neustar and also approved, as well as configured, to be associated with your application by an AT&T administrator. By default, you are provided one short-code with an application with the capability of adding or removing up to 5 short codes.
How can my application access the SMS messages that are sent by AT&T Wireless customers to the short code associated with my application?
Your application has two ways of retrieving messages that are sent by AT&T Wireless customers to the short code associated with your application. One way is where your application will use the polling mechanism to check the inbox associated with your application short code for any new message arrival. The other way is using the callback operation by registering your application listener endpoint to receive the incoming messages.
Your preference has to be implicitly indicated on the preferred mechanism that your application wants to use, while requesting or associating a short code for your application. This is because, for a given short code, both mechanisms could not co-exist for receiving incoming SMS messages.
How do I query the status of the message when I send the same message to multiple recipients?
Even though the same message is sent to multiple recipients, the combination of the unique identifier returned in the response of the send request and the destination customer's phone number, can be used to correlate the status of the message sent.
If your application is using the polling mechanism to obtain the status, the response would contain individual status entries for recipients.
If the application is using the callback operation, by registering the listener endpoint to receive the status there would be multiple status notifications (one for each recipient). The delivery status notifications for different recipients may be delivered to your application server at different points in time depending on when those messages are delivered to the individual recipients or expired in the network when they can't be delivered until the specified expiry period is reached.
How quickly are messages delivered?
Most messages that are delivered to a device which is turned on and connected to the AT&T Wireless network are delivered quickly, often in seconds. However, the delivery time needed for individual messages varies with factors such as network load, user location, and the network connectivity of the device.
What is a custom short code?
A custom short code is a short code that a developer wants to associate with their application that is different from the default 8-digit short code provided by the AT&T API Platform.
If the custom short code is, as is common, a 5-digit or a 6-digit short code that is managed by usshortcodes.com to be used for cross-carrier messaging, it must be leased by the developer from usshortcodes.com and the developer must provide proof to AT&T that they own the short code before it can be associated with their application on the AT&T API Platform.
If the custom short code being requested by the developer is not a 5-digit or 6-digit short code, then AT&T determines whether the code is available, and whether it is willing to associate that short code to the application. If AT&T approves the custom short code for the given application, the application may incur additional charges.
There are two types of short codes that may be assigned to your application:
- Online short code: This short code is assigned to your application by default. It is also assigned if you provide a listener URL for Mobile Originated SMS messages so that you get notifications in real time.
- Offline short code: This short code is assigned if you are polling for messages or if you did not provide a listener URL for the incoming Mobile Originated SMS messages.
What happens when an SMS message cannot be delivered to the destination customer on the first attempt?
The message is queued up in the AT&T network and is retried on a periodic interval until a configured maximum period (normally 72 hours) is reached. After the configured retry period is exhausted, the SMS message expires. When the SMS message is expired in the network, the delivery status of the message is set to DeliveryImpossible for a given recipient.
How often do I need to invoke the Get SMS method?
The answer depends on the volume of messages and how often you are expecting them. The recommended interval is every 5 minutes. If you expect a lot of traffic, you should use the callback operation (for scalability) where your application can register a listener endpoint and where the API Gateway automatically notifies your application of the incoming text message without your application having to frequently poll for the incoming text message.
Note that the preference of polling for the messages or using a callback notification to receive messages must be decided during the time of associating a short code to your application. For a given short code, your application can employ only one mechanism and cannot switch back and forth on the preference for the same short code.
When I send a message, who does the end user see as the source of the message?
When you sign up for AT&T messaging, you will be provided the use of an AT&T short code. This typically eight-digit code will be the code that the end user sees as the originator of the message. This same code can be used by end users to reply or send messages to your application.
Does AT&T support delivery receipts?
Yes, AT&T supports delivery receipts. There are two ways of getting the delivery status of an SMS message:
- Polling mechanism—Where the developer application polls on a regular basis with the given message id, to check the status of the sent message.
- Callback Notification mechanism—Where the developer application registers an SMS Delivery status notification URI against a given short code in the MyApps page of the developer program website, and a near real-time notification is sent to the application listener from the AT&T API Platform when the message reaches its final state.
Is it possible to get a higher transaction rate for my app?
Will the end user (AT&T Wireless customer) who receives a message from my application and sends messages to my application be charged for sending and receiving these messages?
Normally, yes. Standard rates would apply. However, it depends on how billing is configured for the short code associated with your application. You can request that the short code associated with your app be set up as free to the customer (zero-rated), but it might require your organization to incur the cost. The details of this type of arrangement must be worked out with the AT&T Developer Program team.
Can I set up my application short code to be zero-rated (free) to the wireless customers who send and receive SMS messages to and from my application short code?
Yes. You can request the short code associated with your application to be set up as free to the customer (zero-rated), but it might require your organization to incur the cost. If this is something your organization is interested in, please contact us for more information on zero-rated short codes.
Can I associate a custom short code with my application instead of the default short code that is provided by the system?
Yes. You can submit a request to associate a custom short code with your application. In the case of 3, 4, 7, and 8 digit short codes, the AT&T short code management team checks to see whether the code is available so it can be used for your application. This process typically takes 1-2 weeks. If it is a 5 or 6 digit short code, you may have to lease it from http://www.usshortcodes.com and then place a request using the short code management functionality that is available in the MyApps page of the developer web portal interface.
How long will the delivery status of a previously sent SMS message be available for an application to query?
If the application is using the polling mechanism to obtain the status, the delivery status will be available until one of the conditions below is met:
- 30 minutes has elapsed after the message has reached its final state OR
- You have queried and retrieved the status once after the message has reached its final state
If the application is using the callback operation, by registering the listener endpoint to receive the status, the delivery status will be automatically delivered to the application. On getting an acknowledgment from your application server, the status is removed from the AT&T server.
Can I send messages to users on other carriers?
AT&T Messaging currently does not support sending messages to (or receiving messages from) other carriers customers and is limited to AT&T wireless customers using a wireless device/phone associated with their AT&T account. Messages sent to AT&T wireless customers who are roaming on other carriers' networks will generally be delivered. Delivery of any particular message will depend on factors such as the other carriers' network, support of messaging for roaming AT&T users, and support of the user's device/phone.
What happens when the phone is switched off when I send an SMS message?
The message is queued and retried for delivery in periodic intervals for up to 72 hours. Once the maximum period of 72 hours is reached, the message is expired and deleted from the retry queue. If the application has registered an SMS delivery notification callback URI, a final delivery notification status will be sent to that endpoint in near real time. The value of the delivery notification status will be “DeliveredToTerminal” if the message is successfully delivered to the handset and “DeliveryImpossible” if the message has expired after 72 hours without successful delivery to the handset.