Skip to main content
Omnitracs Knowledge Base

CoPilot Send Message Details

This method is used to send a message to mobile device. The response will contain a Key that can be used to retrieve status of the message at a later time.

 

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

 

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

 

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

 

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

  • Was this article helpful?