SMS GATEWAY CONFIGURATION

Table Of Contents Table Of Contents

HTTP Messaging Gateway Interface document Version: 0.1

 January 17, 2023

 Message Gateway - Configuration The GTIGLOBAL Messaging Gateway is configured as part of the GTIGLOBAL Application server. The Partner must implement an interface to the GTIGLOBAL Provisioning API or manually configure the gateway using the GTIGLOBAL Control Panel Web UI. The configuration items include the following items that must be configured per GTIGLOBAL Message Gateway. ● Primary URL ● Secondary URL ● Client Security Token ● GTIGLOBAL Security Token Primary URL Secondary URL Required Optional The GTIGLOBAL Messaging Gateway uses this URL to send the HTTPs requests to the UCaas Server. This URL is always the first option used to deliver an Http Message. If the Primary Server returns an error. The GTIGLOBAL Messaging Gateway may try to deliver the message to the secondary server. See the section on Response Code Handling to understand when the secondary server is used. Client Security Token GTIGLOBAL Security Token Required Required Any Request delivered to the GTIGLOBAL Messaging Gateway must contain an Bearer Authorization Header containing this token. Any Request delivered to the UCaas server must contain an Bearer Authorization Header containing this token.

Termination URL When the UCaas server sends a request to the GTIGLOBAL Messaging Gateway. The URL needs to be as follows: https://messaging.mobileuc.global:8445/GTIGLOBALMsgGateway/v2/message Store And Forward In the case where a message fails to deliver to the UCaas Server. The GTIGLOBAL Application server could perform store and forward where the request is stored and delivered at a later time. The GTIGLOBAL Application server performs store and forward based on the error response received from the UCaas server. Any response considered a temporary failure is processed by the store and forward service. Refer to the section on Error Responses for information on which responses are considered permanent or temporary. A message that has been stored is tried again roughly every 30 seconds and will persist for 7 days. After which the message is discarded. These durations are controlled by GTIGLOBAL and cannot be changed by a customer. In order to maintain message order. After a subscriber’s message has been placed into the Store and Forward service. All future messages for this subscriber are automatically placed in the store. The messages are then delivered based on the re-try timer (30 seconds) and delivered based on the order placed in the store service.

Group Messaging Group Messaging is supported. Each recipient of the message is contained in the list of TO users. All Group messages delivered as an MMS type message. Origination Group Messaging When a subscriber originates a group message. The GTIGLOBAL Messaging Gateway delivers a single MMS message to the UCaas Platform. The To field contains the number of each participant that needs to receive the message. Termination Group Messaging When a 3rd party generates a group message. The UCaas Server is expected to send a message to the GTIGLOBAL Messaging Gateway for each GTIGLOBAL Subscriber (SIM) that is part of the group. The To field contains the number of each participant that needs to receive the message. The Owner field contains the number of the subscriber that receives this message.

Emojis Emojis and extended characters are supported. These will be encoded as UTF-8. There may be limitations on how these are rendered based on the handset. SMS Messages with binary UDH data ● SMS messages starting with User Data Header (UDH) binary data (examples: Apple iOS Activation Response messages used for iMessage, FaceTime, and iCloud) are not supported using this service. ● iMessages are not transmitted using SMS or MMS and are therefore not handled by the GTIGLOBAL messaging infrastructure. Security Https encryption is used. This requires proper valid public SSL certificates issued by CA. Authentication Bearer authentication is an HTTP authentication scheme that involves security tokens called bearer tokens. These tokens are to be included in every request as part of the Authentication Header. These tokens are data filled against the provisioning GTIGLOBAL Message Gateway. There is one token to be used when messages are sent to the UCaas server and a separate token used when sent to the GTIGLOBAL Messaging Gateway. Any message that is received for a subscriber that does not have a valid token receives a 401 Unauthorized response. ● Missing Authorization Header ● Received token Does not match the provisioned token ● Header is in the incorrect format. Messaging Fragmentation Fragmented messages are not supported. A POST-ed message event must contain the entire content for that message event. The GTIGLOBAL Messaging Gateway does not process fragment identification information, and will not re-order fragments into sequential order during delivery.

Media Messages Media images are encoded as base64 and contained in the JSON message body with the following limitations. ● 1 MB Limit ● Images, videos, audio, docs, and vcard are all supported by the API. Refer to Appendix A Supported Content Types for a complete list of supported types. NOTE: There may be limitations on how these are rendered based on the handset. ● A vCard file is encoded base64 string and delivered as an MMS Transmission Rates The API is restricted to 1 message per second.

API The API protocol is HTTPs using Bi-directional POSTs containing JSON content bodies. MMS/SMS Message Format Required Headers Field Authorization Value Bearer Auth-Schema Token Example Authorization: Bearer 1234 Contains the provisioned Security token Content-Type User-Agent Accept application/json;charset=UTF-8 application/json Content-Type: application/json;charset=UTF-8 GTIGLOBAL sends:mobileuc/v2.0 Accept : application/json

Json Content Body The following json format is used for all requests. Message Json Schema { "type" : "string", "domain" : "string”, "direction" : "string", "message" : { "id" : "string", "text" : "string", "subject" : "string", "to" : [ "string" ], "from" : "string", "owner" : "string", "media" : [{ "mimeType" : "string", "fileName" : "string", “encoding” : “string”, "data" : "string" }] } }

Json Field Definitions Parameter Requirement Type Description type required Identifies the type of message. Either SMS or MMS domain optional String Identifies the subscribers domain. If the domain is not specific the owner information is used to derive the domain. For an origination the value is always delivered and is based on the SIP domain assigned to the subscriber. direction required Identifies the message direction. message required Object Object defining the Message

Message JSON Object Parameter Requirement Type Description id required String UUID identifier that unique identities this message text optional String The text data of the SMS/MMS message. subject optional String Used to display the subject of the SMS/MMS to Required [String Array Object] The E164 number (or numbers) the message is sent to. For group MMS messages all participants are shown in this list. For non group messages this list only contains 1 number. All SMS messages are expected to only have 1 number. from required String The E164 number the message was sent from owner required String The E164 number assigned to the subscriber associated with this message. For origination messages this would always match the field. For termination messages this would always match one of the numbers in the List. Media optional Object Object for MMS

Media JSON Object mimeType Required if data is included. String Define the content of the data. Such as image/jpeg fileName Required if data is included. String Identifies the data object data Required String Data that is formatted as either text or base64 encoding Required if a base64 image is included. Defines the encoding format of the data

Response Code handling Handling of Status Codes Field Status Codes Description Store and Forward Secondary URL (if provisioned) 200-299 Successful Response No No 300-399 Redirection Response No No 401 Unauthorized 407 Proxy Authentication Required Indicates the authorization token is invalid. Yes No 408 Request TimeOut Yes Yes 429 To Many Requests Yes Yes 480 Temporarily Unavailable Yes Yes 481 Call or Transaction Does not Exist Yes Yes 4xx (All Other Responses) Permanent Failures No No 500 and Greater Server Internal Error Yes Yes

SMS/MMS Termination Processing The GTIGLOBAL Messaging Gateway determines if the received message is invalid. The following validation checks are provided and the error response generated. A message must have a subject, text or media Bad Request Type field missing or not set to sms or mms Bad Request Direction field missing or not set to orig or term Bad Request Missing Message Object Bad Request Message:Owner missing or does not match a number in the to list Bad Request When a base64 data is included and the mimeType or filename is empty Bad Request A subscriber cannot be identified based on the owner Not Found The identified subscriber cannot be associated with GTIGLOBAL Messaging Gateway. Method Not Allowed The identified subscriber does not messaging enabled on the SIM Method Not Allowed Missing Authorization Header Unauthorized Authorization Header does not start with “Bearer “ Unauthorized Authorization token does not match the associated token defined in the GTIGLOBAL Messaging Gateway. Unauthorized If the incoming request is rejected due to invalid data or invalid json. A json body may be added to the response to include a description as to why the message was not processed. This response body is optional and only included for certain error conditions. The response body has the following format. { } "status" "error" Parameter status : 404, : "error string" Requirement required Type Description integer error required String Http Response status code Description of the error.

Restrictions and Limitations ● IMessage and IMessage activations are not supported (handled to and from SIM by direct messaging channels to Apple). ● API is restricted to 1 message per second. ● DLR reports are not provided. ● 1MB limit for base64 encoding data. ● There may be limitations as to how Emojis and Images are rendered based on the handset. ● All numbers in the To,From, and Owner should be in E164 format.

Appendix A Supported Content Types

1.      Application 2. Text 3. Message 4. Multipart 5. Audio 6. Image 7. Video

Append B Examples For these examples, 16822826124 is the GTIGLOBAL Sim subscriber. 19728972222 is a PSTN user SMS Origination delivered to the UCaas Server Authorization: Bearer 123456 User-Agent: mobileuc/2.0 Content-Type: application/json;charset=UTF-8 Content-Length: 204 { } "type" : "sms", "domain" : "65.36.59.155", "direction" : "orig", "message" : { "id" : "b26d628f-2f4a-401b-85da-23f8e86ac79c", "text" : "A simple orig msg", "to" : [ "+19728972222" ], "from" : "+16822826124", "owner" : "+16822826124" }