What it is
A connected assistant knows nothing about your account in advance. It learns it the way a new dispatcher would: it asks Cargofy what objects there are, reads their fields, then acts. You only describe the job in plain words. This page shows what happens behind one request, so you know what to expect and how to ask.
How it fits together
1. The assistant learns what it can work with
On a new request, the assistant starts by calling entities-list. Cargofy answers with count and the list entities: every object your role can read and what each allows. In a shipper’s brand the objects look like this:
{ "slug": "shipment", "label": "Shipment",
"capabilities": ["query", "get", "create", "update"],
"operations": ["transfer-ownership", "add-bid", "finish-bidding"] }
{ "slug": "facility", "label": "Location",
"capabilities": ["query", "get", "create", "update"],
"operations": [] }
{ "slug": "dm:companies", "label": "Companies",
"capabilities": ["query", "get", "create", "update", "delete"],
"operations": ["link"] }Your data models come with the dm: prefix. capabilities lists what the assistant does with each object, operations its business actions.
2. It reads the fields before it writes
Before it creates or changes a record, the assistant calls entities-schema. Each field says whether it can be written, what type it is, its allowed values and how to fill it. For a shipment, the schema tells the assistant that the route goes into waypoints, the country is a lowercase code like ua, and the body type is one of a fixed list. That is why one request — “Create a shipment from Kyiv to Lviv” — is enough: the assistant fills the fields itself.
3. It finds records with filters, search and pages
entities-query finds records by conditions, by text or both. Every condition must match.
Not every field can be filtered. The schema lists for each field which conditions it supports and whether text search covers it, and the assistant builds the request from that. A shipment is filtered by number, your own code, status, final price, creation date and distance; a location by name and type. When a field does not support a condition, Cargofy says so, and the assistant changes the request.
One answer holds 20 records, up to 100, and says how many there are in total:
{ "count": 20, "total": 362, "next_cursor": "MjcwOA==" }Results come newest first. Each object can also be sorted by one field: shipments by creation date, trucks and trailers by plate, locations by name, trips by order date.
Say “show more” and the assistant asks for the next page. For a long list, say “export it to a file”: Cargofy saves the result as a JSON file in your account instead of putting it in the chat. truncated: true in the answer means the result was cut: narrow it with a condition. The file can be sent by email as an attachment, see Email.
4. It acts as you
Every action the assistant takes is saved in the activity log under your name, with the app’s name. A task it creates is created by you.
5. It reads errors and corrects itself
Cargofy answers a wrong request with an error that says what to fix, and the assistant tries again. For example:
- A filter with an unknown operator comes back with the list of valid ones.
- A task blocked without a reason comes back with a request for the reason.
- A location without a postal code comes back with the name of the missing field.
6. It stays inside your brand and your role
The assistant works in one brand and sees nothing in your other brands. Your role decides what it can do with records: an action your role does not allow fails with an error. Which actions are open to every member is in Limits.