Messaging API

At the core of Fortumo’s Messaging Platform is our Messaging API. This robust, scalable API gives you a global line of communication with your customers for authentication (2FA), payment confirmations, notifications and promotions through A2P SMS messaging. You can use the Messaging API together with our direct carrier billing and bundling platforms or as a stand-alone solution.

Messaging API is RESTful and asynchronous. Upon successfully calling the Fortumo messaging endpoint, Fortumo responds with HTTP 200. The initial response is followed by a separate callback 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.

Fortumo Messaging API can be used for sending messages

  • to specific MSISDNs
  • using charging_token, to users that have authenticated their identity via Fortumo Authorisations API

Security

Messaging API uses certificate based authentication where certificates are provided on every incoming and outgoing request.

When calling the Fortumo messaging endpoint, you will need to provide Fortumo with the certificate common name (CN) in the certificate that is associated with your merchant account. For account configuration, please get in touch with your account manager.

Every request that originates from Fortumo will have following subject:

Subject: C=EE, ST=Tartumaa, L=Tartu, O=Fortumo Ltd., CN=api.fortumo.io

MSISDN based messaging

The first option to specify the recipient of a text message is to provide user's MSISDN to Fortumo. In order to guarantee that every message is sent with the best rates possible, it is recommended to also specify user's country and carrier, provided you have that information.

MSISDN based messaging request example:

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": "A Gaming Company", 
    "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" 
}

Charging token based messaging

An alternative method for using Messaging API in case you do not have access to user's MSISDN is to have user authenticate their identity with the help of Fortumo Authorisations API. After you have access to a user verified charging token, you can, instead of specifying user MSISDN, simply provide Fortumo the verified charging token value and Fortumo makes sure your message reaches the correct phone number.

Charging token based messaging request example:

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": "A Gaming Company",
    "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"
}

Request parameters

Parameter Type Description Possible values Optionality
merchant String Merchant hash that identifies you as a merchant, issued by Fortumo 27f883a72e93a62b916957df48a1ef52 mandatory
charging_token String Token received after user has authenticated their identity via Authorisations API, issued by Fortumo 8923b690-2d70-4d51-8caa-d4ab2871f188:8fe403b3 optional (for MSISDN based messaging)/ mandatory (for charging token based messaging)
operation_reference String Unique reference ID generated by the you for correlating message requests to message callbacks, issued by merchant f152f32c301c918fa125e03aabb18850 (Should not exceed 32 characters) mandatory
message_type String Defines the type of the message that may or may not affect the cost of sending the specific message receipt, reminder or marketing mandatory
message_body String Message that is sent to the user You are now subscribed to Unlimited Games. Play games now at https://exam.ple/18b789aa Price: 5 MYR (excl. GST). To un-subscribe:https://exam.ple/181189aa (Should not exceed 160 characters) mandatory
sender String Short name of the message sender that, when possible, will be used as SMS sender value A Gaming Company mandatory
recipient Object Details of the recipient of the message See below for parameters optional (for charging token based messaging)/ mandatory (for MSISDN based messaging)
callback String URL where Fortumo will make your server callbacks indicating message delivery status https://example.com/ mandatory
Recipient        
country_code String Specifies the country of the recipient's MSISDN EE (ISO 3166-1 alpha-2) optional
channel_code String Specifies the carrier of the recipient of the text message, codes issued by Fortumo and values are available via Capabilities API tele2-ee optional
msisdn Integer Specifies the phone number where the message will be sent 3725123456 (International format including country code, excluding + sign) mandatory
API response

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

Status code Description
200 Everything OK, messaging request queued for processing
400 Bad request containing errors in the request body (e.g. mandatory field missing)
406 Content-Type was not application/json
495 Certificate missing
500 Service unavailable due to a temporary overloading or maintenance, retry required

API callback

Once your request has been processed Fortumo will make a callback to your callback URL. Each callback will have a reference to the original messaging request and the latest state of the message.

Callback example:

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": "f152f32c301c918fa125e03aabb18850",
  "consumer_identity": "bf78835b-538e-30e9-8483-3cfee5ce6eb7",
  "error": {},
  "timestamp": "2016-05-24T07:17:07.352Z"
}
Callback parameters
Parameter Type Description Possible values
message_id String Unique ID of the message that was sent, automatically generated by Fortumo ce33066d-bd3a-494a-92f9-2a9234385f9f
merchant String Merchant hash that identifies you as a merchant, issued by Fortumo 27f883a72e93a62b916957df48a1ef52
operation_reference String Unique reference ID generated by you for correlating callbacks to messaging requests, specified by merchant in message request f152f32c301c918fa125e03aabb18850
message_state String Delivery state of the message delivered or failed
consumer_identity String A unique identification ID of the consumer involved, will be the same even if the consumer makes another authorisation c087decf541277b7921ad6a42693ad8e
error Object Informational object for understanding the reason behind message delivery failure See below for specific error codes and messages
timestamp String Timestamp when the message was created 2015-08-18T06:36:40Z (ISO-8601)
Possible delivery error codes
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
Help us improve our Merchants Portal. Was this article helpful?