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
| Conversation | Paths | With |
|---|---|---|
| Chat of a shipment | /v1/shipment/{shipment}/chat/message | Cargoplot's service team |
| Chat of an inquiry | /v1/inquiry/{inquiry}/chat/message | Cargoplot's service team |
| Customs of a shipment | /v1/shipment/{shipment}/customs/message | The 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
curl -H 'X-Cargoplot-Key: <token>' \
'https://api.cargoplot.com/v1/shipment/C2AE-XEE1/chat/message?limit=2'
{
"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 | |
|---|---|
id | The message's identifier: stable, and the same wherever the message appears. It is what marking read takes. |
reference | The reference of the shipment or inquiry. |
conversation | CONVERSATION_CHAT or CONVERSATION_CUSTOMS, for timelines that merge the two. |
text | The message as plain text. |
send_time, edit_time | When it was sent, and when it was last edited in the app. edit_time is null for a message that never was. |
author | Who wrote it: see authors. |
channel | CHANNEL_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. |
read | Whether you have read it: see read and unread. |
attachments | The 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.
| Kind | Who | name | user_id |
|---|---|---|---|
AUTHOR_KIND_ORGANIZATION | A member of your own organization | The person | The person's id for GET /v1/user/{user} |
AUTHOR_KIND_SERVICE | The service side of the conversation | A member of Cargoplot's service team by name, a partner on that side as the service team | Absent |
AUTHOR_KIND_EXTERNAL | A user of another client of Cargoplot, or an email sender Cargoplot could not match to a user or an organization | The person's name, or the name in the From header | Absent |
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:
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:
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
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 | |
|---|---|
text | Required. 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:
{
"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}/chatand/v1/shipment/{shipment}/customsare kept for it.
Refusals
| Status | When |
|---|---|
400 | A 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. |
404 | No such shipment or inquiry in your organization. Another organization's and one that does not exist answer the same. |
409 | A reply in a customs conversation that does not exist yet, or a request with the same Idempotency-Key that is still being processed. |
429 | The 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.