Sending messages

Messaging API is RESTful and asynchronous. Upon successfully calling the Fortumo messaging endpoint, Fortumo responds with HTTP 200 indicating successful receival of messaging request. The initial response is followed by message delivery status callbacks to the URL specified in the messaging request. Every callback will have a reference to the original request and the latest state of the messaging object.

There are 2 major ways how Fortumo Messaging API can be used for sending messages:

• using phone numbers (MSISDNs) as a sender - mainly for 2FA and marketing related messages
• using charging tokens - mainly used for additional communication with users who have authenticated their identity via Fortumo Authorisations API

Messaging API endpoint URL:

https://messaging-jwt.fortumo.io

REST

Payments API is designed according to the REST principles where different resources are created and updated. This allows easy integration using existing tools and provides established security infrastructure between the parties. This also simplifies the overall design and implementation of the API functionalities.

Synchronicity

Payments API is designed to be fully asynchronous and the immediate response indicates only if the initial submission of the API call has succeeded (e.g. contains valid request body that can be parsed). Actual results of the methods are delivered to the merchant by making callback requests to the merchant hosted Local API. On object status change, a new callback request is made to the Local API.

HTTP response codes

Fortumo will respond with one of the following HTTP codes to indicate that your request has been received.

Idempotency

All method calls with identical operation_reference parameter value will result in the same behaviour. This consistent behaviour helps to avoid duplications in case of failures and retries. For example, in case of a timeout error it is safe to retry sending the same API calls multiple times. When the call successfully delivers its message, the action is executed only once, and the operation would not be duplicated.

Messaging request parameters

Only secure HTTPS URL's can be used as callback URL's

Specifying country and channel code is not mandatory, but is recommended, provided you have that information as it improves the speed and reliability of message routing.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

POST /messaging HTTP/1.1
Host: messaging.fortumo.io
Content-Type: application/json

{
    "sender": "Fortumo", 
    "recipient": {
    	"msisdn": "3725123456"
    },
    "message_body":  "You are now subscribed to Unlimited Games. Support at s.fortumo.com", 
    "message_type": "marketing", 
    "merchant": "c087decf541277b7921ad6a42693ad8e", 
    "callback": "https://example.com/", 
    "operation_reference": "f152f32c301c918fa125e03aabb18850" 
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

POST /messaging HTTP/1.1
Host: messaging.fortumo.io
Content-Type: application/json

{
    "sender": "Fortumo", 
    "recipient": {
      "country_code": "EE", 
      "channel_code": "sandbox-ee", 
      "msisdn": "3725123456"
    },
    "message_body":  "You are now subscribed to Unlimited Games. Support at s.fortumo.com", 
    "message_type": "marketing", 
    "merchant": "c087decf541277b7921ad6a42693ad8e", 
    "callback": "https://example.com/", 
    "operation_reference": "f152f32c301c918fa125e03aabb18850" 
}

1
2
3
4
5
6
7
8
9
10
11
12
13

POST /messaging HTTP/1.1
Host: messaging.fortumo.io
Content-Type: application/json

{
    "sender": "Fortumo",
    "charging_token": "8ebd3885-7129-4e23-99c7-58e9741d3941:d3304123",
    "message_body":  "Your subscription to Premium Access will be renewed in 24h. Support at s.fortumo.com", 
    "message_type": "reminder",
    "merchant": "c087decf541277b7921ad6a42693ad8e",
    "callback": "https://example.com/", 
    "operation_reference":"f152f32c301c918fa125e03aabb18850"
}

Callbacks

Once your request has been processed Fortumo will make a callback request to the URL provided in the initial request.

Please note that lack of confirmed callback does not always mean that message was not delivered. On certain operators status updates are not made at all and may be missing for single messages based on number of factors.

Callback parameters

Delivery errors

Possible messaging states

1
2
3
4
5
6
7
8
9
10
11
12

POST https://merchant-callback.url/ HTTP/1.1
Content-Type: application/json

{
  "message_id": "ce33066d-bd3a-494a-92f9-2a9234385f9f",
  "message_state": "submitted",
  "merchant": "c087decf541277b7921ad6a42693ad8e",
  "operation_reference": "f152f32c301c918fa125e03aabb18850",
  "consumer_identity": "bf78835b-538e-30e9-8483-3cfee5ce6eb7",
  "error": {},
  "timestamp": "2016-05-24T07:16:50.352Z"
}

1
2
3
4
5
6
7
8
9
10
11
12

POST https://merchant-callback.url/ HTTP/1.1
Content-Type: application/json

{
  "message_id": "ce33066d-bd3a-494a-92f9-2a9234385f9f",
  "message_state": "delivered",
  "merchant": "c087decf541277b7921ad6a42693ad8e",
  "operation_reference": "152f32c301c918fa125e03aabb18850",
  "consumer_identity": "bf78835b-538e-30e9-8483-3cfee5ce6eb7",
  "error": {},
  "timestamp": "2016-05-24T07:17:07.352Z"
}