Send Text Message
sendTextMessage
This web service is used to create a forward text message and queue it for transmission to a list of destinations (addressees). A global message handle is returned. Transactions indicating the disposition of transmitted messages will be available through ESS.
int sendTextMessage(String sender, String addressees, String replyTo, boolean returnReceipt, int priority, int macro, String body) throws WSException
- sender indicates the sender of the message. If this parameter is left blank the authenticated user will be the sender of the message.
-
addressees: is a comma delimited string containing the addressees (destinations) of the message. The addressees may be vehicles, groups of vehicles, users, groups of users or any combination thereof. A single message may be addressed to up to 20 addressees. If the addressee is indirect, attach the '@' symbol in front of the addressee.
SCAC/Vehicle ID's are supported. Valid SCAC/Vehicle ID format is:SCAC|Vehicle ID
Send the message to the specified vehicle
@SCAC|Vehicle ID
Send the message to the coverage of the specified vehicle
In both cases, the if the vehicle ID has leading zeros, they are required. Leading or trailing blanks for the SCAC or the Vehicle ID may be omitted.
Fleetwide addressing is supported. Possible values are:*ALLVEH
send message to all vehicles
*ALLUSR
send message to all users
-
replyTo indicates how reply messages from a driver will be routed. This has an effect on the routing of return messages when the driver uses the "Reply" key on the mobile terminal. These are referred to as "reply" messages. Drivers may also send "unsolicited" messages by creating a message and transmitting it without replying to a forward message. Possible values are:
*Personal
meaning that replies will be routed to the sender of the original forward message.
*Dispatch
meaning that replies will be routed to the coverage of the vehicle.
- returnReceipt a boolean that when set to true indicates that a notification indicating that the message has been read should be returned through ESS.
- priority an integer indicating the Message Priority of the forward message. See the panel below for a detailed description.
-
macro an integer indicating the forward macro template to which the message body applies.
00
Specifying 0 indicates a freeform forward message is being sent. In this case, the integrator is responsible for word-wrapping (via space-padding) if desired.
01 - 63
Specifying 1 - 63 indicates the macro template that is being referenced.
99
Specifying 99 indicates a freeform forward message is being sent, and that the integrator desires the message to be automatically word-wrapped on 38-character line boundaries prior to transmission. In this case, the integrator is relieved of the burden of inserting spaces manually in order to achieve word-wrapping.
- body The body of the message. The body of the message is a string containing a section of XML. The form of the body is described below.
Message Priorities
The priority controls how the NOC delivers a forward message to the vehicle and how the driver is notified as described below.
Group messages are transmitted 12 times over 85 minutes, regardless of priority except for Extended Sleepy. Extended Sleepy group messages are transmitted 20 times over 72 hours. Return message priorities include Normal and Emergency. Emergency appears when the driver marks a return message as "Priority."
|
Priority |
Transmission Attempts |
Driver Notification |
|
0 - Normal |
9 times over 35 minutes |
Unit beeps once, message waiting light goes on. |
|
1 - Important |
9 times over 35 minutes |
Unit beeps once, message waiting light goes on. Optional remote devices are activated. |
|
2 - Sleepy |
7 times over 18.25 hours |
Unit beeps once, message waiting light goes on. |
|
3 - Sleepy-Important |
7 times over 18.25 hours |
Unit beeps once, message waiting light goes on. Optional remote devices are activated. |
|
5 - Attention |
9 times over 35 minutes |
Unit beeps three times, message waiting light flashes. Optional remote devices are activated and remain active until the message is read. |
|
6 - Extended Sleepy |
10 times over 72 hours |
Unit beeps once, message waiting light goes on. |
|
9 - Emergency |
10 times over 35 minutes |
Unit beeps three times, message waiting light flashes. Optional remote devices are activated and remain active until the message is read. |
Unlike other types of mobile units, MCP50 and IVG units do not have a wakeup timer to scan for messages over long periods when the unit is off or out of coverage. If you send messages to MCP50 or IVG-equipped vehicles select the Sleepy, Sleepy Important (Sleepy+), or Extended Sleepy message priority, because it attempts transmission over a longer period of time. For example, the Extended Sleepy message priority allows a message to be sent on a Friday and received on a Monday when the truck ignition is turned on after being powered off for the weekend.
Authorization Requirements
The credentials supplied with this method call (as specified in the accompanying WS-Security header) must be authorized to the following application(s) and their associated role-based permissions.
Required Application Licenses
- Remote Integration
Required User Permissions
- Can use QTRACS
- Can send OTA freeform messages, if macro number is zero
- Can send OTA macro messages, if macro number is not zero
- Can send message to fleet, in order to send a message to all vehicles
- Can send message to all users, in order to send a message to all users
- Can send emergency priority messages, if the priority parameter is set to emergency
- Can send attention messages, if the priority is 5
- If message is to a vehicle, can see data for all assets OR the vehicle must be in the user's coverage or global group
Customer integrators are authorized to their own company's data only.
Body Parameter
When sending the contents of the body parameter, any XML characters (<,>,',",&) must be escaped. If you are creating J2EE or .Net web service clients the escaping is performed automatically. However, some clients that you may develop may not do the encoding automatically for you so the string being sent will have to be encoded. Sample message body formats are shown further down on this page.
The sendTextMessage web service accepts two forms in the body parameter.
- Forward freeform text message. Using the <msgBody> element.
- Forward Macro message. Using the <macroBody> element.
Forward Freeform Text Message
When sending free form text messages, you should enclose the contents of the text message in a <msgBody> element. The following sample shows what the <msgBody> element should look like for a simple text message. *Note: For readability the XML characters have not been escaped.
|
|
If you want to split the text message onto separate lines, you must pad each line with 38 spaces so that the text following the spaces will appear on the next line. You will not be charged for the blank characters. The following samples shows what the <msgBody> element should look like when sending a text message with padding spaces to force a new line. *Note: For readability the XML characters have not been escaped.
|
|
Optionally, you may send a free form text message that wraps onto multiple lines and still maintains readability. Using a macro of 99 will wrap the message onto multiple lines without splitting words between lines. This ensures that the text-to-speech function of mobile units will read the message correctly without burdening the user to pad each line with extra spaces. When using a macro of 99 do not include the <macroBody> element.
|
|
Note: The sendTextMessage web service does not support sending freeform text messages using Macro 0 and the <macroBody> element.
A complete sample request for a freeform message is shown at the bottom of this page.
Forward Macro Message
Forward macros are conveyed via an element call <macroBody>.
The following sample shows what the <macroBody> element should look like for a macro message.*Note: For readability the XML characters have not been escaped.
|
|
The elements within <macroBody> are determined by the dictionary entries and field groups defined in the corresponding macro template. All dictionary entries and group entries defined on the macro template must be provided.You do not have to provide any label elements defined in the corresponding macro template.
Dictionary entry = <macroField>
Dictionary entries are conveyed via an element called <macroField>. The <macroField> (dictionary entry) elements must be provided in the same order as defined in the corresponding macro template. While XML itself is not order-dependant, the underlying parsing logic on the server expects the fields to be passed in a left-to-right, top-to-bottom order as defined in the corresponding macro template.
Each <macroField> element has a "dictTag" attribute whose value is a unique identifier of the dictionary entry being conveyed. A dictionary entry's unique identifier is referenced by three different names: "Integration tag" (shown on the QTRACS/Portal UI), "xmlTag" (getDictionaryEntry WS) or "dictTag" (getMacro WS). We use the "dicTag" name stored in the dictionary as as an attribute of an XML element while the macro data itself is delivered as the "payload". The advantage of this approach is that changes to the macro template definition and its associated dictionary entires do not require changes to the XSD (schema), and therefore issues like dynamic XSD construction, security, and versioning are avoided. Interoperability best practices suggest implementing only simple types in an XML document; therefore, all elements shall be defined as a 'string' type. Since all elements are represented as strings and the XSD treats macro bodies in a generic way (i.e. data type is not conveyed) there is no need for the XSD to change as dictionary fields are added, removed, or modified.
Field group = <fieldGroup>
Field groupings are explicitly conveyed via a dedicated grouping element called <fieldGroup>. Each <fieldGroup> element has a "dictTag" attribute whose value describes the name / nature of the field grouping. Field groups with identical dictionary tag attribute values may be repeated within a given macro. Such identical groups are only distinguished by the data contained within their <macroField> elements. For example, if a macro contained two field groups defining stop information, then each stop group could be distinguished by the inclusion of a "stopNumber" macro field within each group. It is the responsibility of the person designing the macro template to include such differentiating information (if needed) in the event of repeating macro field groups.
A complete sample request for a macro message is shown at the bottom of this page.
Validation of <macroField> values:
All dictionary entries have a macro field type (a.k.a. mobile data type). The macro field type restricts the type of data that can be entered into a dictionary entry. See the list of supported macro field types for details.
The sendTextMessage web service validates the values of the <macroField> (dictionary entry) elements based on their macro field type. It will also validate that all fields that are declared mandatory in the macro template are included.
Exceptions
002 Required field not specified.
003 Company not authorized for access through integration.
004 Sender is not authorized.
005 Destination must be specified.
006 Invalid Reply to.
007 Invalid Return receipt.
008 Message body cannot be empty.
009 Invalid priority specified.
010 Invalid macro number specified.
011 User is not authorized to send messages to all vehicles.
012 Invalid destination.
013 Destination not found.
014 Maximum of 20 destinations may be specified.
015 Message not created.
016 Cannot send a message to a vehicle without a device.
017 User is not authorized to send OTA freeform messages.
018 Message body exceeds allowable line limit.
019 Wildcard destination cannot be indirect.
020 Only one destination allowed when there is a wildcard destination.
021 Message body contains one or more illegal chars: '~|{}^[]
022 User is not authorized to send OTA macro messages.
023 Macro definition status has errors.
024 User is not authorized to send messages to all users.
025 Parsing of message body failed.
026 Macro message body does not match macro message definition.
027 Macro field is invalid.
028 Failure sending message. A specific reason will be returned to the client for message failure.
029 Route dispositions through OTS is invalid.
Sample sendTextMessage Request for Macro Message
|
|
Sample sendTextMessage Request for Freeform Message
|
|
Sample sendTextMessage Request for Freeform Message with Macro 99
|
|
Sample sendTextMessage Response
|
|