API Guide
-
Sending RCS/SMS
-
RCS/SMS Delivery Receipts
-
RCS Seen Receipt
-
Receiving Incoming Messages
1.Sending an RCS/SMS Message
An RCS/SMS request must contain all of the information which is required to route a message thorough the system to the handset. These are:
Information POST Field Example
Request Type reqType BULK
Number to send to MSISDN 447123456789
Message msg Hello World
Sender sender TestSender
Requests must be sent to “https://api2.mmg.co.uk/rcs/v2/api”.
All required information must be present in the JSON POST structure of the request.
Username/Password credentials should be sent along with the request via a standard basic authorisation header.
Example Request
POST https://api2.mmg.co.uk/rcs/v2/api
Content-Type: application/json
Authorization: Basic <base64 encoded username:password>
{
"reqType":"BULK",
"MSISDN":"447891658396",
"msg":"test message",
"sender":"TestSender",
}
Optional Parameters
Information POST Field Example
Multipart allowed (> 160 characters) multi true
Custom ID (returned with receipt) cid 123456
Receipt Delivery URL Delurl www.receipts.co.uk
Request Response
Successful Request
On submission of a complete SMS message request the server will respond with a single string in the format “Success 100, 42” where 42 is replaced by the unique reference used by MMG for delivery of the message to the handset and subsequent delivery report.
Notes
-
A message will only be sent by RCS if the Sender ID has been pre-registered, otherwise it will be sent as a standard SMS.
-
An RCS message will be attempted for 10 seconds before failing over to a standard SMS if it can’t be achieved
Example Successful Response
HTTP 200 OK
Content-Type: application/json
{
"reference": "42"
}
Failed Request
Upon receiving an incorrect request the server will respond with a single string in the format “Error 204” where 204 is replaced with one of the error codes below
Example Failed Response
HTTP 400 Bad Request
Content-Type: application/json
{
"Error":206,
"Description":"Invalid username or password"
}
Error Codes
Error Code Explanation
200 The request was not received through HTTPS. Requests must be sent to https://api.mmg.co.uk/rcs/api
201 The request was not made through HTTP POST
202 Username and/or Password not set or Username not in correct format
203 Request type not set
204 Invalid request type sent
205 Missing required field
206 Username or password incorrect
207 Invalid MSISDN
208 Master account does not have enough credits available to complete the transaction
209 Message too long
210 Sender too long
220 API is temporarily disabled due to too many failed logins.
221 API is permanently disabled due to too many failed logins.
2. RCS/SMS Delivery Receipt
Once the RCS/SMS message has been delivered a POST request will be made to the location defined in your API account.
The format of the request will be as follows:
Information POST Field Example
Unique Reference ID 42
Custom Reference CID 1234-232-134
Number message sent to MSISDN 447123456789
Delivery Date and Time Delivery 2012-06-27 12:33:00
Status status 3
Substatus substatus 5
Upon successful receipt of the above data the receiving server should respond in a timely manner (less than a second) with a single line string response of “RECEIVED”
Example Delivery Receipt
POST https://www.website.co.uk/receipts
Content-Type: application/json
{
"reference":"564634E434D0586B0C957D97E556CAD",
"MSISDN":"447891658396",
"status":"3",
"substatus": "5",
"deliverytime":"2024-01-01 16:36:48",
"cid":"customid"
}
Status Codes
Code Explanation
3 - Successful Delivery
2 - Undeliverable
4 - Message delivery has expired
5 - Message has been rejected by the network
Sub Status Codes
Code Explanation
2 - Delivered to Operator
5 - Delivered to handset
4 - Message was rejected by the operator and deemed undeliverable, possibly due to a network glitch or restrictions imposed by the operator
9 - Message was not delivered to the intended recipient and considered undeliverable, typically due to factors such as an invalid or unreachable destination number
15 - Message was received and sent to the operator. However, it has been pending until the validity period has expired or the operator returns the EXPIRED status
29 - Message has expired, and the delivery status is unknown, indicating that the delivery report or confirmation was not received or could not be determined
6 - Message has been received, but the network is experiencing problems
10 - Message has been received and rejected because the user is subscribed to DND (Do Not Disturb) services
14 - The destination address has been blocklisted either at the operator's request
3. RCS Seen Receipt
Once the RCS message has been seen a POST request will be made to the location defined in your API account.
Note: Only RCS messages send a Seen Receipt.
The format of the request will be as follows:
Information POST Field Example
Unique Reference ID 42
Custom Reference CID 1234-232-134
Number message sent to MSISDN 447123456789
Seen Date and Time seentime 2012-06-27 12:33:00
Upon successful receive of the above data the receiving server should respond in a timely manner (less than a second) with a single line string response of “RECEIVED”
Example Seen Receipt
POST https://www.website.co.uk/seen-receipts
Content-Type: application/json
{
"reference":"564634E434D0586B0C957D97E556CAD",
"CID": "1234-232-134",
"MSISDN":"447891658396",
"seentime":"2024-01-01 16:36:48",
}
4. Receiving Incoming Messages
When an incoming message is received by the MMG system, it is checked against a list of registered numbers and RCS senders. If one is found, a POST request will be made to the location defined in your API account.
The format of the request will be as follows:
Information Post Field Example
Unique Reference IID 42
Number/Sender message sent from MSISDN 447123456789
Message Message Hello
Number message sent to Number 44789011829
Received Date and Time DateReceived 2012-06-27 12:33:00 or Failed
Upon successful receipt of the above data the receiving server should respond in a timely manner (less than a second) with a single line string response of “RECEIVED”.
Example Request
POST https://www.website.co.uk/incoming.php
Content-Type: application/json
{
"MSISDN":"NotifyTest",
"Message":"Testing",
"Number":"44789100000",
"DateRecieved":" 2024-01-28 11:54:32",
"ID":"MxJFwONIywR7yZysg7iAtDXQ"
}