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.

Code Description
200 Everything OK, request queued for processing
400 Bad request containing errors in the message (e.g. mandatory field missing, value too short)
403 Certificate is valid but merchant is not supported.
406 Content-Type was not application/json
495 Certificate missing
500 Service unavailable due to a temporary overloading or maintenance. Retry required
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

Parameter Type Required Description
merchant String Mandatory Merchant account id, provided by Fortumo, e.g. 27f883a72e93a62b916957df48a1ef52
charging_token String Optional A valid and verified customer identifying token, provided by Authorisations API and issued by Fortumo. Mandatory for charging token based messaging. Example: 8923b690-2d70-4d51-8caa-d4ab2871f188:8fe403b3
operation_reference String Mandatory Unique reference ID for uniquely identifying each API request and correlating message requests to message callbacks. Should not exceed 32 characters. Example: f152f32c301c918fa125e03aabb18850
message_type String Mandatory Defines the type of the message that may or may not affect the cost of sending the specific message. Refer to your Account Manager for the right value to use. Supported values are receipt, reminder and marketing with last one being the default and most commonly used value
message_body String Mandatory Message content that will be sent to the user. Is subject to standard GSM limits for the length of SMS (usually 160 symbols for Latin and 70 symbols for Unicode).
sender String Mandatory Short name of the message sender that, where available, will be used as SMS sender value. Refer to integration prerequisites for more information on custom sender names. Example: Fortumo
recipient Object Optional Details of the recipient of the message, see below for parameters. Mandatory for MSISDN based messaging
callback String Mandatory A HTTPS URL for delivering message status and delivery callbacks, e.g. https://example.com/
Recipient      
country_code String Optional Specifies the country of the recipient's MSISDN according to ISO 3166-1 alpha-2. Optional, but improves routing when set. Example: EE
channel_code String Optional Specifies the carrier of the recipient of the text message for advanced routing. Channel codes are issued by Fortumo, e.g. orange-pl
msisdn Integer Mandatory Specifies the phone number where the message will be sent in international format including country code, excluding + sign, e.g. 3725123456

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
Parameter Type Required Description
message_id String Mandatory Unique ID of the message that was sent, automatically generated by Fortumo, e.g. ce33066d-bd3a-494a-92f9-2a9234385f9f
merchant String Mandatory Merchant hash that identifies you as a merchant, issued by Fortumo. E.g. 27f883a72e93a62b916957df48a1ef52
operation_reference String Mandatory Unique reference ID generated by you for correlating callbacks to messaging requests, specified by merchant in message request, e.g. f152f32c301c918fa125e03aabb18850
message_state String Mandatory Current delivery state of the message, one of submitted, delivered, failed
consumer_identity String Mandatory Consumer identification id, e.g. c087decf541277b7921ad6a42693ad8e. A one-time temporary value e.g. not_persisted_3af593eb-6b2a-433f-852d-df70a3fa6a9e will be sent for MSISDN-based messaging
error Object Optional Informational object for understanding the reason behind message delivery failure. See below for specific error codes and messages
timestamp String Mandatory Timestamp when the message was created, e.g. 2015-08-18T06:36:40Z (ISO-8601)
Delivery errors
Code Message
1001 Generic error, non-retriable
1002 Generic error, retriable
1003 Invalid recipient
1004 Carrier not supported
1005 Invalid sender name
1006 Message content too long
1007 Messaging not enabled

Possible messaging states

Authorisation state Description
submitted SMS was forwarded to mobile operator and awaits delivery.
delivered SMS was successfully delivered to handset and delivery was confirmed by the operator.
failed SMS sending failed either due to error routing or delivery error.
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"
}
Help us improve our Merchants Portal. Was this article helpful?