API Version
The SMS API requires free full access and special permission before it can be used. The API is intended for established businesses or organizations to send SMS Shortcode messages to AT&T subscribers within the United States.
Introduction
The SMS API sends SMS messages to one or more AT&T Wireless mobile devices and receives messages by polling or by enabling a listener. This API also enables apps to query the delivery status of SMS messages sent from an app.
Considerations
The RESTful SMS API provided by AT&T has the following considerations for you to keep in mind:
- The character set encoding is controlled by use of the Content-Encoding parameter.
- The supported character sets are GSM 7-bit, Latin1, and UCS2.
- Multiple byte character sets in message payloads are supported.
- Binary encoded content in an SMS message is not supported.
- Any SMS message that is longer than 4096 1-byte characters is rejected.
- SMS messages that originate from apps in the Production realm incur standard AT&T Messaging charges for the originating customer.
- SMS messages that originate from apps in the Sandbox realm are free-to-user SMS messages. This depends upon the way in which the short code billability is provisioned.
- The SMS API supports text messages to AT&T Wireless customers only.
- The SMS API does not support sending messages to users that are not on the AT&T Wireless network.
- The network retries deliveries to the mobile users for up to 72 hours; after which time any undeliverable messages are deleted from the network.
- The delivery of a SMS message is not guaranteed. Delivery depends on many factors such as the target device status. The delivery status of the message indicates the final status of the message.
- Sending SMS messages using map:group is not supported. However, multiple destination addresses may be included in a single Send SMS method request. The maximum number of destination addresses that are supported in a single message is 50.
- The messages sent from an AT&T Wireless customer to the short code for your app account are obtained by the app either polling for it using a method request or by registering a listener endpoint URI where the API gateway will send a notification using a callback method request. For a given short code only one mechanism would be supported and so the choice has to be indicated by the developer while requesting a short code to be associated with the app.
- You must ensure that your app meets the Telephone Consumer Protection Act (TCPA), CAN SPAM Act standards, and any other appropriate laws and regulations.
- The API Gateway supports two providers for the Send SMS method; the AT&T RESTful API provider and the GSMA OneAPI provider. If more than one short code is associated with your app account and if you plan to originate SMS messages from more than one of the short codes, then consider using the GSMA OneAPI provider for this method. The GSMA OneAPI provider enables you to specify a short code as a parameter in the URI to indicate the originating sender address for the SMS message.
Provisioning
The RESTful SMS API provided by AT&T requires that you provision your app as follows.
You must register the SMS API for your app account on the AT&T Developer Program web site in order to utilize this API.
When you request a short code to be associated with your app, you should specify the following properties.
- Type of short code: Default Provided or Custom
- Reception of Mobile Originated (MO) messages: Online via callback or Offline via polling
- Message rating: Free to user or Standard rated
OAuth
All APIs provided by AT&T use the OAuth 2.0 framework. All API requests sent to the API Gateway must include an OAuth access token.
You may authorize access for this API by using the following scope.
"SMS" for the Get SMS method, the Get SMS Delivery Status method, the Receive SMS callback, and the Send SMS method. To obtain an OAuth access token, use the App Key and App Secret from the My Apps section after registering and signing into your API Platform account. To obtain your OAuth access token run the following command from the Command Line Interface window and replace "{{APP_KEY}}", "{{APP_SECRET}}", and "{{API_SCOPES}}" with the App Key, App Secret, and the API scopes that are specified in your app account.
Get Access Token method using the cURL command:
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}}"
A successful response from the API Gateway contains an OAuth access token, the expiration period, and an OAuth refresh token as displayed in the following example.
Response from the API Gateway for the Get Access Token method:
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Date: {{DATE_AND_TIME_STAMP}}
{
"access_token":"{{OAUTH_ACCESS_TOKEN}}",
"token_type": "bearer",
"expires_in":{{EXPIRATION_PERIOD}},
"refresh_token":"{{REFRESH_TOKEN}}"
}
Extract the value from "{{OAUTH_ACCESS_TOKEN}}" to use in the Authorization parameter for requests to the API Gateway. When sending a request to the API Gateway a successfully constructed Authorization parameter looks like the following.
Authorization parameter for the HTTP header:
Authorization: Bearer {{OAUTH_ACCESS_TOKEN}}
For more information about the OAuth refresh token, other authentication options, and revoking tokens; see the OAuth 2.0 API v4.
AT&T
Overview
The Get SMS method receives SMS messages via the polling mechanism.
Your app must have an offline short code in order to utilize this method.
The messages are sent to an app from the user's mobile device to an offline short code associated with the app on the AT&T mobile network.
Upon retrieval of a message, the message is removed from the server.
Only the SMS messages received since the last time that this method was run are available to be retrieved.
If the quantity of messages to be retrieved from the server is larger than the number of messages that is able to be retrieved in a single response, then the requesting app must run multiple method requests to retrieve the complete list of the messages.
This method must be requested at least once every thirty minutes.
The SMS messages are automatically removed from the server after every 30 minutes if this method is not run.
For apps that expect to receive a large number of SMS messages, it is recommended that the app run this method frequently with a maximum frequency of once every 5 minutes.
Add one or more offline short codes as follows.
- 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.
- Click on the Add Short Code link and click the Save button without adding any URI information.
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 in your app account.
Note: 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 the method is run.
OAuth Scope
Scope: SMS
Model: client_credentials
Resource
GET https://api.att.com/rest/sms/2/messaging/inbox
Request Examples
JSON
Request
GET https://api.att.com/rest/sms/2/messaging/inbox?RegistrationID=22627000 Authorization: Bearer xyz123456789 Accept: application/json
Response
COPY
{
"InboundSmsMessageList": {
"InboundSmsMessage": [
{
"MessageId": "msg0",
"Message": "Hello",
"SenderAddress": "tel:4257850159"
}
],
"NumberOfMessagesInThisBatch": "1",
"ResourceUrl": "http://api.att.com/rest/sms/2/messaging/inbox",
"TotalNumberOfPendingMessages": "0"
}
}
Request Parameters
★Required Parameters
Parameter
Accept
String
Header
Specifies the format of the body for the response.
The acceptable values for this parameter are:
- application/json
- application/xml
The default value is application/json.
Note: For this method, this parameter specifies how the entity should be represented in case of an error.
This parameter is for setting the format of an error message.
If there is no error, then the representation will match the form of the actual content.
Authorization ★
String
Header
Specifies the authorization.
The acceptable format for this parameter is the word "Bearer" followed by a space ( ) and an OAuth access token.
If this parameter value is missing from the header, then the API Gateway returns a message with an HTTP Status Code of 400 Invalid Request.
If the OAuth access token is not valid, then the API Gateway returns an HTTP Status Code of 401 Unauthorized with a WWW-Authenticate HTTP header.
Content-Type ★
String
Header
Specifies the representation format of the request.
The acceptable values for this parameter are:
- application/json
- application/xml
- application/x-www-form-urlencoded
RegistrationID ★
String
Query Parameter
Specifies the identifier (ID) of the app account.
Note: This parameter value is a short code that is obtained from your app account on the AT&T Developer Program website.
Response Parameters
★Required Parameters
Parameter
InboundSmsMessageList ★
InboundSmsMessageListObject
Body
Contains the information for one or more SMS messages.
This parameter contains the following child parameters:
- InboundSmsMessage
- NumberOfMessagesInThisBatch
- ResourceUrl
- TotalNumberOfPendingMessages
GSMA OneAPI
Overview
The Get SMS method receives SMS messages via the polling mechanism.
Your app must have an offline short code in order to utilize this method.
The messages are sent to an app from the user's mobile device to an offline short code associated with the app on the AT&T Network.
Upon retrieval of a message, the message is removed from the server.
Only the SMS messages received since the last time that this method was run are available to be retrieved.
If the quantity of messages to be retrieved from the server is larger than the number of messages that can potentially be retrieved in a single response, then the requesting app must run multiple method requests to retrieve the complete list of the messages.
This method must be requested at least once every thirty minutes.
The SMS messages are automatically removed from the server after every 30 minutes if this method is not run.
For apps that expect to receive a large number of SMS messages, it is recommended that the app run this method frequently with a maximum frequency of once every 5 minutes.
Add one or more offline short codes as follows.
- 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.
- Click on the Add Short Code link and click the Save button without adding any URI information.
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 in your app account.
Note: 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 the method is run.
OAuth Scope
Scope: SMS
Model: client_credentials
Resource
GET https://api.att.com/2/messaging/inbox/smsmessaging/inbound/registrations/{{registrationId}}/messages
Request Examples
XML
Request
GET https://api.att.com/2/smsmessaging/inbound/registrations/22627000/messages Authorization: Bearer xyz123456789 Accept: application/json
Response
<inboundSMSMessageList> <inboundSMSMessage> <messageId>msg0</messageId> <message>Hello</message> <senderAddress>tel:4257850159</senderAddress> </inboundSMSMessage> <numberOfMessagesInThisBatch>1</numberOfMessagesInThisBatch> <resourceURL> http://api.att.com/2/smsmessaging/inbound/registrations/22627012/messages </resourceURL> <totalNumberOfPendingMessages>0</totalNumberOfPendingMessages> </inboundSMSMessageList>
Request Parameters
★Required Parameters
Parameter
Accept
String
Header
Specifies the format of the body for the response.
The acceptable values for this parameter are:
- application/json
- application/xml
The default value is application/json.
Note: For this method, this parameter specifies how the entity should be represented in case of an error.
This parameter is for setting the format of an error message.
If there is no error, then the representation will match the form of the actual content.
Authorization ★
String
Header
Specifies the authorization.
The acceptable format for this parameter is the word "Bearer" followed by a space ( ) and an OAuth access token.
If this parameter value is missing from the header, then the API Gateway returns a message with an HTTP Status Code of 400 Invalid Request.
If the OAuth access token is not valid, then the API Gateway returns an HTTP Status Code of 401 Unauthorized with a WWW-Authenticate HTTP header.
Content-Type ★
String
Header
Specifies the representation format of the request.
The acceptable values for this parameter are:
- application/json
- application/xml
- application/x-www-form-urlencoded
RegistrationID ★
String
Query Parameter
Specifies the identifier (ID) of the app account.
Note: This parameter value is a short code that is obtained from your app account on the AT&T Developer Program website.
Response Parameters
★Required Parameters
Parameter
InboundSmsMessageList ★
InboundSmsMessageListObject
Body
Contains the information for one or more SMS messages.
This parameter contains the following child parameters:
- InboundSmsMessage
- NumberOfMessagesInThisBatch
- ResourceUrl
- TotalNumberOfPendingMessages
AT&T
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 allows 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.
OAuth Scope
Scope: SMS
Model: client_credentials
Resource
GET https://api.att.com/rest/sms/2/messaging/outbox/{{Id}
Request Examples
JSON
Request
GET https://api.att.com/rest/sms/2/messaging/outbox/SMSa9b1927803784049 Authorization: Bearer xyz123456789 Accept: application/json
Response
{
"DeliveryInfoList": {
"DeliveryInfo": [
{
"Id": "msg0",
"Address": "3500000992",
"DeliveryStatus": "DeliveredToTerminal"
}
],
"ResourceUrl": "https://api.att.com/rest/sms/2/messaging/outbox/SMSa9b192780378404c"
}
}
Request Parameters
★Required Parameters
Parameter
Accept
String
Header
Specifies the format of the body for the response.
The acceptable values for this parameter are:
- application/json
- application/xml
The default value is application/json.
Note: For this method, this parameter specifies how the entity should be represented in case of an error.
This parameter is for setting the format of an error message.
If there is no error, then the representation will match the form of the actual content.
Authorization ★
String
Header
Specifies the authorization.
The acceptable format for this parameter is the word "Bearer" followed by a space ( ) and an OAuth access token.
If this parameter value is missing from the header, then the API Gateway returns a message with an HTTP Status Code of 400 Invalid Request.
If the OAuth access token is not valid, then the API Gateway returns an HTTP Status Code of 401 Unauthorized with a WWW-Authenticate HTTP header.
Content-Type ★
String
Header
Specifies the representation format of the request.
The acceptable values for this parameter are:
- application/json
- application/xml
- application/x-www-form-urlencoded
Id ★
String
URI Path
Specifies the unique message identifier (ID) that is returned by the API Gateway as part of the Send SMS method response.
Response Parameters
★Required Parameters
Parameter
DeliveryInfoList ★
Delivery Info List Object
Body
Contains the body of the response.
This parameter contains the following child parameters:
- DeliveryInfo
- ResourceUrl
GSMA OneAPI
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 allows 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.
OAuth Scope
Scope: SMS
Model: client_credentials
Resource
GET https://api.att.com/rest/sms/2/messaging/outbox/{{Id}
Request Examples
JSON
Request
GET https://api.att.com/rest/sms/2/messaging/outbox/SMSa9b1927803784049 Authorization: Bearer xyz123456789 Accept: application/json
Response
{
"DeliveryInfoList": {
"DeliveryInfo": [
{
"Id": "msg0",
"Address": "3500000992",
"DeliveryStatus": "DeliveredToTerminal"
}
],
"ResourceUrl": "https://api.att.com/rest/sms/2/messaging/outbox/SMSa9b192780378404c"
}
}
Request Parameters
★Required Parameters
Parameter
Accept
String
Header
Specifies the format of the body for the response.
The acceptable values for this parameter are:
- application/json
- application/xml
The default value is application/json.
Note: For this method, this parameter specifies how the entity should be represented in case of an error.
This parameter is for setting the format of an error message.
If there is no error, then the representation will match the form of the actual content.
Authorization ★
String
Header
Specifies the authorization.
The acceptable format for this parameter is the word "Bearer" followed by a space ( ) and an OAuth access token.
If this parameter value is missing from the header, then the API Gateway returns a message with an HTTP Status Code of 400 Invalid Request.
If the OAuth access token is not valid, then the API Gateway returns an HTTP Status Code of 401 Unauthorized with a WWW-Authenticate HTTP header.
Content-Type ★
String
Header
Specifies the representation format of the request.
The acceptable values for this parameter are:
- application/json
- application/xml
- application/x-www-form-urlencoded
requestId ★
String
URI Path
Specifies the SMS Request identifier (ID) that is returned as part of the Send SMS method response message.
SenderAddress ★
String
URI Path
Specifies the AT&T mobile destination number of the response message.
Note: This parameter is always the short code assigned to your app account or the user's mobile number (user-agent) identifying the sender of the message.
Note: This parameter is assigned automatically by AT&T to the short code for your app account.
Note: Assigning to mobile address is not supported.
Response Parameters
★Required Parameters
Parameter
DeliveryInfoList ★
Delivery Info List Object
Body
Contains the body of the response.
This parameter contains the following child parameters:
- DeliveryInfo
- ResourceUrl
Overview
The Get SMS Delivery Status method requests the status of a previous SMS delivery request that was accepted by the AT&T Wireless network for delivery to a mobile device.
The Id parameter value, which is returned in the response to the corresponding Send SMS method, must be provided in this method request.
A final state is reached when the DeliveryStatus parameter is set to either DeliveredToTerminal or DeliveryImpossible.
Refer to the response parameters for more information about the DeliveryStatus parameter value.
For the 30 minute period following the setting of the final value for the DeliveryInfo parameter, you may successfully request only one delivery status query.
After the 30 minute period, the contents of the DeliveryInfo parameter may not be available for a query request.
OAuth Scope
Scope: SMS
Model: client_credentials
Resource
GET https://api.att.com/2/smsmessaging/outbound/requests/{{senderAddress}}/{{requestId}}/deliveryInfos
Request Examples
JSON
Request
GET https://api.att.com/2/smsmessaging/outbound/12345678/SMSa9b1927803784049/deliveryInfos Authorization: Bearer xyz123456789 Accept: appication/json
Response
{
"deliveryInfoList": {
"deliveryInfo": [
{
"address": "tel:+13500000992",
"deliveryStatus": "DeliveredToTerminal"
}
],
"resourceURL": "https://api.att.com/2/smsmessaging/outbound/requests/22888026/SMSa9b1927803784049/deliveryInfos"
}
}
Receive SMS
AT&T
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.
OAuth Scope
Scope: SMS
Model: Not Applicable
Resource
POST {{your_notification_callback_uri}
Notification Examples
JSON
Notification
{
"DateTime": "04-15-2011T12:00:00",
"MessageId": "",
"Message": "Hello world",
"SenderAddress": "tel:+12071111111",
"DestinationAddress": "52345678"
}
Notification Parameters
★Required Parameters
Parameter
DateTime ★
String
Body
Specifies the time and date on which the message is received.
Example: "DateTime":"04-15-2011T12:00:00"
DestinationAddress ★
String
Body
Specifies the short code to which the message is destined.
Message ★
String
Body
Specifies the text of the message sent.
Note: The maximum acceptable length for this parameter is 4096 1-byte characters.
MessageId ★
String
Body
Specifies the unique identifier for the message that is returned by the API Gateway.
Note: For this release, this parameter is empty.
SenderAddress ★
String
Body
Specifies the mobile device number of the sender or customer.
The acceptable format for this parameter is the term tel followed by a URL encoded colon character ( %3A ) followed by a URL encoded plus sign character ( %2B ) followed by the URL encoded country code and AT&T mobile number
Example: "SenderAddress":"tel%3A%2B16309700001"
Quickstart
cURL
#Get Access Token via OAuth. #Replace {{CLIENT_ID}} and {{CLIENT_SECRET}} with your key and secret. curl "https://api.att.com/oauth/v4/token" \ --header "Content-Type: application/x-www-form-urlencoded" \ --header "Accept: application/json" \ --data "client_id={{CLIENT_ID}}&client_secret={{CLIENT_SECRET}}&scope=SMS&grant_type=client_credentials" \ --request POST #Refresh an Access Token. #Replace {{REFRESH_TOKEN}} with the refresh token from OAuth. curl "https://api.att.com/oauth/v4/token" \ --header "Content-Type: application/x-www-form-urlencoded" \ --header "Accept: application/json" \ --data "client_id={{CLIENT_ID}}&client_secret={{CLIENT_SECRET}}&scope=SMS&grant_type=client_credentials&refresh_token={{REFRESH_TOKEN}}" \ --request POST #Send a Message #Replace {{ACCESS_TOKEN}} with your access token. curl "https://api.att.com/rest/sms/2/messaging/outbox" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer {{ACCESS_TOKEN}}" \ --header "Accept: application/json" \ --data $'{"Message":"SMS Message Text","Address":["tel:1234567890","tel:1234567890"]}' \ --request POST
Java
package com.att.example; // Import the relevant code kit parts import com.att.api.sms.service.SMSService; import com.att.api.oauth.OAuthService; import com.att.api.oauth.OAuthToken; import com.att.api.rest.RESTException; public class App { private static void setProxySettings() { // set any proxy settings //RESTConfig.setDefaultProxy("proxy.host", 8080); } public static void main(String[] args) { try { setProxySettings(); // Use the app settings from developer.att.com for the following // values. Make sure SMS is enabled for the app key/secret. final String fqdn = "https://api.att.com"; // Enter the value from 'App Key' field final String clientId = "ENTER VALUE!"; // Enter the value from 'Secret' field final String clientSecret = "ENTER VALUE!"; // Create service for requesting an OAuth token OAuthService osrvc = new OAuthService(fqdn, clientId, clientSecret); // Get OAuth token using the SMS scope OAuthToken token = osrvc.getToken("SMS"); // Create service for interacting with the SMS api SMSService smsSrvc = new SMSService(fqdn, token); // Phone number final String pn = "5555555555"; // Message final String msg = "msg"; smsSrvc.sendSMS(pn, msg, false); } catch (RESTException re) { // handle exceptions here re.printStackTrace(); } finally { // perform any clean up here } } }
PHP
<?php // make sure this index.php file is in the same directory as the 'lib' folder. require_once __DIR__ . '/lib/OAuth/OAuthTokenService.php'; require_once __DIR__ . '/lib/SMS/SMSService.php'; // use any namespaced classes use Att\Api\OAuth\OAuthTokenService; use Att\Api\SMS\SMSService; // Use the app settings from developer.att.com for the following values. // Make sure SMS is enabled the app key/secret. // Enter the value from 'App Key' field $clientId = 'ENTER VALUE!'; // Enter the value from 'Secret' field $clientSecret = 'ENTER VALUE!'; // Enter phone number that SMS will be sent to // For example: $number = '5555555555'; $number = 'ENTER VALUE!'; // Create service for requesting an OAuth token $osrvc = new OAuthTokenService('https://api.att.com', $clientId, $clientSecret); // Get OAuth token using the SMS scope $token = $osrvc->getToken('SMS'); // Create service for interacting with the SMS api $smsSrvc = new SMSService('https://api.att.com', $token); // Send a SMS with the message 'Test Message' to $number and don't receive // status notification $response = $smsSrvc->sendSMS($number, 'Test Message', false); ?> <!DOCTYPE html> <html> <head> <title>AT&T SMS Example</title> </head> <body> <?php var_dump($response); ?> </body> </html>
Ruby
#!/usr/bin/env ruby # Make sure the att-codekit has been installed then require the class require 'att/codekit' # Include the name spaces to reduce the code required (Optional) include Att::Codekit # Uncomment to set a proxy if required # Transport.proxy("http:/proxyaddress.com:port") # Use the app settings from developer.att.com for the following values. # Make sure SMS is enabled for the app key/secret. # Enter the value from 'App Key' field client_id = 'ENTER VALUE!' # Enter the value from 'Secret' field client_secret = 'ENTER VALUE!' # Set the fqdn to default of https://api.att.com fqdn = 'https://api.att.com' # Create service for requesting an OAuth token clientcred = Auth::ClientCred.new(fqdn, client_id, client_secret) # Get OAuth token using the SMS scope token = clientcred.createToken('SMS') # Create service for interacting with the SMS api sms = Service::SMSService.new(fqdn, token) # Setup the addresses that we want to send addresses = "555-555-5555,444-555-5555" # Alternatively we can use an array # addresses = [5555555555,"444-555-5555"] # Use exception handling to see if anything went wrong with the request begin # Send a message to the addresses specified response = sms.sendSms(addresses, "Message from att's codekit sms example") status = sms.smsStatus(response.id) rescue Service::ServiceException => e # There was an error in execution print what happened puts "There was an error, the api returned the following error code:" puts "#{e.message}" else puts "Sent SMS with id: #{response.id}" puts "#{response.id} has the resource url: #{response.resource_url}" puts "" puts "Status response:" puts "\tResource URL: #{status.resource_url}" puts "\tDelivery Info:" status.delivery_info.each do |info| puts "\t\t------------------------" puts "\t\tMessage ID: #{info.id}" puts "\t\tAddress: #{info.address}" puts "\t\tStatus: #{info.status}" puts "\t\t------------------------" end end
CSharp
//List of using alias to make it easier to qualify an identifier to a namespace or type using System; using System.Collections.Generic; using System.Collections.Specialized; using System.IO; using System.Net; using System.Net.Security; using System.Security.Cryptography.X509Certificates; using System.Text; using System.Web; using System.Web.Script.Serialization; /* * PREREQUISITE: Use .Net C# Web Site Project. * An ASP.NET page is typically divided into two files: * A markup file with a .aspx extension * A code file, with a .aspx.cs extension * This code defines a partial class named SMS (Class name * can be replaced with the name of the page happens to be for you). * For more information about OAuth or SMS Service parameters, refer to online * documentation at https://developer.att.com. */ public partial class SMS : System.Web.UI.Page { string apiResponseString = string.Empty; //successful response of api request string apiErrorResponse = string.Empty; //error response of api request /* The Page_Load event is triggered when a page loads, and ASP.NET will * automatically call the subroutine Page_Load, and execute the code * inside it. */ protected void Page_Load(object sender, EventArgs e) { /*If the application is deployed behind the proxy, add the value * of the proxy IP and Port, otherwise leave it as it is. */ string proxyIp = ""; int proxyPort = 0; //BypassCertificateError(); //Uncomment to ignore one way ssl handshake errors. // Get Access Token Start string oAuthEndPoint = "https://api.att.com/oauth/v4/token"; string oAuthHTTPVerb = "POST"; string oAuthAccept = "application/json"; string oAuthContentType = "application/x-www-form-urlencoded"; string oAuthclient_id = ""; //Update with registered SMS Service Application Id/Key. string oAuthclient_secret = ""; //Update with registered SMS Service Secret Key/Id. string oAuthScope = "SMS"; string oAuthBody = "client_id=" + HttpUtility.UrlEncode(oAuthclient_id).ToString() + "&client_secret=" + HttpUtility.UrlEncode(oAuthclient_secret).ToString() + "&grant_type=" + HttpUtility.UrlEncode("client_credentials").ToString() + "&scope=" + HttpUtility.UrlEncode(oAuthScope).ToString(); // Send web request and handle web response HttpWebRequest webRequest = null; HttpWebResponse webResponse = null; GetAccessTokenResponse getAccessTokenResponse = null; try { webRequest = (HttpWebRequest)System.Net.WebRequest.Create(oAuthEndPoint); if (!string.IsNullOrEmpty(proxyIp)) { webRequest.Proxy = new WebProxy(proxyIp, proxyPort); } webRequest.ContentType = oAuthContentType; webRequest.Accept = oAuthAccept; webRequest.Method = oAuthHTTPVerb; byte[] postBytes = null; if (!string.IsNullOrEmpty(oAuthBody)) { UTF8Encoding encoding = new UTF8Encoding(); postBytes = encoding.GetBytes(oAuthBody); } if (postBytes != null) { webRequest.KeepAlive = true; webRequest.ContentLength = postBytes.Length; Stream postStream = webRequest.GetRequestStream(); postStream.Write(postBytes, 0, postBytes.Length); postStream.Close(); } webResponse = (HttpWebResponse)webRequest.GetResponse(); using (StreamReader sr2 = new StreamReader(webResponse.GetResponseStream())) { apiResponseString = sr2.ReadToEnd(); getAccessTokenResponse = new GetAccessTokenResponse(); JavaScriptSerializer deserializeJsonObject = new JavaScriptSerializer(); getAccessTokenResponse = (GetAccessTokenResponse)deserializeJsonObject.Deserialize(apiResponseString, typeof(GetAccessTokenResponse)); sr2.Close(); } webRequest = null; webResponse.Close(); // Get Access Token End // Send SMS Start string smsServiceEndPoint = "https://api.att.com/sms/v3/messaging/outbox"; string smsServiceHTTPVerb = "POST"; string smsServiceAccept = "application/json"; string smsServiceContentType = "application/json"; string smsServiceAuthorization = getAccessTokenResponse.access_token; NameValueCollection headers = new NameValueCollection(); headers.Add("Authorization", "Bearer " + smsServiceAuthorization); OutboundSMSRequestRootObject outboundSMSRequest = new OutboundSMSRequestRootObject(); outboundSMSRequest.outboundSMSRequest = new OutboundSMSRequest(); outboundSMSRequest.outboundSMSRequest.address = new List<string>(); outboundSMSRequest.outboundSMSRequest.address.Add("tel:+1<Number>"); //Update with AT&T MSISDN, as tel:+1<10 digit number> outboundSMSRequest.outboundSMSRequest.address.Add("tel:+1<Number>"); //Update with AT&T MSISDN, as tel:+1<10 digit number> outboundSMSRequest.outboundSMSRequest.message = "Startup Guide"; outboundSMSRequest.outboundSMSRequest.notifyDeliveryStatus = false; JavaScriptSerializer javaScriptSerializer = new JavaScriptSerializer(); string outBoundSmsJson = javaScriptSerializer.Serialize(outboundSMSRequest); OutboundSMSResponseRootObject sendsmsresponse = null; webRequest = (HttpWebRequest)System.Net.WebRequest.Create(smsServiceEndPoint); if (!string.IsNullOrEmpty(proxyIp)) { webRequest.Proxy = new WebProxy(proxyIp, proxyPort); } webRequest.ContentType = smsServiceContentType; webRequest.Accept = smsServiceAccept; webRequest.Method = smsServiceHTTPVerb; webRequest.Headers.Add(headers); postBytes = null; if (!string.IsNullOrEmpty(outBoundSmsJson)) { UTF8Encoding encoding = new UTF8Encoding(); postBytes = encoding.GetBytes(outBoundSmsJson); } if (postBytes != null) { webRequest.KeepAlive = true; webRequest.ContentLength = postBytes.Length; Stream postStream = webRequest.GetRequestStream(); postStream.Write(postBytes, 0, postBytes.Length); postStream.Close(); } webResponse = (HttpWebResponse)webRequest.GetResponse(); using (StreamReader sr2 = new StreamReader(webResponse.GetResponseStream())) { apiResponseString = sr2.ReadToEnd(); sendsmsresponse = new OutboundSMSResponseRootObject(); JavaScriptSerializer deserializeJsonObject = new JavaScriptSerializer(); sendsmsresponse = (OutboundSMSResponseRootObject)deserializeJsonObject.Deserialize(apiResponseString, typeof(OutboundSMSResponseRootObject)); sr2.Close(); } // Send SMS End } catch (WebException ex) { try { if (null != ex.Response) { using (StreamReader sr2 = new StreamReader(ex.Response.GetResponseStream())) { apiErrorResponse = sr2.ReadToEnd(); sr2.Close(); } } } catch { apiErrorResponse = "Unable to get response"; } } catch (Exception ex) { apiErrorResponse = ex.ToString(); } finally { webRequest = null; if (webResponse != null) webResponse.Close(); webResponse = null; } } #region IgnoreSSLHandshakeError private static void BypassCertificateError() { ServicePointManager.ServerCertificateValidationCallback += delegate(Object sender1, X509Certificate certificate, X509Chain chain, SslPolicyErrors sslPolicyErrors) { return true; }; } #endregion #region SMSServiceDataStructures // SMS Service Classes. ///<summary> ///Class to hold ResourceReference ///</summary> public class ResourceReference { ///<summary> ///Gets or sets resourceURL ///</summary> public string resourceURL { get; set; } } public class OutboundSMSResponseRootObject { public OutBoundSMSResponse outBoundSMSResponse; } // <summary> /// Class to hold send sms response /// </summary> public class OutBoundSMSResponse { // <summary> /// Gets or sets messageId /// </summary> public string messageId { get; set; } // <summary> /// Gets or sets ResourceReference /// </summary> public ResourceReference resourceReference { get; set; } } public class OutboundSMSRequest { public List<string> address { get; set; } public string message { get; set; } public bool notifyDeliveryStatus { get; set; } } public class OutboundSMSRequestRootObject { public OutboundSMSRequest outboundSMSRequest { get; set; } } #endregion #region OAuthServiceDataStructures // OAuth Service Class class GetAccessTokenResponse { public string access_token { get; set; } public int expires_in { get; set; } public string refresh_token { get; set; } public string token_type { get; set; } } #endregion }
Delivery Info Object Parameters
★Required Parameters
Parameter
Address ★
String
Body
Specifies the mobile number of the receiver.
DeliveryStatus ★
String
Body
Specifies the status of the SMS message that is delivered.
The acceptable values for this parameter are:
- DeliveredToNetwork : The message is delivered to the network, but not yet delivered to the user's mobile device.
- DeliveredToTerminal : The message is successfully delivered to the user's mobile device.
- DeliveryImpossible : The message is not successful delivered, such as when the message is not delivered before it expires.
Id ★
String
Body
Specifies the unique identifier (ID) for the message destination.
Note: If an SMS message is sent to more than one destination address, then a unique ID is returned for each of those addresses.
Note: This parameter value allows you to query the delivery status for each of the destination addresses.
Note: This parameter is only present when the AT&T URI is used by the app.
Delivery Info List Object Parameters
★Required Parameters
Parameter
DeliveryInfo ★
Delivery Info Object
Body
Contains the delivery information for the response.
This parameter contains the following child parameters:
- Id: Used for only the Get SMS Delivery Status method.
- Address
- DeliveryStatus
ResourceUrl ★
String
Body
Specifies the URI being used to provide network delivery status of the sent message.
Inbound SMS Message Object Parameters
★Required Parameters
Parameter
Message ★
String
Body
Specifies the text of the message being sent.
Note: The maximum acceptable length for this parameter is 4096 1-byte characters.
MessageId ★
String
Body
Specifies the message identifier (ID) that is unique for every message returned in the list.
SenderAddress ★
String
Body
Specifies the mobile number of the sender.
Inbound SMS Message List Object Parameters
★Required Parameters
Parameter
InboundSmsMessage ★
Inbound SMS Message Object
Body
Contains the body of an inbound response.
This parameter contains the following child parameters:
NumberOfMessagesInThisBatch ★
String
Body
Specifies the number of messages sent in the batch response.
ResourceUrl ★
String
Body
Specifies the endpoint URI that serves this request.
TotalNumberOfPendingMessages ★
String
Body
Specifies the total number of messages pending that have not been retrieved from the server for the specific RegistrationId parameter value or short code.
Note: This parameter is based on a combination of size, the number of messages, and the maximum response size for the method request.
Note: The API Gateway may return messages in batches.
Note: If the messages are returned in batch mode due to a size limitation, then this parameter contains the remaining number of messages that are waiting to be retrieved from the server for the given short code.
Note: If this parameter value is greater than zero (0), then not all of the messages for a particular short code were returned in the response.
Note: In order to retrieve the messages that remain on the server, the app must make another request to retrieve the remaining messages.
Note: If this parameter value is zero (0) or empty, then there are no pending messages for the app to retrieve at this time.
Resource Reference Object Parameters
★Required Parameters
Parameter
ResourceUrl ★
String
Body
Specifies the URI that provides network delivery status of the sent message.
14100000
Session Expired
Sorry! Your session has expired.