AT&T Landline Texting API
Landline Texting API Authentication
If you have not done so already, you will need to buy AT&T Landline Texting to begin using the API. Please Contact your AT&T account manager to get started.
Next, you will need to authenticate with the AT&T Landline Texting API service. A representative will call you at the phone number you are text enabling to verify ownership of the number. After verification, an email is sent to you containing the session key for the account. If you already have an account but cannot obtain session keys, then contact att_asc_support@amcustomercare.att-mail.com for support.
When you set-up an account, you can then obtain one or more session keys, depending on how you plan to configure your sessions.
Input Parameters
The following tables include the input parameters for message/send, message/send to multiple recipients, and message/send a scheduled message.
AT&T Landline Texting API Input Parameters: Message/Send To Single Recipient
Parameter Name
Value
Type
Required
session
The GUID representation of a logged-in user.
String
True
contacts
The string representation of a phone number.
- US Domestic numbers are full, 10-digit numbers.
String
True
body
The message to be sent. The message body can be a maximum of 250 bytes.
String
True
Parameter Name
session
Value
The GUID representation of a logged-in user.
Type
String
Required
True
Parameter Name
contacts
Value
The string representation of a phone number.
- US Domestic numbers are full, 10-digit numbers.
Type
String
Required
True
Parameter Name
body
Value
The message to be sent. The message body can be a maximum of 250 bytes.
Type
String
Required
True
AT&T Landline Texting API Input Parameters: Message/Send To Multiple Recipients
Parameter Name
Value
Type
Required
session
The GUID representation of a logged-in user.
String
True
contacts
The string representation of a phone number.
- US Domestic numbers are full, 10-digit numbers.
- International numbers must be in E.164 format.
Note: You can have 15 individual contacts as parameters. For example:
String
True
body
The message to be sent. The message body can be a maximum of 250 bytes.
String
True
Parameter Name
session
Value
The GUID representation of a logged-in user.
Type
String
Required
True
Parameter Name
contacts
Value
The string representation of a phone number.
- US Domestic numbers are full, 10-digit numbers.
- International numbers must be in E.164 format.
Note: You can have 15 individual contacts as parameters. For example:
Type
String
Required
True
Parameter Name
body
Value
The message to be sent. The message body can be a maximum of 250 bytes.
Type
String
Required
True
AT&T Landline Texting API Input Parameters: Message/Send Scheduled
Parameter Name
Value
Type
Required
session
The GUID representation of a logged-in user.
String
True
contacts
The string representation of a phone number.
- US Domestic numbers are full, 10-digit numbers.
String
True
body
The message to be sent. The message body can be a maximum of 250 bytes.
String
True
scheduledDate
Time/Date of desired delivery; must be in milliseconds and converted to Pacific Time.
String
False
Parameter Name
session
Value
The GUID representation of a logged-in user.
Type
String
Required
True
Parameter Name
contacts
Value
The string representation of a phone number.
- US Domestic numbers are full, 10-digit numbers.
Type
String
Required
True
Parameter Name
body
Value
The message to be sent. The message body can be a maximum of 250 bytes.
Type
String
Required
True
Parameter Name
scheduledDate
Value
Time/Date of desired delivery; must be in milliseconds and converted to Pacific Time.
Type
String
Required
False
Output Parameters
This section includes output parameters for both message/send success and failure.
Message/send success response
{
"response" {
"fingerprint": "4233621183",
"root" "664880513175330816",
"tokens" [
{
"contact": 3460624702,
"device": 304397802,
"fingerprint": "4233621183",
"message": "664880513175330816"
}
]
},
"success": true
}
Technically, you can ignore the fingerprint and root elements of the response object. You can use the elements in the tokens array instead of the fingerprint and root elements. In all cases, there is a single token in the token array.
AT&T Landline Texting API Output Parameters: Message/Send Success
Parameter Name
Value
Type
Required
name
The ContactId of the message recipient.
String
True
device
UserId of the message sender.
String
True
fingerprint
Is the ConversationId, which is an ID assigned based off of recipients of the message.
String
True
message
The ID of the message that was just sent.
String
True
success
The success/failure of the web request.
String
True
Parameter Name
name
Value
The ContactId of the message recipient.
Type
String
Required
True
Parameter Name
device
Value
UserId of the message sender.
Type
String
Required
True
Parameter Name
fingerprint
Value
Is the ConversationId, which is an ID assigned based off of recipients of the message.
Type
String
Required
True
Parameter Name
message
Value
The ID of the message that was just sent.
Type
String
Required
True
Parameter Name
success
Value
The success/failure of the web request.
Type
String
Required
True
Message/send failure response
The following is an example of a failure response to a message/send:
{
"response": {
"code": -703,
"desc": "Bad arguments"
},
"success": false
}
AT&T Landline Texting API Output Parameters: Message/Send Failure
Parameter Name
Value
Type
Required
code
The AT&T Landline Texting error code.
String
True
desc
Description of the error.
String
True
success
The success/failure of the web request. True = success; False = failure.
String
False
Parameter Name
code
Value
The AT&T Landline Texting error code.
Type
String
Required
True
Parameter Name
desc
Value
Description of the error.
Type
String
Required
True
Parameter Name
success
Value
The success/failure of the web request. True = success; False = failure.
Type
String
Required
False
Message/send success response
The following is an example of a failure response to a message/send:
{
"response":
{
"id":664883126574915584,
"status":"queued"
},
"success": true
}
AT&T Landline Texting API Output Parameters: Message/Send Success
Parameter Name
Value
Type
Required
code
The AT&T Landline Texting error code.
String
True
status
The status of the message delivery.
String
True
success
The success/failure of the web request. True = success; False = failure.
String
True
Parameter Name
code
Value
The AT&T Landline Texting error code.
Type
String
Required
True
Parameter Name
status
Value
The status of the message delivery.
Type
String
Required
True
Parameter Name
success
Value
The success/failure of the web request. True = success; False = failure.
Type
String
Required
True
Message/send failure response
The following is an example of a failure response to a message/send:
"success":false,
"errorDesc": "Invalid recipients. Invalid phone numbers: +1206856.
Phone numbers should be in e164 format."
}
Parameter Name
Value
Type
Required
success
The success/failure of the web request. True = success; False = failure.
String
False
errorDesc
Description of the error that caused failure.
String
True
Parameter Name
success
Value
The success/failure of the web request. True = success; False = failure.
Type
String
Required
False
Parameter Name
device
Value
Description of the error that caused failure.
Type
String
Required
True
Failure Response: File too big
The following is an example of a message/send failure because the size of file being sent exceeds the maximum allowed:
<head><title>413 Request Entity Too Large</title></head>
<body bgcolor="white">
<center><h1>413 Request Entity Too Large</h1></center>
<hr><center>nginx</center>
</body>
</html>
Status Codes
AT&T Landline Texting uses status codes to indicate the success, failure, or progress of an event. The success codes are assigned when message delivery succeeds to both the recipient and database. Failure codes are assigned when the message cannot be sent because of an internal or external problem. Progress messages are assigned when the message is in-process or queued. If you use AT&T Landline Texting's API Web Hooks, then there are specific progress messages that give you the ability to track the message through each step of the delivery process.
Status Codes: Message Not Sent
If an error occurs when the text message is sent, then an error message appears. The current list of error codes is included in the table below.
Code
Description
State
Retry
-1234
Recipient sent STOP message
Resolution = Recipient must send UNSTOP message.
Failure
No
-855
Internal Error
Failure
Yes
-801
Spam Protection
Resolution = Contact to have spam flag removed.
Failure
No
-704
Internal Error
Failure
No
-700
Internal Error
Failure
No
-394
Invalid Parameter Length
Resolution = May no longer be valid. May be replaced by -703/Bad Argument, which is caused by incorrect/invalid input parameter.
Failure
No
-124
Unable to determine carrier
Failure
No
-1
Unknown Error
Unknown
Yes
Code
-1234
Description
Recipient sent STOP message
Resolution = Recipient must send UNSTOP message.
State
Failure
Retry
No
Code
-855
Description
Internal Error
State
Failure
Retry
Yes
Code
-801
Description
Spam Protection
Resolution = Contact to have spam flag removed.
State
Failure
Retry
No
Code
-704
Description
Internal Error
State
Failure
Retry
No
Code
-700
Description
Internal Error
State
Failure
Retry
No
Code
-394
Description
Invalid Parameter Length
Resolution = May no longer be valid. May be replaced by -703/Bad Argument, which is caused by incorrect/invalid input parameter.
State
Failure
Retry
No
Code
-124
Description
Unable to determine carrier
State
Failure
Retry
No
Code
-1
Description
Unknown Error
State
Unknown
Retry
Yes
Status Codes: Message Progress
When you use Web Hooks, the message-progress Status Codes give you the ability to track the progress of events as they occur. These specific codes are labeled as transient. Consequently, they are unlikely to be visible in any message/list API calls.
Code
Description
State
Retry
0
Delivered–No Confirmation
Success
Yes
1
In Progress
Transient
No
2
Queued
Transient
No
3
Queued
Transient
No
4
Delivery-Confirmed
Success
Yes
5
Error–Confirmed
Failure
Yes
6
Delivered–Confirmed by Delivery Receipt
Success
Yes
7
Error–Confirmed by Delivery Receipt
Failure
Yes
Code
0
Description
Delivered–No Confirmation
State
Success
Retry
Yes
Code
1
Description
In Progress
State
Transient
Retry
No
Code
2
Description
Queued
State
Transient
Retry
No
Code
3
Description
Queued
State
Transient
Retry
No
Code
4
Description
Delivery-Confirmed
State
Success
Retry
Yes
Code
5
Description
Error–Confirmed
State
Failure
Retry
Yes
Code
6
Description
Delivered–Confirmed by Delivery Receipt
State
Success
Retry
Yes
Code
7
Description
Error–Confirmed by Delivery Receipt
State
Failure
Retry
Yes
Send to One Individual Contact
The first and most basic scenario is sending a single text message to a single, individual contact. In this scenario, one unscheduled message is sent to one recipient. The recipient can be either an existing contact or a contact not yet included in the Contact List. The only requirement for the contact is that their telephone number must be valid and text-enabled.
$ curl https://api-landlinetexting.att.com/message/send \
-d session=3d0f1dde-aaff-4ce8-b61a-af212a860abc:123456789
-d --data-urlencode contacts='+18559479447'
-d --data-urlencode body='Hello World, from AT&T Landline Texting!'
{
"response"
"fingerprint": "4236521183",
"root": "327559093363723008",
"tokens": [
{
"contact" : 1989548603,
"device" : 309626613,
"fingerprint": "42336654183",
"message": "327545678963723008"
}
]
},
"success": true
}
Send to Multiple Individual Contacts
The second scenario is sending a single text message to multiple, individual contacts. In this scenario, one unscheduled message is sent to multiple contacts. However, the contacts/recipients are individuals and not a Contact Group.
$ curl -X POST https://api-landlinetexting.att.com/message/send
-d session=8762f385-22a0-4675-9aaf-949602f3edde:304397802
--data-urlencode contacts=‘+12068597896’
--data-urlencode contacts='+14257772300' -d body=asdf
{
"success": true,
"response": {
"fingerprint": "227798380".,
"root": "666345808406650880",
"tokens": [
{
"message": "666345808406650881",
"fingerprint": "4233621183",
"device": 304397802,
"contact": 3460624702
},
{
"message": "666345808406650882",
"fingerprint": "3235647327",
"device": 304397802,
"contact": 3461841602
}
]
Send a Scheduled Message
The third scenario is setting-up and sending a single, scheduled text message that is sent to an individual contact.
$ curl –X POST https://api-landlinetexting.att.com/message/send \
-d session=3d0f1dde-aaff-4ce8-b61a-af212a860abc:123456789
-d --data-urlencode contacts='+18559479447'
-d --data-urlencode body='Hello World, from AT&T Landline Texting!'
-d scheduledDate=14477075270000
{
"response" {
"fingerprint": "4236521183",
"root": "327559093363723008",
"tokens": [
{
"contact" : 1989548603,
"device" : 309626613,
"fingerprint": "42336654183",
"message": "327545678963723008"
}
]
},
"success": true
}
Receive a Text Message
AT&T Landline Texting uses Web Hooks to push state-changes to your account. Web Hooks allow Server-to-Server communication of new events, without the requirement of a persistent connection. Web Hooks give you the ability to receive and track real-time events within AT&T Landline Texting.
Retry Logic
AT&T Landline Texting uses Web Hooks to push state-changes to your account. Web Hooks allow Server-to-Server communication of new events, without the requirement of a persistent connection. Web Hooks give you the ability to receive and track real-time events within AT&T Landline Texting.
Single Message/Intermittent Message Delivery Failure
In the case of delivery failure for a single message or intermittent messages, AT&T Landline Texting defines the message delivery as failed when one of the following conditions is met:
- If you receive a status code that is a not a 200-level code, then message delivery has failed.
- If your server takes longer than seven (7) seconds to respond to a delivery, then message delivery has failed.
When message delivery fails, the message is sent to the retry queue. AT&T Landline Texting uses an exponential back-off algorithm with a ten (10) minute ceiling to try to resend the message. The first retry occurs when the message has been in the queue for ten (10) seconds. If message delivery does not succeed within the 10-minute ceiling, then AT&T Landline Texting can continue to retry delivery for a maximum of 72 hours.
All Message Delivery Failure
If all messages fail to be delivered for one (1) hour, then AT&T Landline Texting assumes that the host is down and stops trying to send messages. AT&T Landline Texting then waits ten (10) minutes and then tries to send a single, relevant message. If the single message is delivered successfully, then AT&T Landline Texting queues the backlog of unsent messages and starts sending. If the single message is not delivered successfully, then AT&T Landline Texting continues sending a single message every 10 minutes. AT&T Landline Texting can continue to retry delivery for a maximum of 72 hours.
Example Payload
POST /message/receive HTTP/1.1
Host: http://www.yoururl.com/api-landlinetexting.att.com/api/receive Content-Length: 581
Content-Type: application/json; charset=UTF-8
POST /message/receive HTTP/1.1
Host: http://www.yoururl.com/api-landlinetexting.att.com/api/receive Content-Length: 581
Content-Type: application/json; charset=UTF-8
{
"body":"Thanks for texting, this is an auto reply!",
"bodySize":42,
"visible":true,
"hasAttachment":false,
"dateRead":null,
"bcc":null,
"finalDestination":"4257772300",
"messageType":"MO",
"deleted":false,
"statusCode":4,
"id":634151298329219072,
"scheduledDate":null,
"fingerprint":"132131532",
"messageTransport":9,
"contactId":3382213402,
"address":"ptn:/4257772222",
"read:true"
"dateCreated":"2015-08-19T16:53:45-07:00",
"dateDeleted":null,
"dateDelivered":null,
"cc":null,
"finalSource":"4257772222",
"deviceId":299538202
}
Parameters
Parameter
Description
Required
session
Session is the response of user/login.
True
type
For now, the available options is 'message'
True
event
Events listed above. i.e. send, receive, etc.
True
url
The destination when the event fires.
True
method
HTTP Method used for Web Hook. i.e. POST, PUT, GET
False
Parameter
session
Description
Session is the response of user/login.
Required
True
Parameter
type
Description
For now, the available options is 'message'
Required
True
Parameter
event
Description
Events listed above. i.e. send, receive, etc.
Required
True
Parameter
url
Description
The destination when the event fires.
Required
True
Parameter
method
Description
HTTP Method used for Web Hook. i.e. POST, PUT, GET
Required
False
Parameters
Parameter
Description
Required
session
Session is the response of user/login.
True
webhookId
The Id of an installed Web Hook.
True
url
The destination when the event fires.
False
method
HTTP Method used for Web Hook. i.e. POST, PUT, GET
False
Parameter
session
Description
Session is the response of user/login.
Required
True
Parameter
webhookId
Description
The Id of an installed Web Hook.
Required
True
Parameter
url
Description
The destination when the event fires.
Required
False
Parameter
method
Description
HTTP Method used for Web Hook. i.e. POST, PUT, GET
Required
False
Parameters
Parameter
Description
Required
session
Session is the response of user/login.
True
webhookId
The Id of an installed Web Hook.
True
Parameter
session
Description
Session is the response of user/login.
Required
True
Parameter
webhookId
Description
The Id of an installed Web Hook.
Required
True
Single Host vs Multiple Hosts
The primary difference between single-host and multiple-host implementations is that multiple-host implementations require different send, receive, and retry queues. Specifically, there are different retry queues for each host. If there are two hosts and one host fails, then AT&T Landline Texting routes traffic to the operating host. After rerouting the traffic, AT&T Landline Texting continues to attempt to send messages to the failed host, using an exponential back-off logarithm similar to that described in the Retry Logic section.
MMS Implementation
The process AT&T Landline Texting uses for sending a text message with an image attached is designed to minimize the message payload until the image is actually sent. This means that the first message sent to the host doesn't include the image itself. Instead, it includes a value (true/false) that indicates that AT&T Landline Texting does, or does not, want to attach an image to a message.
MMS Retrieve Process
This section describes the steps necessary to retrieve MMS content from AT&T Landline Texting. When you look at the details of the message, you'll see that there is an Attachment field. This field is a boolean value. If this value is "true", then execute a message Attachment/list web call.
Parameter
Description
Type
Required
session
The GUID representation of a logged-in user.
String
True
messageId
A unique string used to identify a given message object.
String
True
Parameter
session
Description
The GUID representation of a logged-in user.
Type
String
Required
True
Parameter
messageId
Description
A unique string used to identify a given message object.
Type
String
Required
True
Example Response
The key data points are the storage key values. These values are used in the next web calls.
{
"total":2,
"response": [
{
"fileName":"IMG_1827.jpg",
"dateCreated":"2015-03-26T13:15:17-07:00",
"fileSizeBytes :40101,
"mimeType":"image/jpeg",
"storageKey":"be9396da-a6aa-442c-9406-asdfasdfasdf"
},
{
"fileName":"123_1.smil",
"dateCreated":"2015-03-26T13:15:17-07:00",
"fileSizeBytes":300,
"mimeType":"application/smil",
"storageKey":"269023ec-67a0-4481-a820-asdfasdfasdf"
}
],
}
AT&T Landline Texting API Parameters: MMS Retrieve Hosted Content
Parameter
Description
Type
Required
session
The GUID representation of a logged-in user.
String
True
storageKey
A unique string used to identify a given media file.
String
True
Parameter
session
Description
The GUID representation of a logged-in user.
Type
String
Required
True
Parameter
storageKey
Description
A unique string used to identify a given media file.
Type
String
Required
True
MMS Send
AT&T Landline Texting supports MMS on landline and toll free numbers. It is required at this time to have the feature enabled on the individual line.
Notes:
- There can be only one recipient of an MMS message.
- You can send only the following MIME types:
- image/bmp
- image/gif
- image/jpeg
- image/png
- text/plain
- The message body is limited to 700 bytes. Images greater than 700 bytes should be sent as an attachment.
- The maximum payload is 600kb. There is no transcoding functionality.
- A session is obtained from a user/login response. Sessions do not expire. They can be stored and used for all future requests.
Parameter
Description
Required
session
Session is the response of user/login.
True
to
The recipients phone number in E.164 format.
True
body
Text body of the message. Max 700 Bytes.
False
Parameter
session
Description
Session is the response of user/login.
Required
True
Parameter
to
Description
The recipients phone number in E.164 format.
Required
True
Parameter
body
Description
Text body of the message. Max 700 Bytes.
Required
False
Sorry! Your session has expired.