Cargoplot APICargoplot API
API docs
OpenAPI spec

Messages

A shipment and an inquiry each have conversations, as they do in the app. You can read them from your own systems, post into them as the user your token belongs to, and mark them read, so the whole conversation lives in your own timeline and your team can answer without opening the app.

The conversations

ConversationPathsWith
Chat of a shipment/v1/shipment/{shipment}/chat/messageCargoplot's service team
Chat of an inquiry/v1/inquiry/{inquiry}/chat/messageCargoplot's service team
Customs of a shipment/v1/shipment/{shipment}/customs/messageThe shipment's customs agent

Each path reads with GET and posts with POST. Marking read has a path of its own, /v1/shipment/{shipment}/chat/read and the same for the inquiry's chat and the shipment's customs conversation, which takes a POST.

{shipment} and {inquiry} take the Cargoplot reference or the numeric id, as every other endpoint does. An inquiry has no customs conversation, so a customs path under /v1/inquiry answers 404.

A shipment booked from an inquiry has the inquiry's reference, and a conversation belongs to a reference. The chat of the inquiry and the chat of its shipment are therefore one conversation, and both paths return it.

Each list returns one conversation. The customs conversation appears in the app once it holds a message; until then its list is an empty page, not an error.

Reading a conversation

GET
/v1/shipment/C2AE-XEE1/chat/message
curl -H 'X-Cargoplot-Key: <token>' \
  'https://api.cargoplot.com/v1/shipment/C2AE-XEE1/chat/message?limit=2'
json
{
  "messages": [
    {
      "id": "d0qhk3bb1d1m1c7ehqkg",
      "reference": "C2AE-XEE1",
      "conversation": "CONVERSATION_CHAT",
      "text": "Your container is released and will be delivered tomorrow.",
      "send_time": "2026-10-01T08:00:00Z",
      "edit_time": null,
      "author": { "kind": "AUTHOR_KIND_SERVICE", "name": "Joan Clarke" },
      "channel": "CHANNEL_APP",
      "read": false,
      "attachments": []
    }
  ],
  "cursor": { "after": "eyJ..." }
}

Messages come newest first, so the latest N are limit=N. Pass order=ORDER_ASC to read forward. The page size and the cursors work as on every list, with one difference: a conversation can be empty, so an empty messages list is a normal answer.

Your own messages are listed, so the whole conversation is in one place.

Field
idThe message's identifier: stable, and the same wherever the message appears. It is what marking read takes.
referenceThe reference of the shipment or inquiry.
conversationCONVERSATION_CHAT or CONVERSATION_CUSTOMS, for timelines that merge the two.
textThe message as plain text.
send_time, edit_timeWhen it was sent, and when it was last edited in the app. edit_time is null for a message that never was.
authorWho wrote it: see authors.
channelCHANNEL_APP for a message written in Cargoplot, whether in the app, through this API or by an AI assistant, and CHANNEL_EMAIL for one that arrived by email.
readWhether you have read it: see read and unread.
attachmentsThe file_name and media_type of each file sent with the message.

Authors

author.kind says on which side of the conversation a message was written.

KindWhonameuser_id
AUTHOR_KIND_ORGANIZATIONA member of your own organizationThe personThe person's id for GET /v1/user/{user}
AUTHOR_KIND_SERVICEThe service side of the conversationA member of Cargoplot's service team by name, a partner on that side as the service teamAbsent
AUTHOR_KIND_EXTERNALA user of another client of Cargoplot, or an email sender Cargoplot could not match to a user or an organizationThe person's name, or the name in the From headerAbsent

On the service side, a forwarder, a customs agent or any other partner who writes in the conversation shows as the service team, never under their own name or organization. A user of another client who writes in it shows as external: by their own name, with no organization and no user_id. No field of a message carries an email address. The text of an emailed message can contain addresses that were written in it, such as the CC: lines Cargoplot puts at the top of one.

The kind follows the organization the author belonged to when the message was sent. A colleague who has left still shows as AUTHOR_KIND_ORGANIZATION, and their user_id may no longer be found at GET /v1/user/{user}. An author of an organization that has been deleted since shows as the service team.

Attachments

A message lists the name and the media type of each file. The files themselves cannot be downloaded through the API: open them in the app.

Polling for new messages

To follow a conversation, filter on send_time:

GET
/v1/shipment/C2AE-XEE1/chat/message
curl -H 'X-Cargoplot-Key: <token>' -G \
  'https://api.cargoplot.com/v1/shipment/C2AE-XEE1/chat/message' \
  --data-urlencode 'filter=send_time >= "2026-10-01T08:00:00Z"'

send_time takes an RFC 3339 time with >= only, and the value is quoted. Start each poll from the last send_time you saw minus a few minutes, and skip the messages whose id you already have. A message is listed a moment after it is sent, so one that is sent while you poll can carry a send_time from before the start of your poll. The order does not matter for polling.

Read and unread

Every message says whether you have read it, meaning the user your token belongs to. A message is read when it is at or before your read position in the conversation, or when you wrote it. The app's unread badge counts by the same rule.

Listing never marks anything read. To mark a conversation read, send the id of a message:

POST
/v1/shipment/C2AE-XEE1/chat/read
curl -X POST 'https://api.cargoplot.com/v1/shipment/C2AE-XEE1/chat/read' \
  -H 'X-Cargoplot-Key: <token>' \
  -H 'Content-Type: application/json' \
  -d '{"message": "d0qhk3bb1d1m1c7ehqkg"}'

That marks the message and every earlier one of the conversation as read, and answers 204 with no body. Send the newest message you have shown. Marking an older message than the last one you marked changes nothing, so the call can be repeated; a message cannot be marked unread.

Your position and your organization's both move, as when you read the conversation in the app. Your unread badge clears and a colleague's does not. What Cargoplot's service team has read does not change. A message that does not exist, or that belongs to another conversation, answers 400 and names the field.

Posting a message

POST
/v1/shipment/C2AE-XEE1/chat/message
curl -X POST 'https://api.cargoplot.com/v1/shipment/C2AE-XEE1/chat/message' \
  -H 'X-Cargoplot-Key: <token>' \
  -H 'Content-Type: application/json' \
  -d '{"text": "Could you confirm the pickup date?"}'

The message is written as the user your token belongs to, in the conversation of the path, and the people who are notified of a message written in the app are notified of this one: for a chat message Cargoplot's service team, for a customs message the shipment's customs agent, by email. It appears in the app at once.

The body has one key:

Key
textRequired. Plain text, at most 10,000 characters, and not only whitespace. It is kept as written: <b> is text here, not formatting.

Any other key answers 400, and message names it. The conversation comes from the path, never from the body.

The answer is 201 with the message, in the shape of the list. Keep it: a message reaches the list a moment after it is posted, so a list right after a post may not show it yet.

Messages are posted as text: files cannot be sent through the API.

Replying in the customs conversation

A message to the customs agent is a reply. It is accepted once the shipment has a customs agent and its customs conversation holds a message, which is when the conversation appears in the app. Before that, and on a shipment without a customs agent, it answers 409:

json
{
  "code": 10,
  "message": "there is no customs conversation to reply in: the shipment has no customs agent, or its customs conversation holds no message yet",
  "details": []
}

A client cannot start a customs conversation through the API.

Sending the same message again

Without an Idempotency-Key nothing is de-duplicated: the same text sent twice can be meant twice, and is posted twice. Send a key to make a retry safe. The same key and the same request answer the first message, with Idempotent-Replayed: true among the response headers, and post nothing.

A post and a read mark are writes, so they spend the write allowance.

What is not here

  • Downloading and sending attachments. A message lists its files by name and media type; the app is where they are opened.
  • Editing and deleting a message, and mentions, which belong to notes. These stay in the app.
  • The conversation itself, with an unread count and whether it is open or closed. The paths /v1/shipment/{shipment}/chat, /v1/inquiry/{inquiry}/chat and /v1/shipment/{shipment}/customs are kept for it.

Refusals

StatusWhen
400A query parameter, a cursor or a filter that is refused, as on every list; a text that is missing, empty, only whitespace or over the limit; a message that is not a message of this conversation; a key the endpoint does not know.
404No such shipment or inquiry in your organization. Another organization's and one that does not exist answer the same.
409A reply in a customs conversation that does not exist yet, or a request with the same Idempotency-Key that is still being processed.
429The write allowance is used up. See rate limits.

From an AI assistant

An AI assistant reads the conversations and, when you have let it make changes, posts and marks them read. What it reads is text written by people, by email too: it treats the text as quoted, never as an instruction.