This document outlines the messaging interface for application providers for the purposes of sending and receiving SMS/MMS short and long code messages.

The SMS/JSON interface allows messages to be received from a mobile user (Mobile Originated, or MO) and messages to be sent to a mobile user (Mobile Terminated, or MT).

Short Code Keyword Requirements

The Canadian Wireless Telecommunications Association (CWTA) mandates that certain keywords be available with all short code services, to ensure that the consumer and carriers can obtain necessary information about the service:

INFO – English or English/French service information (who runs the service, how can they be contacted, who is the aggregator, etc.)

HELP / AIDE – English / French help messages (where can more information or help be found, contest rules & regulations, contact info, etc.)

STOP / ARRET - English / French opt-out request

The application should process incoming text from the mobile phone in a case insensitive way (i.e. treat STOP, Stop and stop as identical requests).

Mobile Originated (MO) messages are messages sent to a short code or long code by a mobile user via SMS and the application will process the MO message. In an interactive program, the MO message is usually followed with an MT reply to the user. This reply can be sent at a later time with an MT transaction originated by the application provider. For short code it can be sent with the MO confirmation in the transaction originated by Sunwire.

The application provider will provide a URL for a collection agent that can receive JSON over HTTP as content-type application/json and reply with a JSON response.

MO requests will come from the same addresses as your destination for MT messages (see below).

The Request will contain the following attributes:

• Type: ‘Message’ – Indicates the type of request
• ID: Unique identifier of the message
• From: The sender of the message (Note: The phone number format may vary from carrier to carrier. It will either be a 10 (national) or 11 (international) digit number)
• To: Short code or long code receiving the message
• Body: The contents of the message (UTF-8 encoded)
• Key: Optional: When configured, a key will be provided in the request to authenticate with your application.

The Response must contain the following attributes:

• Status: ‘OK’ to mark the message as received. Remove it from queue. ‘FAIL’ to mark the message as received but rejected. Remove it from queue.
• Body: This is an optional field and will only work on short codes. You may include a message in the Body attribute to immediately respond (must be UTF-8 encoded). NOTE: For cross- carrier programs, the reply should be limited to less than 137 characters (1-136) due to carrier restrictions on message size. This limit includes spaces, carriage returns, etc.

An HTTP error, empty response or status other than ‘OK’ or ‘FAIL’ will be treated as a delivery failure and the message will not be removed from the queue. Delivery failures will be re-attempted at exponentially increasing intervals, re-trying after 2 seconds, then 4, 8, 16, etc… up to a total of 12 re-tries (or approximately 2.5 hours of attempts), after which the message will be marked as failed and removed from the queue.

Example MO SMS

Request

                                    
                                    { 
                                        "Type": "Message", 
                                        "ID": "57cf806f02571", 
                                        "From": "17055551234", 
                                        "To": "123456", 
                                        "Body": "Subscribe" 
                                    }
                                    
                                

Response (Confirm Only)

                                    
                                    {
                                        "Status": "OK" 
                                    }
                                    
                                

Response (Confirm with Reply)

                                    
                                    {
                                        "Status": "OK" 
                                        "Body": "Thank you for subscribing."
                                    }
                                    
                                

Mobile Terminated (MT) messages are used to send messages from an application to a user via SMS.

The application provider will provide a delivery agent that can send JSON over HTTP as content-type application/json.

The JSON document must be posted to the API URL as the contents of the HTTP POST, i.e. the HTTP POST will deliver the document as content-type application/json and not as an embedded file inside an encoded form. This means that the delivery agent will need to access the HTTP POST content directly instead of using encoded form methods or tools for encoding name-value pairs.

API URLs: Specific URL(s) will be provided as part of your configuration, but they will follow the format: https://xxx.sunwire.ca/sms/

The application provider must provide Sunwire with a list of IP addresses that will require access to this API before it can be used.

The Request must contain the following attributes:

• From: The sender of the message. Numeric value of the long code or short code that will be sending.
• To: Numeric value of the recipient of the message
• Body: The contents of the message (must be UTF-8 encoded). NOTE: For cross-carrier programs, the reply should be limited to less than 137 characters (1-136) due to carrier restrictions on message size. This limit includes spaces, carriage returns, etc.
• Receipt: Supported on short codes only. Value must be ‘YES’ or ‘NO’ to request delivery receipt (See Delivery Receipt Report section for more information)
• Key: Optional: If configured, an API key will be required in the request for authentication purposes.

The Response will contain the following attributes:

• Status: ‘OK’ or ‘FAIL’
• Reason: Reason for fail status (Only if status is FAIL)
• ID: Unique identifier of the message (Only if status is OK)

Example MT SMS

Request

                                    
                                    POST /sms HTTP/1.1 
                                    Content-Type: application/json 
                                    Content-Length: 112

                                    { 
                                        "From": "123456", 
                                        "To": "17055551234", 
                                        "Body": "Your daily news.", 
                                        "Receipt": "yes” 
                                    }
                                    
                                

Response (Fail)

                                    
                                    {
                                        "Status": "Fail", 
                                        "Reason": "IP address not allowed."
                                    }
                                    
                                

Response (Success)

                                    
                                    {
                                        "Status": "OK" 
                                        "ID": "67df965509094"
                                    }
                                    
                                

Mobile Originated (MO) messages are messages sent to a short code or long code by a mobile user via MMS and the application will process the MO message. In an interactive program, the MO message is usually followed with an MT reply to the user. This reply can be sent at a later time with an MT transaction originated by the application provider. For short code it can be sent with the MO confirmation in the transaction originated by Sunwire.

Multimedia Messaging Service (MMS) messages are messages that contain media content, such as images, audio or video. When MMS is received by the Sunwire gateway, the file will be saved for 7 days and a link will be provided from which the file can be downloaded.

The application provider will provide a URL for a collection agent that can receive JSON over HTTP as content-type application/json and reply with a JSON response.

MO requests will come from the same addresses as your destination for MT messages (see below).

The Request will contain the following attributes:

• Type: ‘Message’ – Indicates the type of request
• ID: Unique identifier of the message
• From: The sender of the message (Note: The phone number format may vary from carrier to carrier. It will either be a 10 (national) or 11 (international) digit number)
• To: Short code or long code receiving the message
• Body: A message starting with ‘MMS received (link will expire in 7 days):’ followed by the download link for the MMS content.
• Key: Optional: When configured, a key will be provided in the request to authenticate with your application.

The Response must contain the following attributes:

• Status: ‘OK’ to mark the message as received. Remove it from queue. ‘FAIL’ to mark the message as received but rejected. Remove it from queue.

An HTTP error, empty response or status other than ‘OK’ or ‘FAIL’ will be treated as a delivery failure and the message will not be removed from the queue. Delivery failures will be re-attempted at exponentially increasing intervals, re-trying after 2 seconds, then 4, 8, 16, etc… up to a total of 12 re-tries (or approximately 2.5 hours of attempts), after which the message will be marked as failed and removed from the queue.

Example MO MMS

Request

                                    
                                    { 
                                        "Type": "Message", 
                                        "ID": "57cf806f02571", 
                                        "From": "17055551234", 
                                        "To": "123456", 
                                        "Body": "MMS received (link will expire in 7 days): 
                                                https://xxx.sunwire.ca/download-file.php?mms=1234&hash=abcd&filename=image.jpg&contenttype=image/jpeg" 
                                    }
                                    
                                

Response

                                    
                                    {
                                        "Status": "OK" 
                                    }
                                    
                                

Mobile Terminated (MT) messages are used to send messages from an application to a user via MMS.

Multimedia Messaging Service (MMS) messages are messages that contain media content, such as images, audio or video.

The application provider will provide a delivery agent that can send JSON over HTTP as content-type application/json.

The JSON document must be posted to the API URL as the contents of the HTTP POST, i.e. the HTTP POST will deliver the document as content-type application/json and not as an embedded file inside an encoded form. This means that the delivery agent will need to access the HTTP POST content directly instead of using encoded form methods or tools for encoding name-value pairs.

API URLs: Specific URL(s) will be provided as part of your configuration, but they will follow the format: https://xxx.sunwire.ca/mms/

The application provider must provide Sunwire with a list of IP addresses that will require access to this API before it can be used.

The Request must contain the following attributes:

• From: The sender of the message. Numeric value of the long code or short code that will be sending.
• To: Numeric value of the recipient of the message
• ContentName: Name of the multimedia content being sent, ex: example.png
• ContentType: Type of multimedia content being sent, as it would be represented in an HTTP Content-Type header, ex: image/png
• Content: The multimedia content to send, encoded in Base64.
• Key: Optional: If configured, an API key will be required in the request for authentication purposes.

The Response will contain the following attributes:

• Status: ‘OK’ or ‘FAIL’
• Reason: Reason for fail status (Only if status is FAIL)
• ID: Unique identifier of the message (Only if status is OK)

Example MT MMS

Request

                                    
                                    POST /sms HTTP/1.1 
                                    Content-Type: application/json 
                                    Content-Length: 112

                                    { 
                                        "From": "123456", 
                                        "To": "17055551234", 
                                        "ContentName": "example.png",
                                        "ContentType": "image/png",
                                        "Content": "iVBORw0KGgoAAAANSUhEU .... 0N0jbu3r48AAAAASUVORK5CYII="
                                    }
                                    
                                

Response (Fail)

                                    
                                    {
                                        "Status": "Fail", 
                                        "Reason": "IP address not allowed."
                                    }
                                    
                                

Response (Success)

                                    
                                    {
                                        "Status": "OK" 
                                        "ID": "67df965509094"
                                    }
                                    
                                

Mobile Terminated (MT) short code messages can request delivery status information. When a message is delivered (see MT section), either successfully or unsuccessfully, the destination carrier will generate a delivery receipt to be returned to the application provider.

Support for delivery receipts varies by wireless carrier. Delivery receipts may take up to 3 days to be returned since the default delivery retry window is 3 days when a subscribers phone is off or out-of-range.

Delivery receipts are sent to the same URL as MO messages except the ‘Type’ attribute will be ‘Report’ instead of ‘Message’. Optionally, a separate URL can be configured for receiving Delivery Receipts.

The Request will contain the following attributes:

• Type: ‘Report’ – Indicates the type of request
• ID: The original unique identifier of the message
• From:The original sender of the message
• To: The original recipient of the message
• Status: Indicates the final status of the message. The value is numeric and may be one of:
• 0 - DELIVERED - The message has been delivered.
• 1 - EXPIRED - The message could not be delivered.
• 2 - DELETED - The message has been deleted.
• 3 – IN-TRANSIT – The message is in-transit (intermediate status).
• 5 - UNDELIVERABLE / FAILED - The message could not be delivered.
• 7 - UNKNOWN - The status of the message is unknown.
• Reason: Indicates the reason the message has reached this status.

The Request will contain the following attributes:

• Status: Status should be set to ‘OK’ to mark the report as received to it from the queue.

An HTTP error will result in the report being left in the queue and retried at a later time until considered expired and deleted from the queue. The expiry time is carrier specific.

Example Report

Request

                                    
                                    { 
                                        "Type": "Report", 
                                        "ID": "67df965509094", 
                                        "From": "123456", 
                                        "To": "17055551234", 
                                        "Status": "0", 
                                        "Reason": "SM received by SME"
                                    }
                                    
                                

Response

                                    
                                    { 
                                        "Status": "OK" 
                                    }