Tools · Parcels

The Parcels module through the assistant: registering the parcel with a photo and notifying the member, following the queue, handling photos, marking the pickup, returning, discarding, reopening and deleting, and the member asking whether anything is waiting. There are 20 tools.

Each tool carries a badge: Read-only changes nothing, Changes creates or changes something right away, and Asks to confirm only acts after your yes to a summary. See Money and confirmation.

#In short

The space is created with create_space and module: "parcels", with the parcels argument for the settings; update_space changes only what you send and keeps the rest.

The team, here, is the owner, the admin, the moderator and finance. The roles are the routes' roles: the assistant never does more than the connected person could do on screen. The owner and the admin see all 20 tools; the moderator and finance, 14 (no discarding, reopening or deleting); the member, 4 (get_parcels_overview, get_parcel, do_i_have_parcels and mark_parcel_picked_up, on their own parcels).

The locker code is a secret. No team response carries it, and it is hidden in the MCP audit log; only do_i_have_parcels and get_parcel show it, to the recipient themselves. Whoever registers or fixes a parcel can set the code, never read it, and the assistant doesn't repeat it.

#The space settings

The parcels argument of create_space and update_space accepts:

#get_parcels_overview

Read-only

The space at a glance. The settings (locker mode and whether the member confirms their own pickup), how many parcels are waiting for you (mine.pendingCount) and, for the team, how many are pending and stalled. Minimum role: anyone who sees the space.

Ask like this: "How many parcels are stalled at the Downtown location?"

#get_parcel

Read-only

One parcel. With the photos, in signed links valid for 1 hour. The team reads any parcel in the community, without the code; the recipient reads theirs (a company's: any current employee of it), with the place and the code while it's waiting. Anyone else gets "not found". Minimum role: any.

Ask like this: "Show me Maria's parcel."

#do_i_have_parcels

Read-only

"Do I have a parcel?" Only yours and those of the company you work for now (recipientType: company, with recipientCompany): the pending ones (all) and the history (the latest), with where to pick up, the locker code while it's waiting and the photos (1-hour links). Show the code only to the person themselves. Minimum role: any.

Ask like this: "Do I have any parcel waiting?"

#mark_parcel_picked_up

Changes

Mark the pickup. The team marks it as STAFF (default, with the name of who came in picked_up_by_name, which defaults to the recipient) or THIRD_PARTY (the name is required). The recipient themselves marks it as SELF (on a company's parcel, any current employee), only if the space doesn't require team confirmation (otherwise, refused). The locker code is deleted. It's idempotent: on an already closed parcel, it returns already_closed: true. Minimum role: any (yours); moderator or finance (others').

Ask like this: "Mark Maria's parcel as picked up." · "I already picked up my parcel."

#search_parcel_recipients

Read-only

Who receives it. The space's members and the active companies with at least one employee with access to it, whose name starts with q (at least 3 letters, up to 8 results), with only id, type, name and initials. With type: member, the id is the recipient_member_id for register_parcel; with type: company, it's the recipient_company_id. Minimum role: moderator (or finance).

Ask like this: "Find Maria Souza so I can register a parcel." · "Find Acme."

#register_parcel

Changes

Register the parcel. For a member with access to the space or for a company with at least one employee with access: exactly one of recipient_member_id and recipient_company_id. It sends the recipient the notice email (with the thumbnail, if the space is set that way), in the community's time zone: the assistant says so. For a company, one e-mail goes to each current employee with access to the space, or only to the company's admins, if it chose so (parcel_notice_admins_only); a closed company gets no e-mail. kind is LETTER, PACKAGE or OTHER (the latter requires kind_label). locker_label and locker_pickup_code (4 to 12 characters, a secret) only apply if the space allows it. client_request_id makes a repeated call return the same parcel, with no second email. The same recipient, kind and tracking within 24 hours is refused (409), unless force is true. Minimum role: moderator (or finance).

Ask like this: "An Amazon package arrived for Maria Souza, in locker 12. Photo: [link]." · "A package arrived for Acme."

#list_pending_parcels

Read-only

The queue. The parcels waiting for pickup, newest to oldest, with recipient (recipientType member or company: recipient or recipientCompany, the other comes null), kind, sender, place, how long they've waited and stalled_days when past the deadline. Filters: kind, q (recipient or company name, sender, carrier or tracking), stalled, recipient_member_id, recipient_company_id, from and to (YYYY-MM-DD, in the community's time zone). Never the code (only has_locker_code). Minimum role: moderator (or finance).

Ask like this: "What has been stalled at the front desk for more than 3 days?"

#list_parcels

Read-only

The history. Same as list_pending_parcels, but with any status (RECEIVED, PICKED_UP, RETURNED, DISCARDED), filterable by status. Minimum role: moderator (or finance).

Ask like this: "Which parcels were returned this month?"

#update_parcel

Changes

Fix. Kind, sender, carrier, tracking, note, place and locker code (which is set again, never read) of a parcel that's waiting. A closed parcel can only be corrected by an owner or admin, and never the code. Each fix goes in the log. Minimum role: moderator (or finance).

Ask like this: "Fix the tracking on Maria's parcel to BR123456789."

#add_parcel_photo

Changes

Add a photo. Up to 5 per parcel, in private storage. The team; on a closed parcel, only the owner and the admin. Minimum role: moderator (or finance).

Ask like this: "Attach this photo to Maria's parcel."

#replace_parcel_photo

Changes

Replace a photo. Replaces a photo with the new file; the old one is deleted. Minimum role: moderator (or finance).

Ask like this: "Replace the parcel's first photo with this one."

#return_parcel

Changes

Return to the sender. Requires the reason. Nothing is deleted: the parcel stays in the history as RETURNED and the locker code is deleted. An already closed parcel answers 409. Minimum role: moderator (or finance).

Ask like this: "Return Maria's parcel to the sender: refused."

#remove_parcel_photo

Asks to confirm

Remove a photo. The file is deleted for good. On the first call it returns the summary and the confirmation code. Minimum role: moderator (or finance).

Ask like this: "Remove the parcel's second photo; it shows the address."

#discard_parcel

Changes

Discard. For a parcel nobody picked up. Requires the reason. Nothing is deleted: it stays as DISCARDED in the history, and reopen_parcel undoes it. It doesn't ask for confirmation, since it's reversible. Minimum role: admin (owner or admin).

Ask like this: "Discard Maria's parcel: expired without pickup."

#reopen_parcel

Changes

Reopen. Undoes a pickup, return or discard made by mistake: it goes back to RECEIVED, with the reason. The deleted code doesn't come back; set another with update_parcel. Minimum role: admin (owner or admin).

Ask like this: "Reopen Maria's parcel: the pickup was marked by mistake."

#delete_parcel

Asks to confirm

Delete a record made by mistake. It leaves the lists and the photos are deleted; the log keeps who and why. To close a parcel for real, use mark_parcel_picked_up, return_parcel or discard_parcel. On the first call it returns the summary and the confirmation code. Minimum role: admin (owner or admin).

Ask like this: "Delete the record of John's parcel: I registered it for the wrong person."

#list_parcel_lockers

Read-only

The space's lockers. In order, including inactive ones (active: false); only active ones can be chosen with locker_id. They matter when the space is in locker_mode: list. Minimum role: moderator (or finance).

Ask like this: "Which lockers does the Downtown unit have?"

#create_parcel_locker

Changes

Add a locker. Name up to 60 characters, unique in the space ignoring case (a repeat is refused, 409). position goes to the end if omitted; active is true if omitted. To use it, the space must be in locker_mode: list (update_space with parcels). Minimum role: admin (owner or admin).

Ask like this: "Add the locker Locker 12 to the Downtown unit."

#update_parcel_locker

Changes

Rename, reorder or activate/deactivate. Parcels already registered keep the name the locker had then. With nothing to change, the call is refused. Minimum role: admin (owner or admin).

Ask like this: "Deactivate the locker Locker 12."

#delete_parcel_locker

Asks to confirm

Remove a locker from the list. It can no longer be chosen; parcels that used it keep its name. To only hide it, use update_parcel_locker with active false. On the first call it returns the summary and the confirmation code. Minimum role: admin (owner or admin).

Ask like this: "Remove the locker Locker 12."

#Related

• Parcels
• Tools
• Money and confirmation
• Recipes