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:
Messaging API endpoint URL:
https://messaging-jwt.fortumo.io
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.
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.
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 |
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.
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" } |
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.
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) |
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 |
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" } |