CoPilot Send Message Details

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

CoPilot
Remote Integration

The user must also have been granted the capability 'Can send CoPilot messages' on the Customer portal.

Calling Interface

SendMessagesResponse sendMessages (SendMessagesRequest sendMessages) throws WSException

sendMessages: The SendMessagesRequest encapsulates the information required to send data to the mobile. Please see below of a description of the necessary fields required for CoPilot.
returns SendMessagesResponse
- The response indicates the successful acceptance of the message for processing. Status of the delivery of the message can be determined by calling getSentMessages.

SendMessagesRequest

Element	Type	Description	Required
Routing	RoutingType	Contains the routing information for this message. The Primary Service Id should be set to 'CPLT' and the Destination should be filled in with the Vehicle Unified Address, and/or Vehicle Id.	Yes
Message	SendMessageType	Container for Message	Yes

Element

Type

Description

Required

Routing

RoutingType

Contains the routing information for this message. The Primary Service Id should be set to 'CPLT' and the Destination should be filled in with the Vehicle Unified Address, and/or Vehicle Id.

Yes

Message

SendMessageType

Container for Message

Yes

Message (SendMessageType)

Element	Type	Description	Required
CorrelationId	string	Customer supplied tracking id. The maximum size of a correlation Id is 100 characters.	Yes
Payload	PayloadType	Container for actual payload in the message. The maximum size of a CoPilot message is 120KB.	Yes

Element

Type

Description

Required

CorrelationId

string

Customer supplied tracking id. The maximum size of a correlation Id is 100 characters.

Yes

Payload

PayloadType

Container for actual payload in the message. The maximum size of a CoPilot message is 120KB.

Yes

Instructions on how to encode and decode binary data

Sample XML Request

Only the SOAP body is shown. To see a sample SOAP Envelope and Header, click here.

<soap:Body>

<msgEip:SendMessagesRequest xmlns:baseEip="http://base.data.eip.omnitracs.com/1.0"

xmlns:msgEip="http://msg.data.eip.omnitracs.com/1.0"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://msg.data.eip.omnitracs.com/1.0 EIPMessage1.0.xsd ">

<Routing>

<Priority>3</Priority>

<Destination>

<Type>Vehicle</Type>

<CustomerAssignedId>MyTruck123</CustomerAssignedId>

</Destination>

<Service>

<Primary>

<Id>CPLT</Id>

</Primary>

</Service>

</Routing>

<Message>

<CorrelationId>MyCorrelationId1234</CorrelationId>

<Payload>

<Type>Binary</Type>

<Binary>52656A6F696E656420526F7574652061742053616E20446965676F2C2043410A392E3635204F4F52204D696C657300</Binary>

</Payload>

</Message>

</msgEip:SendMessagesRequest>

</soap:Body>

SendMessagesResponse

Element	Type	Description	Required
SendMessageAck	IncomingAckType	Acknowledgement Status for each message sent in the request	Yes

Element

Type

Description

Required

SendMessageAck

IncomingAckType

Acknowledgement Status for each message sent in the request

Yes

IncomingAckType

Element	Type	Description	Required
Id	IdType	Contains the unique keys for this message for both customer and platform . The Key to use for future reference is in the Key field of the Id element.	Yes
AckStatus	AckStatusType(int)	1 indicates the message was accepted, 0 indicates it was not. If 0, check the AckStatusReason for the reason why it was nacked.	Yes
AckStatusReason	string	Some text explaining the reason for a Nack	No
Destination	BaseResourceType	Indicates the Destination that this AckStatus is for. This will be a copy of the Destination that was specified in the request.	No

Sample XML Response

This example shows the response to a successful send request.
The Key that is returned in the response can be used in a subsequent call to get the status of the sent message.

<soapenv:Body>

<msgEip:SendMessagesResponse xmlns:baseEip="http://base.data.eip.omnitracs.com/1.0"

xmlns:msgEip="http://msg.data.eip.omnitracs.com/1.0"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://msg.data.eip.omnitracs.com/1.0 EIPMessage1.0.xsd ">

<SendMessageAck>

<Id>

<Key>1111-2222-3333-4444</Key>

<CorrelationId>MyCorrelationId1234</CorrelationId>

</Id>

<AckStatus>1</AckStatus>

<Destination>

<Type>Vehicle</Type>

<SystemAssignedId>105300001</SystemAssignedId>

<CustomerAssignedId>SR-VID1</CustomerAssignedId>

</Destination>

</SendMessageAck>

</msgEip:SendMessagesResponse>

</soapenv:Body>

Exceptions

0000 - There was a problem with the request, either the XML was invalid, or no soap operation was found.

0001 - Too many web service calls too quickly. Make the request later.

0002 - An Internal Error Occurred when trying to process the request. Please try again later.

0003 - Authentication Failed. Check the user credentials

0004 - Not Authorized (No Authorized Apps found)

0005 - WSSE Header Block missing or invalid

0006 - WSSE Header Username token is missing or invalid

1000 - No Data Found. Was not able to locate a required resource

1001 - Invalid Input, Something missing or incorrect in the request. Exception will indicate what the problem was.

1002 - Internal Error, some unknown error occurred. Retry later or call customer service.

1003 - Not authorized. Not authorized to use this service. Check the User Roles on the customer portal