Fetch Messages

Overview

If this web service is defined in account XML, the app will use it to check for new incoming messages. The web service is called each time the app is moved to foreground and also when push notification about incoming message arrives.

For more information about sending push notification to the app, see Push Notifications over HTTP

Hint

To get full send/receive text message functionality via web services, all the following web services will have to be implemented:

  • Send Message to be able to send outgoing messages
  • Fetch Messages to be able to fetch incoming messages
  • Push Notifications over HTTP to be able to send push notifications to mobile devices about incoming messages
  • Push Token Reporter to obtain and store push addresses of devices and create mapping between usernames and push addresses where the username is being used.

If you receive an incoming message for user X on your server, you need to check the mapping created by Push Token Reporter and see that user X is using device with push token ABC. You can then send push notification to this device using Push Notifications over HTTP web service. Push notifications will wake up the app on this device and make it call the Fetch Messages, which will finally deliver the messages.

Parameters

Parameter templates for Fetch Messages web service can use any variables from Global parameters and Account parameters scopes. There are also additional, service-specific parameters for this service:

last_known_sms_id

This parameter will be replaced by sms_id field of the last message received in the past. “Last” is based on timestamp, i.e. it will be sms_id of the message received before with the highest sending_date.

Server can use this field to determine which messages need to be sent to client. In case there is no previous message, the app will send an empty string.

last_known_sending_date

Similar to above, this parameter will be replaced by the most recent sending_date received previously. Note that apps will send this parameter in RFC3339 format with UTC timezone. If you use a different timezone in your response, the value here will be converted.

Server can use this field to determine which messages need to be sent to client. In case there is no previous message, the app will send an empty string.

Configuration

The following Account XML keys are relevant for Fetch Messages web service configuration:

genericSmsFetchUrl

Contains the URL, including URL scheme, of the web service, possibly also with query string.

https://example.com/fetch_messages/?username=%account[username]%&password=%account[password]%&last_id=%last_known_sms_id&last_ts=%last_known_sending_date%&device=%installid%

genericSmsFetchPostData

If filled in, the app will use POST request to send the message.

Example ( for application/x-www-form-urlencoded):

username=%account[username]%&password=%account[password]%&last_id=%last_known_sms_id&last_ts=%last_known_sending_date%&device=%installid%

Example ( for application/json ):

{
  "username" : "%account[username]%",
  "password" : "%account[password]%",
  "last_id"  : "%last_known_sms_id%",
  "last_ts"  : "%last_known_sending_date%",
  "device"   : "%installid%"
}

genericSmsFetchContentType

Specifies the value of Content-Type header to be sent in the request. If not specified, the app will default to application/x-www-form-urlencoded

Response

The response will be considered successful if the HTTP response code is 2xx.

Non-2xx responses are silently ignored.

Successful response can contain array of items under unread_smss key, which represent unread messages. Only “application/xml” and “application/json” content types are supported for the response. Each record has following fields:

sms_id:unique identifier of the message, set by provider. Optional, but if not provided, the app won’t check for duplicate messages.
sending_date:date when the message was sent, in RFC 3339 format.
sender:address of the sender. This field should work as destination address when sending a reply.
sms_text:body of the message, UTF-8 encoded

The response should also contain date key, which represent the current date on the server and should be based on the same clock as sending_date. It must be in RFC 3339 format. It’s used to synchronize timestamps of incoming messages which are server clock based with the timestamps of outgoing messages which are device clock based.

See the examples below for better understanding.

Duplicate detection and removal

Received messages are checked for duplicities. Duplicate messages are detected based on sending_date and sms_id fields. In case your web service returns a message with both values which already exist on the client, it will be silently ignored.

Examples

GET method, XML

request:

GET /fetch_messages/?username=johndow&password=12345678&last_id=&last_ts=&device=73C54F29105A0647 HTTP/1.1
Host: example.com
Connection: close
Cache-Control: max-age=0
User-Agent: CloudSoftphone/1.5.6

response:

HTTP/1.1 200 OK
Date: Sun, 15 Mar 2015 00:46:17 GMT
Server: Apache/2.4.7 (Ubuntu)
Vary: Accept-Encoding
Content-Length: 123
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Content-Type: text/xml

<response>
    <date>2015-03-15T00:46:17.25Z</date>
    <unread_smss>
        <item>
            <sms_id>E6E553673C54F29105A0647204C</sms_id>
            <sending_date>2014-12-19T16:39:57.31-08:00</sending_date>
            <sender>+1 (555) 123-1234</sender>
            <sms_text>Hello World</sms_text>
        </item>
        <item>
            <sms_id>E6E553673C54F29105A0647A4F0</sms_id>
            <sending_date>2014-12-19T16:39:59.77-08:00</sending_date>
            <sender>+1 (555) 123-1234</sender>
            <sms_text>Another message</sms_text>
        </item>
    </unread_smss>
</response>

POST method, JSON

request:

POST /fetch_messages/ HTTP/1.1
Host: example.com
Connection: close
Cache-Control: max-age=0
User-Agent: CloudSoftphone/1.5.6
Content-Type: application/json
Content-Length: 183


{
    "username"    : "johndow",
    "password"    : "12345678",
    "last_id "    : "E6E553673C54F29105A0647204C",
    "last_ts "    : "2014-12-20T00:39:57.000Z",
    "device  "    : "73C54F29105A0647"
}

response:

HTTP/1.1 200 OK
Date: Sun, 15 Mar 2015 00:46:17 GMT
Server: Apache/2.4.7 (Ubuntu)
Vary: Accept-Encoding
Content-Length: 123
Keep-Alive: timeout=5, max=100
Content-Type: application/json
Connection: Keep-Alive

{
    "date"          : "2015-03-15T00:46:17.25Z",
    "unread_smss"   :
    [
            {
                "sms_id"        : "E6E553673C54F29105A0647204C",
                "sending_date"  : "2014-12-19T16:39:57.31-08:00",
                "sender"        : "+1 (555) 123-1234",
                "sms_text"      : "Hello World"
            },
            {
                "sms_id"        : "E6E553673C54F29105A0647A4F0",
                "sending_date"  : "2014-12-19T16:39:59.77-08:00",
                "sender"        : "+1 (555) 123-1234",
                "sms_text"      : "Another message"
            }
    ]
}