Driver-dispatch messaging

Many fleets rely on direct driver-dispatch messaging to coordinate pickups, share updates, and clarify route instructions. By integrating your TMS with Samsara’s messaging APIs, you can let dispatchers send messages to drivers in real time, while receiving driver replies for a complete in-app communication workflow.

Why Integrate Messaging?

• Real-Time Dispatch Updates: Instantly contact drivers to adjust schedules, add stops, or confirm deliveries.
• Centralized Communication: Consolidate messages in your TMS, so dispatchers don’t have to juggle multiple tools.
• Two-Way Sync: Drivers send messages from the Samsara Driver App, which flow back into your TMS for visibility and record keeping.

1. Sending Messages

Use the POST /v1/fleet/messages endpoint to send messages to drivers.

curl --request POST 'https://api.samsara.com/v1/fleet/messages' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>>' \
  --data-raw '{
    "driverIds": [ 1654973 ],
    "text": "Hello driver, please confirm your next stop."
  }'

Required Fields

• driverIds: An array of Samsara driver IDs.
• text: The message contents (up to 2,500 characters).

Multiple Drivers

If you provide more than one driver ID, Samsara creates one message per driver behind the scenes.

Response Details

The create message response returns only basic data about each message:

{
  "data": [
    {
      "driverId": 555,
      "text": "This is a message."
    }
  ]
}

This does not include timestamps or sender info. To see those details (e.g., sentAtMs, sender), you must retrieve all messages using the GET /v1/fleet/messages endpoint.

2. Retrieving Messages

Use GET /v1/fleet/messages to list messages sent or received within a specific time window. By default, it returns the last 24 hours of messages if no parameters are provided.

curl --request GET 'https://api.samsara.com/v1/fleet/messages' \
     --header 'Authorization: Bearer <token>>'

Response Format

{
  "data": [
    {
      "driverId": 555,
      "isRead": true,
      "sender": {
        "name": "John Doe",
        "type": "dispatch"
      },
      "sentAtMs": 1462881998034,
      "text": "This is a message."
    },
    {
      "driverId": 555,
      "isRead": false,
      "sender": {
        "name": "Tyler Freckmann",
        "type": "driver"
      },
      "sentAtMs": 1462882998034,
      "text": "Acknowledged!"
    }
  ]
}

• sender.type can be "driver" or "dispatch".
• sentAtMs is the UNIX timestamp (milliseconds) of when the message was sent.
• isRead indicates if dispatch read (from the Samsara dashboard) or if the driver read (from the Driver app).

Query Parameters

If you want to see messages from the last week, for example:

curl --request GET 'https://api.samsara.com/v1/fleet/messages?durationMs=604800000' \
     --header 'Authorization: Bearer <token>>'

(That’s 7 days in milliseconds.)

3. Idempotency & Message Tracking

Because the POST /v1/fleet/messages endpoint doesn’t return a unique message ID, you should rely on sentAtMs, driverId, sender, and text from the GET /v1/fleet/messages response to detect duplicates:

1. Store the (driverId, text, sentAtMs, sender.type) tuple when you retrieve messages.
2. If you see the same tuple again, it’s likely a duplicate (unless your TMS intentionally sends identical content multiple times).

4. Reading Driver Replies

Drivers can reply from the Samsara Driver App, which appear as messages from "sender": { "type": "driver" }.

1. Continually poll GET /v1/fleet/messages for new messages.
2. Filter for messages with sender.type = "driver".
3. Present these replies in your TMS interface.

Alternatively, you can query more frequently (e.g., every 30 seconds) or rely on a job that runs every few minutes.

5. Marking Messages as Read

The API does not support marking dispatch messages as read. Dispatchers can see the read/unread status in the Samsara cloud dashboard, and drivers see it in the app. For TMS-based read status, you can track it yourself in your TMS database once you've processed the new messages.

Example Workflow

1. Look Up Driver ID

   • If your TMS only has external ID: GET /fleet/drivers/tms:driverXYZ.

2. Send Message to that driver ID

   cURL

   curl --request POST 'https://api.samsara.com/v1/fleet/messages' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer <token>>' \
        --data-raw '{
          "driverIds": [ 1654973 ],
          "text": "Route changed: proceed to 123 Main St."
        }'
   

3. Poll for Replies

   cURL

   curl --request GET 'https://api.samsara.com/v1/fleet/messages?durationMs=3600000' \
        --header 'Authorization: Bearer <token>>'
   

   • Check if the driver replied (driverId = "<driver ID>" and sender.type = "driver").

4. Store or Display the new reply in your TMS.

   • Potentially mark the message as “read” internally to avoid duplication.

Best Practices

The lack of unique message IDs can lead to duplicates if dispatchers send the same content repeatedly.

• Maintain an internal message ledger keyed by (text, sender, driverId, sentAtMs).
• Consider adding a random token to the text for automated messages to add entropy and enable idempotency.

• Driver Management Guide – to learn how to retrieve or create driver IDs.
• External IDs – for referencing drivers by custom IDs in your TMS.
• Messaging Endpoint Reference – for detailed specs on request/response fields.