TOP

Use the dropdown to get support, or purchase this product

Related Content

No related content found

AT&T Message Archiving Interface Setup Guide

1. Introduction
This document helps AT&T Message Archiving customers set up the interface between AT&T Message Archiving service and the customer’s server, to support transferring their employees’ messages from AT&T to the customer’s server.

2. Setup Instructions

Customers will need to perform the following steps:
Set up a server to capture and store employees’ incoming and outgoing messages from AT&T.
Provide AT&T with the following information regarding this server:
1. URL to this server that uses a DNS registered FQDN including the port.
2. If basic HTTP authentication if implemented, need to provide a valid username and password.
Develop the Message Archiving API, including the test connection option.
With the help of the onboarding team, test the connection between the AT&T Message Archiving service and the customer’s server.

3. Technical API Details

3.1 API Description

3.1.1 General

The API is RESTful synchronous API.
The API pushes messages to customers’ server URL.
Customer will provide a URL that uses a DNS registered FQDN.
Pushed messages include SMS or MMS messages, including attachments. For MMS, the archived messages will be split into a text portion and an attachment portion.

3.1.2 Security/Authentication

- Messages are pushed to Customer’s server URL via HTTP POST over SSL/TLS.
- The customer’s server should support standard HTTP over SSL/TLS on port 443 using a standard (e.g., Verisign) certificate.
- Self-sign certificates are not supported.
  - The TLS version is determined during the SSL negotiation between client and server, and the version that is supported by both sides is selected.
  - The transport version will be determined based on the TLS support of the customer’s server. If the customer’s server supports TLS1.2, then the transport will be TLS1.2; if the customer’s server supports lower version, then this version will be used.0 / 1.1 / 1.2 is supported:
- The messages are not encrypted before or during transmission.
- Customer is expected (but not required) to use basic HTTP authentication (username/password) to protect the receiving URL by authenticating any request sent to the URL.
- If customer is implementing basic HTTP authentication, customer must provide a valid username/password.

3.2 Interface Description

3.2.1 Headers

Name

Mandatory

Value

Description

Authorization

N

username:password” in Base64 string, preceded by the authorization method (i.e. “Basic”)

Example:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

3.2.2 Method

POST

3.2.3 Request

POST /{customer URL}/

3.2.4 Input Parameters

#	Field Name	Type	Mandatory	Values	Description
1	subscriberId	String	Y		Subscriber’s Unique ID
2	msisdn	String	Y	MSISDN in e164 format. e.g. +15674296613	User phone number
3	ban	String	Y		Billing Account Number
4	messageId	String	Y		Unique Message ID per Subscriber. Case sensitive.
5	messageContext	String	Y	e.g. ‘pager-message’, ‘multimedia-message’	Message type
6	messageTime	Date	Y	e.g. “2014-11-20T23:28:30Z”	Message time in UTC
7	from	String	Y	MSISDN , Email	Message sender
8	to	String array	Y	List of MSISDN/ Email	Message recipient/s – To and CC recipients
9	groupMessage	Boolean	Y	True/false	Whether message is to a group
9	direction	String	Y	‘In’ , ‘Out’	Message direction – sent or received
10	subject	String	N		Message subject
11	contentType	String	N	‘text/plain’
12	textContent	String	N		Message text, in UTF8
13	textSize	Integer	N		Text message size, in bytes
14	attachment	Array	N
14.1	name	String	Y		Attachment name
14.2	content	String	Y		Attachment content, in base64
14.3	contentType	String	Y	e.g. ‘image/jpeg’	Attachment type
14.4	attachSize	Integer	Y		Attachment size, of the binary content

3.2.5 Outpot Parameters

NA

3.2.6 Request Sample

Text message example:

POST {customer’s url}

{

“subscriberId”: “N_NBI_033_9999999999999999999999”,

“msisdn”: “+11234567890”,

“ban”: “111111111111”,

“messageId”: ” %7Cnh”,

“messageContext”: “pager-message”,

“messageTime”: “2015-12-16T14:44:35Z”,

“from”: “+11234560000”,

“to”: [“+11234567890”],

“groupMessage”: false,

“contentType”: “text/plain”,

“textContent”: “Hi Michael”,

“textSize”: 8,

“direction”: “In”

}

Attachment message example:

POST {customer’s url}

{

“subscriberId”: “N_NBI_033_9999999999999999999999”,

“msisdn”: “+11234567890”,

“ban”: “111111111111”,

“messageId”: “wM”,

“messageContext”: “multimedia-message”,

“messageTime”: “2015-12-16T14:45:40Z”,

“from”: “+11234560000”,

“to”: [“+11234567890”],

“groupMessage”: false,

“subject”: “”,

“direction”: “In”,

“attachment”: [{

“name”: “TV_97429799-4759-41db-bd52-67b775d9bbdf.jpg”,

“contentType”: “image/jpeg”,

“content”: “c29tabBob3Rvb2ZzbWVvbmU=”,

“attachSize”: 17

}]

}

3.3 Response codes

Response Code	Description
200 OK	Success response
400 Bad request	Malformed request syntax
401 Unauthorized	Authorization has been refused for the credentials
404 Not found	User not found
500 Internal Server Error	The request could not be fulfilled due to Server error
503 Service Unavailable	Service Unavailable

4. Error handling

AT&T Message Archiving service is designed to resubmit messages in the following scenarios:

If there is no connection with the customer’s server
If an error was returned by the customer’s server
In case of timeouts

Note that any error returned by the customer’s server, either 4xx errors or 5xx errors, will trigger the retry logic. This is in order to avoid any circumstance of losing a message due to error condition on the customer’s side.

4.1 Retry Logic

Resubmitting a message due to any of the error cases defined above will follow the following logic:

Two consecutive retries are performed to push the message.
If all consecutive retries fail, a retry loop of 1 hour interval will be activated for the customer.
Each retry loop will resubmit all customer’s messages which could not be previously pushed.
The retry loop will be activated until all customer’s messages are pushed successfully, and as long as un-pushed messages exist.
Messages are kept in AT&T Message Archiving service temporary storage for up to 5 days. After 5 days, messages that could not be pushed will be deleted.

5. Connectivity test

After the Customer’s server URL is defined, it is possible to test that the customer’s server and the server URL are set up correctly, and that the customer is ready to receive messages.

The AT&T Onboarding Team can test the connectivity.

The connectivity test sends a test message to the company URL for a dummy user, using the AT&T Message Archiving Push API.

The MSISDN of the dummy user is ‘+99999999999’ (system configuration).

The text message is: “This is a test message”.

The customer’s server is expected to ignore a message that is sent to the pre-defined dummy user and return a 200 OK response.

6. Performance and Throughput

The push server’s throughput depends on AT&T Message Archiving capacity and on the customer’s server capacity.

There are two scenarios in which messages are pushed to the customer’s server:

Online message push
Retry message push

6.1 Online message push

Normally, messages are pushed as soon as they are captured by AT&T Message Archiving service. The message capacity depends on the company users’ message traffic.

The expected throughput of the AT&T Message Archiving Push API is 0.5 messages/sec, per 1000 users.

Note that if the customer’s server’s throughput is less than the online push capacity – the messages that fail due to overload, will be handled by the push retry described below.

6.2 Retry message push

The retry scenario is activated for messages that failed during online push. These messages will be pushed sequentially by the AT&T Message Archiving retry process, and therefore the throughput depends mainly on the customer’s server response time.

7. Technical Information

Production environment
The customer firewall should allow access from the following IP address 12.130.30.68.
We support one-way SSL encryption.
Connection is established over the Public Internet.