The MGW API implementation attempts to adhere RESTful principles; and much of the Messaging Gateway system functionality are exposed via REST Resources.
Depending on the type of Resource, the API Client MAY invoke the supported methods (e.g. POST, GET, PUT, DELETE) to achieve an action or a set of actions.
The following are the publicly available Resources that are used for interchange between the MGW and the User’s system:
- Document Resource
- DeliveryReceipt Resource
A document is a resource that encapsulates a MO/MT message (applies to both SMS and MMS).
| Field | Description | Version | MO/MT |
| id |
String; globally unique identifier of the document message. If this is omittted in MT Documents, a unique id string is automatically generated. For MT documents, API Clients MAY optionally inject and generate their own unique IDs for the DeliveryReceipt. If this ID is not unique however, this may cause confusion in the tracking of DeliveryReceipts. As of version 2017-12, id values that are submitted as integers may be automatically converted to string |
3 | MO, MT system generated |
| from | String; The source of the document;For MT documents, this will be the VirtualShortCode OR a suffixed VirtualShortCode.For MO documents, this will be the mobile number OR a masked-mobile-number. The mobile number is expected to follow the E.164 international format without the leading ‘+’, i.e. country code + phone number (e.g. 639101234567).As of version 2017-12, if the mobile number has the leading ‘+’, the ‘+’ character will be removed. |
3 | MO (required), MT (required) |
| to | String; The destination of the document;For MT documents, this will be the mobile number OR a masked-mobile-number. The mobile number is expected to follow the E.164 international format without the leading ‘+’, i.e. country code + phone number (e.g. 639101234567) |
3 | MO (required), MT (required) |
| content_type | String;
The MIME type of the content body. Currently supported value is “text/plain”. |
3 | MO (required),
MT (required) |
| body | String;
The content body of the document. For “text/plain” document, this is the UTF-8 text message. |
3 | MO (required), MT (required) |
| date | String; The date of the document.Format can be:
The default timezone is “UTC” (GMT) if tzinfo is not present. |
3 | MO (required), MT (required) |
| usagetype | String; Application code for context and logging.For MT documents under VirtualShortCodes with MT-billing (i.e. Reverse SMS billing, where recepient is charged), the usagetype value resolves to the applicable Telco tariff code (charge amount) for the document.This is provisioned and configured per User. |
3 | MO (optional), MT (required) |
| delivery_receipt_url | String; URL where the Messaging Gateway will attempt to POST the status of the document. (see DeliveryReceipt resource) |
3 | MT (optional) |
| thread | String; The thread identifier for tying the MT response to the original MO document.Depending on the Telco requirements, this MAY be required. This is provisioned and configured per User. |
3 | MO (optional),
MT (optional) |
| telco | String; The unique name of the Telco.This is for logging and customization purposes (e.g. per- Telco reply document customization).This is provisioned and configurable per User. |
3 | MO (optional), MT (not applicable) |
| from_alias | String; alphanumeric up to 11 characters. The alphanumeric sender ID; if enabled and allowed in your account.Note that this differs from the ‘from‘ field – which refers to the VirtualShortcode assigned to you. |
3 | MO (not applicable), MT (optional) |
Every document SHOULD be identified by the content type:application/vnd.net.wyrls.Document-v3+json
Serialization formats supported: json = Javascript Object Notation
Sample MO Document (inbound document, as sent from mobile to VirtualShortCode 100234)
{
“id”: “103fe864-182b-11e2-9c9c-6c626d3f08c7”,
“from”: “639191234444”,
“to”: “100234”,
“content_type”: “text/plain”,
“body”: “hello world”,
“usagetype”: “MYSERVICE_INBOUND”,
“thread”: “120123182418”,
“telco”: “smart”,
“date”: “20120123T102537”
}
Sample MT Document (outbound document, as sent by API Client from AccessNumber 100234 to mobile)
{
“id”: “150b6f40-f5a7-11e1-a21f-0800200c9a66”,
“from”: “100234”,
“from_alias”: “MYSERVICE”,
“to”: “639191234444”,
“content_type”: “text/plain”,
“body”: “Sorry, you sent an invalid keyword. Text HELP to 100234”,
“usagetype”: “MYSERVICE_REPLY_PREMIUM”,
“thread”: “120123182418”,
“date”: “2012-01-23T18:25:43+0800”,
“delivery_receipt_url”: “http://12.34.56.78/uri/to/delivery_receipt_handler”
}
Requirements
The User MUST use an API Client (HTTP user agent).
For authentication/authorization, Basic Access Authentication scheme will be used (see Appendix).
Request
To send a document, a Client must issue an HTTP POST request with the following structure.
POST /documents HTTP/1.1
Host: <hostname>
Authorization: Basic <base64_encoded_account>
Date: Thu, 2 Feb 2012 22:38:34 GMT
Content-Type: application/vnd.net.wyrls.Document-v3+json
Content-Length: Nnnn
<MT_Document_resource_encoded_as_json>
Successful Response
The HTTP status code 202 Accepted means that the document was successfully created and enqueued for delivery.
Error Responses
Error status codes MAY include X-Client-Error header for diagnostics purposes.
HTTP Status Codes:
4xx – Client error, please consult the HTTP headers for additional information.
5xx – Server error, escalate to support contact.
Requirements
The User MUST setup the URL endpoint where MO document will be sent (HTTP POST).
This URL will be provisioned in the Messaging Gateway on a per VirtualShortCode OR per keyword basis (if on a shared VirtualShortCode).
Request
The MGW user-agent will issue an HTTP POST request with the following:
POST <URL_endpoint_uri_path> HTTP/1.1
Host: <hostname>
Date: Thu, 2 Feb 2012 22:38:34 GMT
Content-Type: application/vnd.net.wyrls.Document-v3+json
Content-Length: Nnnn
<MO_Document_resource_encoded_as_json>
Successful Response
The HTTP status code 202 Accepted means that the document was successfully created and enqueued for delivery.
The MGW user-agent MAY also accept any 2xx code.
Error Responses
HTTP Status Codes:
4xx – The MGW user-agent MAY retry. Upon repeated 4xx errors, MGW user-agent MAY rate-limit / back-off.
5xx – The MGW user-agent MAY retry. Upon repeated 5xx errors, MGW user-agent MAY rate-limit / back-off.
A delivery receipt is a resource that encapsulates the status of an MT document; if indeed it was delivered to the Telco successfully or not.
| Field | Description | Version |
| id |
String; Version unique identifier (uuid) of the delivery receipt. |
1 |
| message_id | String; The id of the MT document where this delivery receipt applies. See the id field of the Document Resource. |
1 |
| delivered | Boolean; If true; this means that the MT document was delivered to the SMSC/MMSC. If false; this means that the delivery of the MT document failed (rejected by the SMSC/MMSC). |
1 |
| reason_code | String; Describes additional information on the value of the “delivered” field. (see table below for the standard values). |
2 |
| reason_description | String; Describes additional information on the “reason_code” field. (see table below for the standard values). |
2 |
Standard Code values:
| Code | Description |
| 200 |
OK – means successfully delivered MT document to the SMSC/MMSC. |
| 400 | Bad Request – means failed to deliver MT document due to bad syntax or invalid format. |
| 402 | Payment Required – means failed to deliver MT document due to insufficient or undetermined balance to fulfill the transaction. |
| 403 | Forbidden – means failed to deliver MT document due to denied permission of the transaction. |
| 404 | Not Found – means failed to deliver MT document due to missing information needed by the SMSC / MMSC. |
| 423 | Locked – means failed to deliver MT document due to time restriction. |
| 500 | Internal Server Error – means failed to deliver MT document due to MGW / SMSC / MMSC error (general system error). |
| 503 | Service Unavailable – means failed to deliver MT document due to temporary unavailability or capacity error in the MGW / SMSC / MMSC. |
DeliveryReceipt Representation
Every delivery receipt is identified by the content type: application/vnd.net.wyrls.DeliveryReceipt-v2+json
Serialization format is: json = Javascript Object Notification.
Example DeliveryReceipt Representations
{
“id”: “449981c0-f5a7-11e1-a21f-0800200c9a66”
“message_id”: “150b6f40-f5a7-11e1-a21f-0800200c9a66”,
“delivered”: true,
“reason_code”: 200,
“reason_description”: “OK”
}
Requirements
The User MUST setup the URL endpoint where DeliveryReceipts will be sent (HTTP POST).
This URL is set per MT document (see the Document Resource field delivery_receipt_url).
Request
The MGW user-agent will issue an HTTP POST request with the following:
POST Requirements
The User MUST setup the URL endpoint where DeliveryReceipts will be sent (HTTP POST).
This URL is set per MT document (see the Document Resource field delivery_receipt_url).
Request
The MGW user-agent will issue an HTTP POST request with the following:
POST <URL_endpoint_uri_path> HTTP/1.1
Host: <hostname>
Date: Thu, 2 Feb 2012 22:39:21 GMT
Content-Type: application/vnd.net.wyrls.DeliveryReceipt-v2+json
Content-Length: Nnnn
<DeliveryReceipt_resource_encoded_as_json>
Successful Response
The HTTP status code 202 Accepted should means that the delivery_receipt was successfully created and
enqueued for processing.
The MGW user-agent MAY also accept any 2xx code.
Error Responses
HTTP Status Codes:
4xx – The MGW user-agent MAY retry. Upon repeated 4xx errors, MGW user-agent MAY rate-limit / back-off.
5xx – The MGW user-agent MAY retry. Upon repeated 5xx errors, MGW user-agent MAY rate-limit / back-off.
