AT&T Message Archiving

Learn how to set up and use AT&T Message Archiving.

Back to product page

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

  1. Customers will need to perform the following steps:
  2. Set up a server to capture and store employees’ incoming and outgoing messages from AT&T.
  3. 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.
  4. Develop the Message Archiving API, including the test connection option.
  5. With the help of the onboarding team, test the connection between the AT&T Message Archiving service and the customer’s server.

Top

 

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.

Top

 

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.

Top

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==

 

Top


3.2.2 Method

POST

 

Top

 

3.2.3 Request

POST /{customer URL}/

 

Top

 

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

 

Top

 

3.2.5 Outpot Parameters

NA

 

Top

 

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

}]

}

 

Top

 

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

 

Top

 

4. Error handling

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

  1. If there is no connection with the customer’s server
  2. If an error was returned by the customer’s server
  3. 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.

 

Top

 

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.

 

Top

 

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.

 

Top

 

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:

  1. Online message push
  2. Retry message push

 

Top

 

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.

 

Top

 

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.

 

Top

 

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.

 

Top