WhatsApp

These tools cover four things around the WhatsApp assistant, Haitham: the numbers you have linked to him, whether tender alerts are sent to those numbers, the files a conversation is holding, and the organization's WhatsApp team groups. Linking a number has no tool: you link it from the phone itself, as Haitham, your assistant explains.

Your linked numbers

Both tools work on the numbers of the member who owns the connection, and only on them. A new number is linked from the phone itself, by messaging the assistant.

whatsapp_link_get

Lists the WhatsApp numbers you have linked, newest first. Each is masked and shows when it was linked, when it last messaged and whether alerts go to it. A member can have up to five numbers linked at once.

Read-only · scope whatsapp.read · all roles · Pro and Enterprise plans

No parameters.

Returns: linked (whether any number is linked), links (each with id, phone_masked, linked_at, last_message_at and alerts_enabled), chat_link (the address that opens a chat with the assistant), and the newest number's phone_masked, linked_at and last_message_at at the top level.

• The full number is never returned. The id is what whatsapp_link_revoke and whatsapp_alerts_set take. The top-level fields describe only the newest number, so read links when you have several.

whatsapp_link_revoke

Disconnects one of your WhatsApp numbers, or all of them when you send no link_id. The assistant loses access through that number at once. To connect again, message the assistant from that phone and open the confirmation link it replies with.

Deletes or overwrites data · scope whatsapp.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

Returns: success and revoked, which is one or all.

• Leaving out link_id disconnects every number, so name the one you mean. An ID that is not one of your active numbers answers 404.
• Disconnecting also deactivates the API key created for that number, which ends the assistant's access through it. Your other numbers keep working.

Alert delivery

Keyword and product alert matches always reach the in-app notifications. These two tools decide whether a copy is also sent to each linked WhatsApp number. The alerts themselves are managed with the tools in Alerts, notifications, tags and billing.

whatsapp_alerts_get

Shows, for each of your linked WhatsApp numbers, whether matched tender alerts (keyword and product alerts) are sent to it.

Read-only · scope whatsapp.read · all roles · Pro and Enterprise plans

No parameters.

Returns: The same reply as whatsapp_link_get. Read links, where each number shows id, phone_masked and alerts_enabled.

• Delivery also depends on a platform-wide switch that ProcDuck's operators control, and the tool does not report it. alerts_enabled: true means the number may receive alerts, not that one has arrived.
• A newly linked number has alerts switched on by default.

whatsapp_alerts_set

Turns WhatsApp delivery of matched tender alerts on or off, for one of your numbers or all of them. It sets only the per-number preference: the alerts themselves are unchanged, and their matches always reach the in-app notifications.

Changes data · scope whatsapp.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

{
  "link_id": "3f6c1d52-8a4e-4c7b-9d21-5e0b7a9c4f18",
  "alerts_enabled": false
}

Returns: success, updated (one or all) and alerts_enabled.

• An ID that is not one of your active numbers answers 404. With no link_id every number you have linked changes, and the call succeeds even when none is linked.
• Matches found while a number is muted are not sent when you turn delivery back on; only new matches are.

Held attachments

When someone sends a file over WhatsApp, the conversation holds it for 48 hours so the assistant can work with it. These tools find those files, read their text and delete the ones whose work is done. They are built for the assistant's own conversation on WhatsApp, where the conversation ID is filled in automatically; any other client sends it itself.

whatsapp_attachments_list

Lists the files sent over WhatsApp that the conversation is still holding, newest first: the ones not yet filed on a record. Use it to find "the file they sent", then read it with whatsapp_attachment_read, file it by sending its staged_ref to product_attachment_upload_url_create or manufacturer_attachment_upload_url_create, then the matching finalize tool, or import a sheet with sheet_import.

Read-only · scope whatsapp.read · all roles · Pro and Enterprise plans

Returns: attachments, each with ref (the reference starting with wa-staged:), file_name, mime_type, size_bytes and received_at, and count.

• At most the 20 newest files are listed. A file is removed automatically 48 hours after it arrives, and a file already filed on a record no longer appears.

whatsapp_attachment_read

Returns the text of a file the conversation is holding: a spreadsheet as a numbered table, a Word, PowerPoint or plain text file as lines, and a PDF's text layer page by page. Reading does not use the file up: it stays available for filing and importing afterwards.

Read-only · scope whatsapp.read · all roles · Pro and Enterprise plans

Returns: ref, file_name, mime_type, size_bytes, kind (sheet, document, text or pdf), truncated and text.

• The text is cut at 40,000 characters and truncated becomes true. A file over 20 MB answers 413, and it can still be filed by its reference without being read. A long sheet is imported with sheet_import, which reads every row.
• Photos, scanned PDFs, voice notes and video have no text this tool can return and answer 422. In the WhatsApp conversation itself the assistant sees photos and scans directly while they are held.
• Answers 404 when the conversation holds no file, or none with that reference.

whatsapp_attachment_discard

Deletes the stored copy of one held file once its work is done, so the assistant stops being shown it with every new message. Use it after the records the file was sent for are created, or when the sender says they are finished with it. It cannot be undone: only sending the file again brings it back.

Deletes or overwrites data · scope whatsapp.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

Returns: discarded (true), ref, file_name and a note saying the copy is gone.

• Discarding does not undo anything already read or written from the file while it was held. A file that is already filed, discarded or expired answers 404.
• Answers 400 when the reference is latest or not a valid reference.

Team groups

A team group is a WhatsApp group the organization creates for its team, and people join only through its invite link. A join request is approved automatically when the phone belongs to a team member (their registered mobile number or a linked WhatsApp number) and the group has room, up to 8 participants; every other request is rejected. These tools are for the owner and admins, and creating a group needs the platform to have groups switched on and room in your plan.

whatsapp_groups_list

Lists the organization's WhatsApp team groups with their status, invite link and participants, and says whether the platform has groups switched on and how much of your plan's group allowance is used. Each participant is marked as a team member or not.

Read-only · scope whatsapp.read · roles: owner, admin · Pro and Enterprise plans

No parameters.

Returns: enabled, max_participants, limit (-1 means unlimited), current (live groups) and groups, each with id, subject, description, status, invite_link, failure_reason, created_at, participant_count and participants (wa_id, joined_at, is_team_member, member_email).

• status is creating, active, suspended or failed, and deleted groups are not listed. A failed group shows its reason in failure_reason, and failed and deleted groups give their place back to your plan's allowance.

whatsapp_groups_create

Creates a WhatsApp group with the name you give. Creation is not instant: the group starts as creating and becomes active with an invite link once WhatsApp confirms, so list the groups again shortly after. Share the invite link with the team.

Changes data · scope whatsapp.write · roles: owner, admin · Pro and Enterprise plans

{
  "subject": "Acme Tenders Team"
}

Returns: success and group, the new group with status creating, answered with HTTP 201.

• Answers 403 when the platform has not switched groups on, and there is nothing to change on your side. Answers 402 plan_limit_reached with feature, limit and current when your plan's allowance is used up: Starter allows no groups, Pro allows 5 and Enterprise has no limit.
• If WhatsApp refuses the request (502), the group is recorded as failed with the reason and its place goes back to the allowance. Groups that are creating, active or suspended count against it.

whatsapp_groups_rename

Changes a group's name on WhatsApp. The group must be active.

Changes data · scope whatsapp.write · roles: owner, admin · Pro and Enterprise plans

{
  "group_id": "c9a1e7b4-52d0-4f36-8b1a-7d4e2f90a6c3",
  "subject": "Acme Tenders Team (Riyadh)"
}

Returns: success.

• Answers 404 when the group does not exist, 409 when it is not active yet, and 502 when WhatsApp refuses.

whatsapp_groups_reset_invite_link

Creates a fresh invite link for a group, and the previous link stops working at once. Use it when a link has reached people outside the team.

Deletes or overwrites data · scope whatsapp.write · roles: owner, admin · Pro and Enterprise plans

Returns: success and the new invite_link.

• The group must be active, or the tool answers 409. Answers 404 when the group does not exist and 502 when WhatsApp refuses.

whatsapp_groups_remove_participant

Removes one participant from a group, by phone number. The participant list updates when WhatsApp confirms the removal, a moment later.

Deletes or overwrites data · scope whatsapp.write · roles: owner, admin · Pro and Enterprise plans

{
  "group_id": "c9a1e7b4-52d0-4f36-8b1a-7d4e2f90a6c3",
  "wa_id": "966501234567"
}

Returns: success: the removal was requested. List the groups again to see it applied.

• Answers 404 when the group does not exist, 409 when it has not been created on WhatsApp yet, and 502 when WhatsApp refuses.
• Removing someone does not change the invite link. To stop old links working, use whatsapp_groups_reset_invite_link.

whatsapp_groups_delete

Deletes a group on WhatsApp for all its participants. This cannot be undone, and the group's place in your plan's allowance is freed.

Deletes or overwrites data · scope whatsapp.write · roles: owner, admin · Pro and Enterprise plans

Returns: success.

• A group that never reached WhatsApp, meaning a failed one or one still being created with no WhatsApp ID, is removed on the ProcDuck side only.
• Answers 404 when the group does not exist. If WhatsApp refuses the deletion, the tool answers 502 and the group stays.