@funnelchat-hq/sdk 0.3.0 → 0.3.2

package/README.md

@@ -40,16 +40,14 @@ Is the phone someone else's? Send them a page that shows the QR instead: `const
 
 ### 3. Send a message
 
-The contact goes first; then the text, from your number:
+One call, from your number to a phone (with country code, digits only):
 
 ```ts
-const contact = await funnelchat.contacts.create({ phone: '5491100000000', name: 'Ana' }); // with country code, digits only
-
-const { message } = await funnelchat.messages.sendDirect({ device_id: device.id, contact_id: contact.id, text: 'Hi Ana!' });
-console.log(message.id, message.status); // 1002 'queued'
+const { message } = await funnelchat.messages.sendDirect({ device_id: device.id, phone: '5491100000000', text: 'Hi Ana!' });
+console.log(message.id, message.contact_id, message.status); // 1002 2001 'queued'
 ```
 
-The answer is the queued message: accepted is not delivered yet. With an official number, free text only goes within 24 hours of the contact's last message; after that, an [approved template](#templates).
+If that phone is not a contact yet, it is created in the workspace of your key; `message.contact_id` is its id. The answer is the queued message: accepted is not delivered yet. With an official number, free text only goes within 24 hours of the contact's last message, so the first message to a new contact is an [approved template](#templates).
 
 ### 4. Know when it was read
 
@@ -71,7 +69,7 @@ app.post('/hooks/funnelchat', express.raw({ type: 'application/json' }), (req, r
 });
 ```
 
-The status goes `sent`, `delivered`, `read` (or `failed`, with `error`). You can also ask for it: `(await funnelchat.messages.get(contact.id, message.id)).status`. More in [Webhooks](#webhooks).
+The status goes `sent`, `delivered`, `read` (or `failed`, with `error`). You can also ask for it: `funnelchat.messages.get(contactId, messageId)`, with `message.contact_id` and `message.id`. More in [Webhooks](#webhooks).
 
 ## Receive messages
 
@@ -90,10 +88,10 @@ if (event.type === 'message.received') {
 
 ## Groups
 
-List the groups of your numbers and send a message to one by its `uid`:
+Start from the groups your number is in, read live from WhatsApp, and write to one by its `uid`:
 
 ```ts
-for await (const group of funnelchat.groups.list()) {
+for await (const group of funnelchat.groups.listByDevice(device.id)) {
   console.log(group.uid, group.name); // '120363000000000001@g.us', 'Customers'
 }
 
@@ -104,9 +102,18 @@ const { action_id } = await funnelchat.groups.sendMessage('120363000000000001@g.
 });
 ```
 
+To learn who joins and leaves a group, follow it once:
+
+```ts
+const { data: followed } = await funnelchat.groups.follow('120363000000000001@g.us', { device_id: device.id });
+console.log(followed.imported, followed.is_admin); // true, true
+```
+
+- The live list is reused for a minute per number, so a group just created in WhatsApp can take that long to show. A group already in your account brings `device_id`; `funnelchat.groups.list()` lists those.
+- Writing to a group that is not in your account follows it first, with the same rules: a number that is not admin of the group answers `422 device_not_group_admin` and nothing is imported. Following needs **Groups and campaigns → Manage groups** (`403 import_permission_required`), takes up to 5 groups per number per minute (`429 import_rate_limited`, with `retryAfter`) and works with QR numbers only (`422 provider_unsupported` with an official one). `followed.imported` is `false` when the group was already in your account.
 - The message goes out in the background: `group_action.completed` (with `action.uuid` equal to `action_id`) or `funnelchat.groups.retrieveAction(action_id)` tell you how it went. A file goes as `type: 'image'` (or `video`, `audio`, `document`) with its `https` `media_url`.
-- Who joins or leaves arrives by `group_participant.joined` and `group_participant.left`: `group`, `participant` (`identity`, `identity_type`, `name`) and `campaign`, `null` for a group without a campaign.
-- Permissions: **Groups and campaigns → View** to read and **Groups and campaigns → Send** to send.
+- Who joins or leaves a followed group arrives by `group_participant.joined` and `group_participant.left`: `group`, `participant` (`identity`, `identity_type`, `name`) and `campaign`, `null` for a group without a campaign.
+- Permissions: **Groups and campaigns → View** to read, **Groups and campaigns → Send** to send and **Groups and campaigns → Manage groups** to follow.
 
 ## Workspaces
 
@@ -148,7 +155,7 @@ CommonJS: `const { Funnelchat } = require('@funnelchat-hq/sdk');`. Every request
 | `funnelchat.contacts` | `list`, `create`, `upsert`, `retrieve`, `update`, `delete`, the tags and fields of a contact, `metaWindow` (the 24-hour window), notes. |
 | `funnelchat.messages` | `send`, `sendDirect`, `sendForm`, `sendContactCard`, `forward`, `get` (one message by id), `list` (the history of a contact), `react`, `removeReaction`. |
 | `funnelchat.templates` | `list`, `create`, `retrieve`, `update`, `quickReplyButtons`, `send`, `delete`. |
-| `funnelchat.groups` | `list`, `retrieve`, `listByDevice`, participants and their joins and leaves, messages, `sendMessage` and `retrieveAction`. |
+| `funnelchat.groups` | `listByDevice` (a number's live groups), `follow`, `list`, `retrieve`, participants and their joins and leaves, messages, `sendMessage` and `retrieveAction`. |
 | `funnelchat.webhooks` | Subscriptions (`list`, `create`, `retrieve`, `update`, `delete`, `test`, `listDeliveries`), the catalog (`events`), `verify` and `constructEvent`. |
 | `funnelchat.conversations` | `list`, `update`, counters, mark everything as read or unread. |
 | `funnelchat.forms` | WhatsApp forms: `list`, `templates`, `create`, `retrieve`, `update`, `delete`, `createVersion`, `sync`, `publish`, numbers, `versions`, answers and `metrics`. |
@@ -168,7 +175,8 @@ A key has the permissions ticked when it was created. The panel groups them by a
 | Create contacts | **Contacts and conversations → Edit** |
 | Send messages and templates | **Contacts and conversations → Send** |
 | Read groups | **Groups and campaigns → View** |
-| Send to a group | **Groups and campaigns → Send** |
+| Send to a group | **Groups and campaigns → Send** (and **Groups and campaigns → Manage groups** for one not in the account yet) |
+| Follow a group | **Groups and campaigns → Manage groups** |
 | Webhook subscriptions | **Notifications (webhooks) → View** to read, **Notifications (webhooks) → Manage** for the rest, plus **View** of the area of each event |
 
 ### Send a message
@@ -191,10 +199,10 @@ if (window.is_open) {
 }
 ```
 
-- `contacts.create({ phone })` (7 to 15 digits) answers the existing contact when that phone is already there. A contact has to exist before you send it anything.
+- **By phone, without `contact_id`:** `sendDirect` and `templates.send` take `phone` (7 to 15 digits, with country code) and create the contact in the workspace of your key when it does not exist yet, as `contacts.upsert` would; the contact stays even if a rule then stops the send. With an official number you can send `whatsapp_id` (Meta's id of the person, such as `US.13491208655302741918`) instead of `phone`; with a QR number that is a `422`. A phone that is a contact of another workspace of your account answers `404`, and nothing is created or sent. With `contact_id` too, `phone` or `whatsapp_id` must be that contact's: otherwise `422 recipient_mismatch`. Creating the contact takes **Contacts and conversations → Edit**, which **Send** includes.
 - `message.id` is the same `message_id` of `message.status_changed`. With it, `funnelchat.messages.get(2001, message.id)` tells you how it is going: `status` moves from `queued` to `sent`, `delivered`, `read` or `failed`, and a `failed` one carries `error` (`code`, `title` and `reason`).
 - `client_reference` (1 to 64 visible ASCII characters, no spaces) comes back in the history of the contact and in `message.status_changed`.
-- `send` is `POST /api/v1/contacts/{contact}/message` and checks the `phone` (or `whatsapp_id`) of the body against the contact of the route: when it does not match, `422 recipient_mismatch`. `sendDirect` is `POST /api/v1/message/send-message`, with `device_id` and `contact_id` in the body.
+- `send` is `POST /api/v1/contacts/{contact}/message` and checks the `phone` (or `whatsapp_id`) of the body against the contact of the route: when it does not match, `422 recipient_mismatch`. `sendDirect` is `POST /api/v1/message/send-message`, with `device_id` and the recipient (`phone`, `whatsapp_id` or `contact_id`) in the body.
 - Contact cards (`sendContactCard`) return `{ messages }`, one per card; a forward (`forward`) one item per destination with its `message` (or `null` when that destination was blocked); a template (`templates.send`) and a form (`sendForm`) `{ message }`.
 
 **A file by URL.** `file` is the URL of the file. When it does not end in a known extension (a signed URL, or one without extension), say what it is with `file_type` and, for a document, the name it arrives with:
@@ -217,8 +225,7 @@ Without `file_type`, a URL without a known extension answers `422` with `errors.
 
 ```ts
 const { message } = await funnelchat.templates.send(3, '45', {
-  phone: '5491100000000',
-  contact_id: 2001,
+  phone: '5491100000000',                  // a new phone becomes a contact, as with sendDirect
   template_variables: { body: ['Lucía'] }, // the body variables, in order
 });
 ```
@@ -527,12 +534,11 @@ const funnelchat = new Funnelchat({ apiKey: '1|fc_live_sandbox', baseUrl: 'http:
 
 ### Pending of the spec
 
-The types come from the full unified spec of the developer portal (`spec/funnelchat.json`; where it came from, in `spec/procedencia.json`: developers-portal c90565e4 of 04-11-2026, with the areas at accounts v1.5.97, conversations v1.19.7 and communities v2.35.5). What production has and that spec does not describe, or describes otherwise than production answers, lives in a separate layer, `spec/pending.json`, which generation applies **only while the spec does not bring it**, or still says exactly what the entry corrects; each entry cites the production code it was read in:
+The types come from the full unified spec of the developer portal (`spec/funnelchat.json`; where it came from, in `spec/procedencia.json`: developers-portal 99928866 of 05-11-2026, with the areas at accounts v1.5.97, conversations v1.19.21 and communities v2.35.7). What production has and that spec does not describe, or describes otherwise than production answers, lives in a separate layer, `spec/pending.json`, which generation applies **only while the spec does not bring it**, or still says exactly what the entry corrects; each entry cites the production code it was read in:
 
-- a message to a group and its action (`groups.sendMessage`, `groups.retrieveAction`, `group_action.completed`): the spec was built with the group actions off;
-- the events of the account (`device.*`, billing, subscriptions, monthly active contacts) and some of groups (`group.message_received`, `group.reaction_added`, `group.full`, `group_action.failed`, the join requests): the API publishes them in its catalog (`webhooks.events()`), not in the spec;
+- the events of the account (`device.*`, billing, subscriptions, monthly active contacts) and some of groups (`group.message_received`, `group.reaction_added`, `group.full`, `group_action.completed` and `.failed`, the join requests): the API publishes them in its catalog (`webhooks.events()`), not in the spec;
 - WhatsApp forms (except sending one) and `webhooks.rotateSecret`;
-- where the spec contradicts production: what a send answers (`{ message }`, never `null`), the body of `devices.qr`, the items of `templates.list`, the answer of `webhooks.update`, and the events the spec only shows by one example (`message.received`, `message.status_changed`, `whatsapp_form.completed`, `group_participant.joined` and `.left`).
+- where the spec contradicts production: what a send answers (`{ message }`, never `null`), the body of `devices.qr`, the items of `templates.list`, the answer of `webhooks.update` and of `groups.retrieveAction`, and the events the spec only shows by one example (`message.received`, `message.status_changed`, `whatsapp_form.completed`, `group_participant.joined` and `.left`).
 
 `src/pending/` has what is not OpenAPI (the `workspace_id` of every event) and `src/core/error-codes.ts` the error codes.
 

package/dist/index.cjs

@@ -388,7 +388,13 @@ var GROUP_ACTION_ERROR_CODES = {
   /** 422: that `type` cannot be sent to this group by this number. */
   unsupported_type: 422,
   /** 429: the number has 50 group actions open. Wait for some to finish; not worth retrying. */
-  too_many_pending_actions: 429
+  too_many_pending_actions: 429,
+  /** 403: following a group (also by writing to one not in the account) needs **Groups and campaigns → Manage groups**. */
+  import_permission_required: 403,
+  /** 429, with `Retry-After`: the number already followed 5 groups this minute. */
+  import_rate_limited: 429,
+  /** 409: another call is following the same group right now. */
+  import_in_progress: 409
 };
 var IDEMPOTENCY_ERROR_CODES = {
   /** 422: the key was already used with another body. Use a new key for a new resource. */
@@ -594,14 +600,29 @@ var routes = [
   { "method": "GET", "path": "/api/v1/forms/families/{familyId}/versions", "operationId": "pendingForms.versions", "domain": "conversations", "permission": "conversations:read", "tag": "WhatsappForm", "summary": "The versions of a form", "pending": true },
   { "method": "GET", "path": "/api/v1/forms/templates", "operationId": "pendingForms.templates", "domain": "conversations", "permission": "conversations:read", "tag": "WhatsappForm", "summary": "Templates to start a form", "pending": true },
   { "method": "GET", "path": "/api/v1/groups", "operationId": "group.index", "domain": "communities", "permission": "communities:read", "tag": "Grupos", "summary": "Listar grupos", "pending": false },
+  { "method": "POST", "path": "/api/v1/groups", "operationId": "apiGroupAction.create", "domain": "communities", "permission": "communities:operate", "tag": "Acciones de grupo", "summary": "Crea un grupo", "pending": false },
   { "method": "GET", "path": "/api/v1/groups/{group}", "operationId": "group.show", "domain": "communities", "permission": "communities:read", "tag": "Grupos", "summary": "Ver un grupo", "pending": false },
   { "method": "GET", "path": "/api/v1/groups/{group}/actions", "operationId": "group.actions", "domain": "communities", "permission": "communities:read", "tag": "Grupos", "summary": "Listar las acciones de sesi\xF3n sobre un grupo", "pending": false },
+  { "method": "POST", "path": "/api/v1/groups/{group}/admins", "operationId": "apiGroupAction.promoteAdmins", "domain": "communities", "permission": "communities:operate", "tag": "Acciones de grupo", "summary": "Promueve tel\xE9fonos a administrador", "pending": false },
+  { "method": "POST", "path": "/api/v1/groups/{group}/admins/remove", "operationId": "apiGroupAction.demoteAdmins", "domain": "communities", "permission": "communities:operate", "tag": "Acciones de grupo", "summary": "Quita el rol de administrador a tel\xE9fonos", "pending": false },
+  { "method": "PUT", "path": "/api/v1/groups/{group}/description", "operationId": "apiGroupAction.updateDescription", "domain": "communities", "permission": "communities:operate", "tag": "Acciones de grupo", "summary": "Cambia la descripci\xF3n del grupo", "pending": false },
+  { "method": "POST", "path": "/api/v1/groups/{group}/import", "operationId": "v2.apiGroupImport", "domain": "communities", "permission": "communities:operate", "tag": "Grupos", "summary": "Importar un grupo de un n\xFAmero", "pending": false },
+  { "method": "GET", "path": "/api/v1/groups/{group}/invite-link/live", "operationId": "apiGroupAction.inviteLink", "domain": "communities", "permission": "communities:read", "tag": "Acciones de grupo", "summary": "Link de invitaci\xF3n vigente del grupo", "pending": false },
+  { "method": "POST", "path": "/api/v1/groups/{group}/invite-link/renew", "operationId": "apiGroupAction.renewInviteLink", "domain": "communities", "permission": "communities:operate", "tag": "Acciones de grupo", "summary": "Renueva el link de invitaci\xF3n del grupo", "pending": false },
+  { "method": "GET", "path": "/api/v1/groups/{group}/join-requests", "operationId": "apiGroupAction.joinRequests", "domain": "communities", "permission": "communities:read", "tag": "Acciones de grupo", "summary": "Solicitudes pendientes para unirse al grupo", "pending": false },
+  { "method": "POST", "path": "/api/v1/groups/{group}/join-requests/approve", "operationId": "apiGroupAction.approveJoinRequests", "domain": "communities", "permission": "communities:operate", "tag": "Acciones de grupo", "summary": "Aprueba solicitudes para unirse al grupo", "pending": false },
+  { "method": "POST", "path": "/api/v1/groups/{group}/join-requests/reject", "operationId": "apiGroupAction.rejectJoinRequests", "domain": "communities", "permission": "communities:operate", "tag": "Acciones de grupo", "summary": "Rechaza solicitudes para unirse al grupo", "pending": false },
   { "method": "GET", "path": "/api/v1/groups/{group}/messages", "operationId": "group.messages", "domain": "communities", "permission": "communities:read", "tag": "Grupos", "summary": "Listar los mensajes enviados a un grupo", "pending": false },
-  { "method": "POST", "path": "/api/v1/groups/{group}/messages", "operationId": "pendingGroups.sendMessage", "domain": "communities", "permission": "communities:send", "tag": "GroupAction", "summary": "Send a message to a group", "pending": true },
+  { "method": "POST", "path": "/api/v1/groups/{group}/messages", "operationId": "apiGroupAction.sendMessage", "domain": "communities", "permission": "communities:send", "tag": "Acciones de grupo", "summary": "Mandar un mensaje a un grupo", "pending": false },
+  { "method": "PUT", "path": "/api/v1/groups/{group}/name", "operationId": "apiGroupAction.updateName", "domain": "communities", "permission": "communities:operate", "tag": "Acciones de grupo", "summary": "Cambia el nombre del grupo", "pending": false },
   { "method": "GET", "path": "/api/v1/groups/{group}/participant-events", "operationId": "group.participantEvents", "domain": "communities", "permission": "communities:read", "tag": "Participantes", "summary": "Listar entradas y salidas de un grupo", "pending": false },
+  { "method": "POST", "path": "/api/v1/groups/{group}/participants", "operationId": "apiGroupAction.addParticipants", "domain": "communities", "permission": "communities:operate", "tag": "Acciones de grupo", "summary": "Suma participantes al grupo", "pending": false },
+  { "method": "POST", "path": "/api/v1/groups/{group}/participants/remove", "operationId": "apiGroupAction.removeParticipants", "domain": "communities", "permission": "communities:operate", "tag": "Acciones de grupo", "summary": "Saca participantes del grupo", "pending": false },
+  { "method": "PUT", "path": "/api/v1/groups/{group}/photo", "operationId": "apiGroupAction.updatePhoto", "domain": "communities", "permission": "communities:operate", "tag": "Acciones de grupo", "summary": "Cambia la foto del grupo", "pending": false },
   { "method": "GET", "path": "/api/v1/groups/{group}/scheduled-messages", "operationId": "group.scheduledMessages", "domain": "communities", "permission": "communities:read", "tag": "Grupos", "summary": "Listar los env\xEDos programados que incluyen un grupo", "pending": false },
+  { "method": "PUT", "path": "/api/v1/groups/{group}/settings", "operationId": "apiGroupAction.updateSettings", "domain": "communities", "permission": "communities:operate", "tag": "Acciones de grupo", "summary": "Cambia si los miembros pueden escribir", "pending": false },
   { "method": "GET", "path": "/api/v1/groups/{groupUid}/metadata", "operationId": "groupMetadata.show", "domain": "communities", "permission": "communities:read", "tag": "Grupos", "summary": "Ver los datos actuales de un grupo en WhatsApp", "pending": false },
-  { "method": "GET", "path": "/api/v1/groups/actions/{action}", "operationId": "pendingGroups.retrieveAction", "domain": "communities", "permission": "communities:read", "tag": "GroupAction", "summary": "A group action", "pending": true },
+  { "method": "GET", "path": "/api/v1/groups/actions/{action}", "operationId": "apiGroupAction.show", "domain": "communities", "permission": "communities:read", "tag": "Acciones de grupo", "summary": "Ver c\xF3mo sali\xF3 una acci\xF3n de grupo", "pending": true },
   { "method": "GET", "path": "/api/v1/groups/participants", "operationId": "group.participants", "domain": "communities", "permission": "communities:read", "tag": "Participantes", "summary": "Listar los participantes de un grupo", "pending": false },
   { "method": "GET", "path": "/api/v1/kanban-settings", "operationId": "kanbanSetting.index", "domain": "conversations", "permission": "conversations:read", "tag": "KanbanSetting", "summary": "Listar tableros", "pending": false },
   { "method": "POST", "path": "/api/v1/kanban-settings", "operationId": "kanbanSetting.store", "domain": "conversations", "permission": "conversations:write", "tag": "KanbanSetting", "summary": "Crear un tablero", "pending": false },
@@ -1118,7 +1139,11 @@ var Groups = class extends Resource {
   retrieve(group, options) {
     return this.client.request("GET", "/api/v1/groups/{group}", { ...options, path: { group } });
   }
-  /** `GET /api/v1/devices/{device}/groups`, paginated (`page`, `pageSize`): the groups of one number. */
+  /**
+   * `GET /api/v1/devices/{device}/groups`, paginated (`page`, `pageSize`): the groups of one number,
+   * read live from WhatsApp (for a key, reused for a minute per number). A group that is already in
+   * the account brings `device_id`; any other can be followed with {@link Groups.follow}.
+   */
   listByDevice(device, query, options) {
     return this.client.paginate("/api/v1/devices/{device}/groups", { ...options, path: { device }, query });
   }
@@ -1161,6 +1186,20 @@ var Groups = class extends Resource {
   sendMessage(group, body, options) {
     return this.client.request("POST", "/api/v1/groups/{group}/messages", { ...options, path: { group }, body });
   }
+  /**
+   * `POST /api/v1/groups/{group}/import`: follows a WhatsApp group of a QR number (`device_id`), as
+   * importing it in the panel does: from then on its joins and leaves arrive by
+   * `group_participant.joined` and `group_participant.left`. Resolves to `{ data: { uid, name,
+   * imported, is_admin } }`: `imported` is `false` when the group was already in the account, and
+   * `is_admin` says whether the number administers it (without that it cannot write to it). Needs
+   * **Groups and campaigns → Manage groups** (`403 import_permission_required`); up to 5 groups
+   * per number per minute (`429 import_rate_limited`, with `retryAfter`); an official number is
+   * `422 provider_unsupported`. {@link Groups.sendMessage} follows the group itself when it is not in
+   * the account yet.
+   */
+  follow(group, body, options) {
+    return this.client.request("POST", "/api/v1/groups/{group}/import", { ...options, path: { group }, body });
+  }
   /**
    * `GET /api/v1/groups/actions/{action}`: where a group action, such as a message sent with
    * {@link Groups.sendMessage}, is (`queued`, `running`, `completed` or `failed`) and its `result`.
@@ -1448,7 +1487,7 @@ var Webhooks = class extends Resource {
 };
 
 // src/version.ts
-var VERSION = "0.3.0";
+var VERSION = "0.3.2";
 
 // src/client.ts
 var BASE_URLS = {