IsatData Pro API V1
Members
-
inner,constantForwardMessageStatesnumber
-
Enumerated type for State of Mobile-Terminated message
Properties:
Name Type Default Description SUBMITTED
number 0 RECEIVED
number 1 ERROR
number 2 DELIVERY_FAILED
number 3 TIMED_OUT
number 4 CANCELLED
number 5 -
inner,constantWakeupPeriodsnumber
-
Enumerated type for TerminalWakeupPeriod
Properties:
Name Type Default Description None
number 0 Seconds30
number 1 Seconds60
number 2 Minutes3
number 3 Minutes10
number 4 Minutes30
number 5 Minutes60
number 6 Minutes2
number 7 Minutes5
number 8 Minutes15
number 9
Methods
-
async,innercancelForwardMessages(auth, ids){Promise.<CancelForwardMessagesResult>}
/home/gbp/projects/isatdatapro-api/lib/api-v1.js, line 880 -
Requests cancellation of specific Mobile-Terminated message(s)
Name Type Description auth
ApiV1Auth Mailbox authenticataion
ids
number | Array.<number> Message id(s) to be cancelled
Returns:
Type Description Promise.<CancelForwardMessagesResult> see CancelForwardMessagesResult
-
innerdateToIdpTime(date){string}
/home/gbp/projects/isatdatapro-api/lib/api-v1.js, line 183 -
Returns an IDP message gateway formatted timestamp, defaults to 1970-01-01 00:00:00
Name Type Description date
Object A Javascript Date object
Returns:
Type Description string An IDP message gateway formatted timestamp 'YYYY-MM-DD hh:mm:ss' -
async,innergetBroadcastIds(auth){Promise.<BroadcastIdList>}
/home/gbp/projects/isatdatapro-api/lib/api-v1.js, line 987 -
Returns the list of Broadcast IDs associated with the Mailbox
Name Type Description auth
ApiV1Auth Mailbox authentication
Returns:
Type Description Promise.<BroadcastIdList> See BroadcastIdList
-
async,innergetErrorDefinitions(){Promise.<Array.<ErrorDefinition>>}
/home/gbp/projects/isatdatapro-api/lib/api-v1.js, line 399 -
Returns an array of error definitions based on an API error code
Returns:
Type Description Promise.<Array.<ErrorDefinition>> See ErrorDefinition
-
async,innergetErrorName(errorId){Promise.<string>}
/home/gbp/projects/isatdatapro-api/lib/api-v1.js, line 424 -
Returns a descriptive error name based on an API error code
Name Type Description errorId
string | number The ErrorID number returned by the API operation
Returns:
Type Description Promise.<string> An error name/description or 'UNDEFINED' -
async,innergetForwardMessages(auth, ids){Promise.<GetForwardMessagesResult>}
/home/gbp/projects/isatdatapro-api/lib/api-v1.js, line 723 -
Retrieves Mobile-Terminated messages submitted, by ID(s)
Name Type Description auth
ApiV1Auth Mailbox authentication see
ApiV1Auth
ids
number | Array.<number> An array of unique
ForwardMessageID
numbersReturns:
Type Description Promise.<GetForwardMessagesResult> The requested IDs and/or error code see GetForwardMessagesResult
-
async,innergetForwardStatuses(auth, filter){Promise.<GetForwardStatusesResult>}
/home/gbp/projects/isatdatapro-api/lib/api-v1.js, line 809 -
Retrieves Mobile-Terminated message state/status by ID(s) and optional time range NOTE: API should support ids as optional if startTimeUtc is specified
Name Type Description auth
ApiV1Auth Mailbox authentication see
ApiV1Auth
filter
ForwardStatusFilter A set of filter criteria for the query see
ForwardStatusFilter
Throws:
-
If filter does not include ids or startTimeUtc
- Type
- Error
Returns:
Type Description Promise.<GetForwardStatusesResult> see GetForwardStatusesResult
-
-
async,innergetIdpTime(){Promise.<Date>}
/home/gbp/projects/isatdatapro-api/lib/api-v1.js, line 248 -
Returns current UTC time at the MGS
Returns:
Type Description Promise.<Date> UTC time at the message gateway -
async,innergetIdpVersion(){Promise.<string>}
/home/gbp/projects/isatdatapro-api/lib/api-v1.js, line 118 -
Returns the Message Gateway System software version details
Returns:
Type Description Promise.<string> IDP Message Gateway System software version -
async,innergetMobileIds(auth, filter){Promise.<MobileIdList>}
/home/gbp/projects/isatdatapro-api/lib/api-v1.js, line 931 -
Returns a list of MobileID metadata
Name Type Description auth
ApiV1Auth Mailbox authentication
filter
Object optional Filters for ID (next ID for sequential query) and size
Name Type Description mobileId
string optional Set the only/first Mobile ID to query, if present
pageSize
number optional Maximum number of results to return (1..1000) defaults to 1000
Returns:
Type Description Promise.<MobileIdList> A response list with error code see MobileIdList
-
async,innergetReturnMessages(auth, filter){Promise.<GetReturnMessagesResponse>}
/home/gbp/projects/isatdatapro-api/lib/api-v1.js, line 513 -
Returns a response object containing retrieved messages that match the filter
Name Type Description auth
ApiV1Auth Mailbox authentication parameters see
ApiV1Auth
filter
FilterGetMobileOrigintated See
FilterGetMobileOrigintated
Returns:
Type Description Promise.<GetReturnMessagesResponse> See GetReturnMessagesResponse
-
innergetStateDefinition(state){string}
/home/gbp/projects/isatdatapro-api/lib/api-v1.js, line 768 -
Returns the enumerated string of the state value
Name Type Description state
number The state value returned in ForwardStatus
Returns:
Type Description string see ForwardMessageStates
-
innergetWakeupPeriod(period){string}
/home/gbp/projects/isatdatapro-api/lib/api-v1.js, line 595 -
Returns the enumerated string of the WakeupPeriod
Name Type Description period
number The TerminalWakeupPeriod
Returns:
Type Description string see WakeupPeriods
-
inneridpTimeToDate(idpTimeUtc){Date}
/home/gbp/projects/isatdatapro-api/lib/api-v1.js, line 235 -
Returns a Javascript Date object by converting an IDP message gateway formatted timestamp
Name Type Description idpTimeUtc
string An IDP message gateway formatted timestamp 'YYYY-MM-DD hh:mm:ss'
Throws:
-
If the passed in value is not a valid IDP datestamp
- Type
- Error
Returns:
Type Description Date Javascript Date object -
-
async,innersubmitForwardMessages(auth, messages){Promise.<SubmitForwardMessagesResult>}
/home/gbp/projects/isatdatapro-api/lib/api-v1.js, line 639 -
Submits Mobile-Terminated message(s) to remote modem(s)
Name Type Description auth
ApiV1Auth Mailbox authentication see
ApiV1Auth
messages
Array.<ForwardMessage> An array of messages see
ForwardMessage
Returns:
Type Description Promise.<SubmitForwardMessagesResult> An error code and metadata see SubmitForwardMessagesResult
Type Definitions
-
ApiV1AuthObject
-
An authentication pair for the IDP Messaging API V1, used for various operations
Properties:
Name Type Description accessId
string The mailbox unique access_id
password
string The mailbox password
-
BroadcastIdListObject
-
Response structure for a BroadcastID query
Properties:
Name Type Description errorId
number An error code for the get_mobiles_paged operation
broadcastGroups
Array.<BroadcastInformation> A list of
BroadcastInformation
objects -
BroadcastInformationObject
-
Metadata for a BroadcastID
Properties:
Name Type Description mobileId
string The unique Broadcast ID
description
string A description as provisioned on the MGS
-
CancelForwardMessagesResultObject
-
Response structure for cancellation request of Mobile-Terminated message(s)
Properties:
Name Type Description errorId
number An error code for the submit_cancelations operation
submissions
Array.<ForwardCancelation> The list of submitted messages to cancel
-
ErrorDefinitionObject
-
Describes an error code returned by the IDP Messaging API
Properties:
Name Type Description id
number The unique error number
name
string The unique name
description
string A verbose description of the error
-
FieldObject
-
A data structure containing various content and metadata within a message, present if a codec is provisioned on the Mailbox
Properties:
Name Type Argument Description name
string A descriptive name of the field, usually in camelCase notation
dataType
string <optional>
Supported types
'enum' is presented as string on decode, may be number or string on encode
'boolean' is presented as a string Value
'unsignedint', 'signedint' are presented as a string Value
'string'
'data' is a string, base64 encoded
'array' is an object with Elements instead of Value
'message' is an object with Message instead of Value
'dynamic' TBC
'property' TBCstringValue
string <optional>
Present if Type is 'enum', 'boolean', 'unsignedint', 'signedint', 'string', 'data'
elements
Array.<Object> <optional>
present if Type is 'array'
Properties
Name Type Argument Description index
number <optional>
index of the Elements array
fields
Array.<Field> <optional>
A list of field objects
message
Message <optional>
present if Type is 'message'
-
FilterGetMobileOrigintatedObject
-
A filter to apply when retrieving Mobile-Originated messages
Properties:
Name Type Argument Default Description startTimeUtc
string | Date <optional>
Start time (high water mark from prior nextStartUtc) ISO format 'YYYY-MM-DDTHH:MM:SSZ'
required if startMessageId is not present, ignored if startMessageId is presentstartMessageId
number <optional>
Start message ID (high water mark from prior NextStartID)
required if startTimeUtc is not presentendTimeUtc
string | Date <optional>
Optional end time if startTimeUtc is used, to return a range of messages rather than all since startTimeUtc
mobileId
string <optional>
Optional filter to retrieve only messages for a single terminal/modem
includeRawPayload
boolean <optional>
true A flag indicating if ReturnMessage.RawPayload should be returned
includeFieldType
boolean <optional>
true A flag indicating if ReturnMessage.Payload.Fields should include the Type property
-
ForwardCancelationObject
-
Metadata structure for a Mobile-Terminated message submission
Properties:
Name Type Argument Description errorId
number An error code returned by the MGS (0 = no errors; 115 = )
messageId
number A unique number generated by the network for tracking status of delivery (-1 if failed)
userMessageId
string <optional>
The optional user-supplied message ID to correlate with ForwardMessageID
mobileId
string A unique Mobile ID or Broadcast ID to send the message to (empty string if failed)
size
number <optional>
The over-the-air message size, in bytes
stateTimeUtc
string The ISO timestamp YYYY-MM-DDTHH:MM:SSZ of the last reported state of the message
mobileWakeupPeriod
number A [something] indicating if the modem is configured for low power sleep
scheduledSendTimeUtc
string A timestamp YYYY-MM-DDTHH:MM:SSZ for the scheduled message delivery to a low power modem
-
ForwardMessageObject
-
Data structure for a Mobile-Terminated (aka To-Mobile aka Forward) message
Properties:
Name Type Argument Description mobileId
string A unique Mobile ID or Broadcast ID to send the message to
userMessageId
string <optional>
An optional ID that may be used by your application to correlate to a system-assigned ForwardMessageID
payloadRaw
Array.<number> <optional>
Must be present if Payload is not present, an array of bytes as decimal values (0..255)
payloadJson
Message <optional>
Must be present if RawPayload is not present, see
Messsage
implies that a Message Definition File is used on the Mailbox -
ForwardMessageRecordObject
-
Metadata structure for a Mobile-Terminated message that has been submitted to the IDP Message Gateway System
Properties:
Name Type Description mobileId
string A unique Mobile ID or Broadcast ID to send the message to
payloadRaw
Array.<number> Must be present if Payload is not present, an array of bytes as decimal values (0..255)
payloadJson
Message Must be present if RawPayload is not present, see
Message
implies that a Message Definition File is used on the MailboxmessageId
number A unique number assigned by the MGS upon submission (get_forward_messages only)
mailboxTimeUtc
string A timestamp assigned by the MGS upon submission (get_forward_messages only)
stateTimeUtc
string A timestamp of the most recent State (get_forward_messages only)
state
number The current state of the message (get_forward_messages only)
errorId
number An error code for the record retrieval
isClosed
boolean An indicator if the message is completed/failed (get_forward_messages only)
referenceNumber
number System generated (get_forward_messages only)
-
ForwardStatusObject
-
Metadata for a submitted Mobile-Terminated message state
Properties:
Name Type Description errorId
number An error code for the Mobile-Terminated message
messageId
number The unique ID of the message assigned by the system
isClosed
boolean An indicator whether the message is no longer pending (delivered or failed)
referenceNumber
number stateTimeUtc
string The ISO timestamp YYYY-MM-DDTHH:MM:SSZ or Date of the reported state of the message
state
number The state/status code of the message
-
ForwardStatusFilterObject
-
A filter for requesting Mobile-Terminated message(s) states
Properties:
Name Type Argument Description ids
number | Array.<number> <optional>
Unique ForwardMessage.ID(s) to query, must be present if startTimeUtc is not
startTimeUtc
string | Date <optional>
The UTC timestamp YYYY-MM-DD hh:mm:ss for the start of retrieval, must be present if ids is not
endTimeUtc
string | Date <optional>
The UTC timestamp YYYY-MM-DD hh:mm:ss for the end of retrieval
-
ForwardSubmissionObject
-
Metadata structure for a Mobile-Terminated message submission
Properties:
Name Type Argument Description errorId
number An error code returned by the MGS (0 = no errors)
messageId
number A unique number generated by the network for tracking status of delivery
userMessageId
string <optional>
The optional user-supplied message ID to correlate with ForwardMessageID
mobileId
string A unique Mobile ID or Broadcast ID to send the message to
size
number The over-the-air message size, in bytes
stateTimeUtc
string The ISO timestamp YYYY-MM-DDTHH:MM:SSZ of the last reported state of the message
mobileWakeupPeriod
number A [something] indicating if the modem is configured for low power sleep
scheduledSendTimeUtc
string An ISO timestamp YYYY-MM-DDTHH:MM:SSZ for the scheduled message delivery to a low power modem
-
GetForwardMessagesResultObject
-
Structure of response to a retrieval of Mobile-Terminated message(s)
Properties:
Name Type Description errorId
number An error code for the get_forward_messages operation
messages
Array.<ForwardMessageRecord> An array of records see
ForwardMessageRecord
-
GetForwardStatusesResultObject
-
Response structure for a query of Mobile-Terminated message state(s)
Properties:
Name Type Description errorId
number An error code returned for the get_forward_statuses operation
more
boolean An indicator if additional statuses are available for retrieval
nextStartTimeUtc
string | null The ISO timestamp YYYY-MM-DDTHH:MM:SSZ for the next retrieval, null if More is false
statuses
Array.<ForwardStatus> | null An array of
ForwardStatus
if any were retrieved, otherwise null -
GetReturnMessagesResponseObject
-
The JSON structured response to the retrieving Mobile-Originated messages
Properties:
Name Type Description errorId
number An API error code (0 means no error)
more
boolean A flag indicating if more messages are available to retrieve
nextStartTimeUtc
string An ISO timestamp YYYY-MM-DDTHH:MM:SSZ for the next high water mark retrieval, empty string if none
nextStartId
number Unique ReturnMessage.ID of the next message available to retrieve from the MGS/Mailbox, -1 if none
messages
Array.<ReturnMessage> | null An array of
ReturnMessage
objects or null if none meet the filter/range criteria -
MessageObject
-
A set of metadata encapsulating data transported over the satellite network as a message
Properties:
Name Type Argument Description isForward
boolean <optional>
indicates if the message is Mobile-Terminated (aka To-Mobile aka Forward)
codecServiceId
number Service Identification Number the first byte of payload optionally used for codec
codecMessageId
number Message Identification Number the second byte of payload optionally used for codec
name
string A short name for the message, typically using camelCase notation
fields
Array.<Field> An array of Field types
-
MobileIdListObject
-
Structure of response to a MobileID query
Properties:
Name Type Description ErrorID
number An error code for the get_mobiles_paged operation
Mobiles
Array.<MobileInformation> A list of
MobileInformation
objects -
MobileInformationObject
-
Metadata for a queried MobileID
Properties:
Name Type Description mobileId
string The unique Mobile ID
description
string A description as provisioned on the MGS
lastRegistrationTimeUtc
string An ISO timestamp format YYYY-MM-DDTHH:MM:SSZ of the last Registration message
regionName
string The region/beam on which the last Registration message was received
-
ReturnMessageObject
-
A set of metadata relating to a Mobile-Originated (aka From-Mobile aka Return) message
Properties:
Name Type Argument Description messageId
number A unique number assigned by the MGS upon receipt of the message
receiveTimeUtc
string An ISO timestamp YYYY-MM-DDTHH:MM:SSZ when the message was received at the Satellite Access Station
regionName
string The name of the satellite regional beam the message was received on
size
number The size of the message received over-the-air, in bytes
mailboxTimeUtc
string An ISO timestamp YYYY-MM-DDTHH:MM:SSZ when the message is ready for retrieval in the Mailbox
mobileId
string The unique Mobile ID of the terminal/modem that sent the message
codecServiceId
number Service Identification Number the first byte of payload optionally used for codec
payloadRaw
Array.<number> <optional>
An array of bytes as decimal numbers (0..255)
present if requested in the get_return_messages operationpayloadJson
Message <optional>
A JSON data structured
Message
present if the MGS has decoded the raw payload using a Message Definition File on the Mailbox -
SubmitForwardMessagesResultObject
-
Structure of response to a Mobile-Terminated message(s) submission
Properties:
Name Type Description errorId
number An error code returned by the system (0 = no errors)
submissions
Array.<ForwardSubmission> An array of
ForwardSubmission
metadata for Mobile-Terminated messages submitted in the operation