08. Messages

POST /message.{format}

Send message. For more detailed examples go to Sending SMS

curl 'http://api.linkmobility.dk/v2/message.json?apikey=[apikey]' -X POST -H "Content-Type: application/json" -d @file.json
curl 'http://api.linkmobility.dk/v2/message.xml?apikey=[apikey]' -X POST -H "Content-Type: text/xml" -d @file.xml

Fields

Name	Type	Default	Description
recipients	String		Comma seperated list of recipients. listid, contactid or phone number, see format below
sender	String(11) / Int(22)	Service SMS	Name / Number of sender. If number defined use this format: +4512345678 where +45 is countrycode
message	String		The message to send
status	Boolean	false	Should a status request be made. See [api:example_dlr]
statusurl	String		URL to request with status of each message. See [api:example_dlr]
returndata	String		Custom data to return in statusurl request. See [api:example_dlr]
class	Int	1	See class list below
sendtime	Date		Send message at a later time, Format : dd-mm-YYYY HH:MM
price	Int	0	Price in local unit for the selected shortcode and minimum 100. For 1272 in DK it would be øre
charity	Boolean	false	Set price to be for a charity or vat exemption. Only allowed for approved users.
invoicetext	String(40)		Invoice text that should be shown on end users phone bill
validity	Int	2880	Message TTL in minutes (recommendation to telcos, but not a hard limit)
contenttype
format	Enum	GSM	See list belov
udh	String		Set UDH, used by BINARY messages
pushurl	String		Used by format WAPPUSH. The url pushed to the terminal
pushexpire	String		Used by format WAPPUSH. Exire time in unix timestamp, default is now + 7 days
filter	Array		Filter who in a list to send the message to. Requires the use of lists and mergefields.
segmentation	Array		Segmentation options for splitting lists into smaller chunks dynamicly when sending.
pid	Int	0	GSM Protocol ID
advanced	String		Key for using advanced fields
protocol	String (advanced)		The protocol name (REST, SMTP and others)
revenuetext	String		Used with premium messages to identify and group messages in the statistics and on the premium payout overview.

recipients

Name	Format	Description
phone number	+[number]	Phone numbers prefix is +. For instance +4512721272
contact id	c[id]	Contact id prefix is c. For instance c123
list id	[id]	List id is default and only an integer

recipients could look like this

1,2,c123,+452721272

format

Name	Required	Description
GSM		Send normal message (160 chars, but if more than 160 chars, 153 chars per part message)
UNICODE		To send speciality chars like chinese letters. A normal message is 160 chars, but if you use unicode each message can only hold 70 chars (But if more than 70 chars, 67 chars per part message)
BINARY	udh, message	Send a binary message body in hex and define udh
WAPPUSH	pushurl, pushexpire	Send a link that is opened on the phone

Keyword replacement

If you are sending to lists, you can use keyword replacement, for instance for inserting a uniq name in each message.

If your list had an extra field called Name you would use it like this :

Hi [Name]

This is only a test

contenttypes

1 = Ringetoner og billeder
2 = Videoklip og tv
3 = Voksenindhold
4 = Musik
5 = Lydbøger og podcasts
6 = Mobilspil
7 = Chat tjenester
8 = Konkurrence og afstemning
9 = Biletter og adgangsbetaling
10 = Nyheder og information
11 = Indsamlinger / donationer (Humanitære organisationer)
12 = Telemetri (M2M)
13 = Diverse
14 = Indsamlinger / donationer (ikke humanitære organisationer)
15 = Lotteri (moms fri)

Note! These contenttypes currenty only apply to danish shortcodes. See contenttypes for more info.

class

0 - Deprecated - Do not use !
1 - Save message in phone memory. Either on the phone or in SIM.
2 - Message contains SIM data.
3 - Message contains info that indicate that it should be sent to external units, normally used by terminal equipment.

By default you should not change this option

filter

Filter is a json array of rules that is matched during the send process, to limit who should get the message.

Name	Values	Description
match	any / all	The way the rules should be matched. Should all or any of the rules match to include a recipient.
rules	field, operation, value	Array of rules to match on

Operation	value	Descriptuon
is	is	If exact match is found include the recipient
is not	not	If exact is not found include the recipient
contains	contains	If mergefield contains the string include the recipient
does not contain	notcontain	If mergefield does not contain the string then include the recipient
starts with	start	If field stats with this string then include the recipient
ends with	ends	If fields ends with this string then include the recipient
is greater than	greater	If field is a number that is greater than value then include the recipient
is less than	less	If field is a number that is less than value then include the recipient

"filter":{
        "match": "any",
        "rules": [
            {
                "field": "Fornavn",
                "operation": "is",
                "value": "chuck"
            },
            {
                "field": "Fornavn",
                "operation": "not",
                "value": "jack"
            },
            {
                "field": "Fornavn",
                "operation": "contains",
                "value": "cool"
            }
        ]
    }

segmentation

Segmentation is a json array that tells the system how to split/limit who to send to.

Name	Description
count	If set how many recipients to send to
percent	If set how big a percentage of the segment should be used
exclude	List of previous batches

Sending to 10% of a list

"segmentation":{
        "percent": 10
}

Sending to the rest of the list

"segmentation":{
        "percent": 100,
        "exclude": [ 12345 ]
}

Responses

Each successful request, will create a new batch for handling the messages, hence it returns a batch status object.

A couple of examples of responses

success

{
    "stat": {
        "sendtime": "17-12-2014 08:42:24",
        "buffered": 0,
        "received": 0,
        "rejected": 0
    },
    "details": {
        "sendtime": "17-12-2014 08:42:24",
        "batchid": "310701",
        "state": "QUEUED"
    },
    "status": 201
}

wrong list id

{
    "status": 400,
    "message":"List ID 12 not found"
}

GET /messages/{page}.{format}

Get list of the newest batches including future waiting batches

curl 'http://api.linkmobility.dk/v2/messages/{page}.json?apikey=[apikey]' -X GET
curl 'http://api.linkmobility.dk/v2/messages/{page}.xml?apikey=[apikey]' -X GET

{
    "messages": [
        {
            "batchid": "2229409",
            "time": "23-03-2015 10:59:19",
            "state": "DONE",
            "sender": "TEST",
            "msg": "Hello world",
            "protocol": "SMTP"
        },
        {
            "batchid": "2229405",
            "time": "23-03-2015 10:50:16",
            "state": "DONE",
            "sender": "TEST",
            "msg": "Hello world",
            "protocol": "REST"
        }
    ],
    "status": 200
}

GET /message/{batchid}/{page}.{format}

Get message details based on batch id from POST

If page is 0 only summary is returned (batch status object)

curl 'http://api.linkmobility.dk/v2/message/{batchid}/{page}.json?apikey=[apikey]' -X GET
curl 'http://api.linkmobility.dk/v2/message/{batchid}/{page}.xml?apikey=[apikey]' -X GET

page = 0

{
    "stat": {
        "sendtime": "17-12-2014 08:42:24",
        "buffered": 0,
        "received": 1,
        "rejected": 1
    },
    "details": {
        "sendtime": "17-12-2014 08:42:24",
        "batchid": "310701",
        "state": "DONE"
    },
    "status": 200
}

page = 1

{
    "message": [
        {
            "msgid": "d2dc8158a56d5bfb201c357e950bf9e6",
            "status": "rejected",
            "recipient": "412345678",
            "statusreason": "Unknown subscriber"
        },
        {
            "msgid": "aeb4205213393c0da008b44f527037e7",
            "status": "received",
            "recipient": "4587654321",
            "statusreason": ""
        }
    ],
    "stat": {
        "sendtime": "17-12-2014 08:46:33",
        "buffered": 0,
        "received": 1,
        "rejected": 1
    },
    "details": {
        "sendtime": "17-12-2014 08:46:33",
        "batchid": "310713",
        "state": "DONE"
    },
    "paging": {
        "current": 1,
        "pages": 1
    },
    "status": 200
}

PUT /message/refund/{lookup-id}.{format}

Refunds a message. If a message is specified in the payload, the user will be notified about the refund (The notification will be sent from the users account).

curl 'http://api.linkmobility.dk/v2/message/refund/{lookup-id}.json?apikey=[apikey]' -X PUT -H "Content-Type: application/json" -d @file.json
curl 'http://api.linkmobility.dk/v2/message/refund/{lookup-id}.xml?apikey=[apikey]' -X PUT -H "Content-Type: text/xml" -d @file.xml

Payload file.json

{
	"refund":{
		"message":"Your message will be refunded"
	}
}

On success, the response is

{
  "status": 200,
  "statusreason": "Message is now in queue for refund."
}

EXPAND /message/expand/{batchid}.{format}

Advanced feature only allowed internally for message recipient expansion

curl 'http://api.linkmobility.dk/v2/message/expand/{batchid}.json?apikey=[apikey]&advanced=[advancedkey]' -X GET
curl 'http://api.linkmobility.dk/v2/message/expand/{batchid}.xml?apikey=[apikey]&advanced=[advancedkey]' -X GET

On success, the response is

{
  "header": [
    "Mobile"
  ],
  "data": [
    [
      "+4512721272"
    ]
  ],
  "status": 200
}

Batch Status Object

The "batch status object" contains basic information about the batch in its current state.

{
    "stat": {
        "sendtime": "17-12-2014 08:42:24",
        "buffered": 0,
        "received": 1,
        "rejected": 1
    },
    "details": {
        "sendtime": "17-12-2014 08:42:24",
        "batchid": "310701",
        "state": "DONE"
    },
    "status": 200
}

stat object:
- sendtime: batch send time
- buffered: number of messages buffered
- received: number of messages recieved
- rejected: number of messages rejected

details object:
- sendtime: batch send time
- batchid: id of current batch
- state: Possible states for batch processing [ QUEUED → RUNNING → DONE ]

status: overall status for the request

State	Description
QUEUED	The batch is ready for processing. The batch will be processed shortly after sendtime has passed.
RUNNING	The batch is currently processing. Messages are being sent, and the "buffered", "received" and "rejected" numbers will be updated as it is processed.
DONE	The batch has finished processing. Up to 48 hours after this the messages will still be sent out for delivery.

Please note:

The number of messages is not known before the batch changes state to "RUNNING". It is only in the "RUNNING" state the recipient lists are expanded.
- Therefore up until this point, "buffered", "recieved" and "rejected" will be 0
After the batch has changed state to "DONE" it will at some point be impossible to fetch the batch status. After this please use the 09. Query interface