bzapper 0.8.1 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 2492fe46b1c91f8b88b673e102de183388ec0aeba9686f83de3d62b50eb4cc01
4
- data.tar.gz: 57c3253532c2a83d67cbbc21b811fc05f97a2c7ac331462fc7d4b60f4bb8a0c2
3
+ metadata.gz: 1a8e0c8a695ae7a7806613f902d9355715a0239d1f34b54bd795b9360ad54466
4
+ data.tar.gz: d40cdd05ab273cc3bf98b9e14c5aabf23c4ff2ac44dc13f5bbb2fbcf855c40ab
5
5
  SHA512:
6
- metadata.gz: 60d10efd60798233d8c40d2f006da6d322d38af941a86d06cb148230ec6cf3a9df435a70a1db49f2630319781b76199e75fac7c2d736bdaf38a2e943279bd926
7
- data.tar.gz: cfee6f2f48d55e3a40934cb509e85ac5832b42f76c1e677dd17d8f8f0f5384f0b617cc22ba25535c3375f7591ef8f959fc90a56cf3acd523696c170fab569287
6
+ metadata.gz: 0e79610714b42f6f9fd5e6d62ce9ef2864d351922885aec6a2a6aef979dbbc54a8daf7636b06c49ab93a4a40ab83868ad9a8779a69310c5a6b200d040706dded
7
+ data.tar.gz: 663ff3dc3a6a50404724745ad2dbbeadf4b97d912b28c706b2b63822b9c0ee53119752f03dd8189cb6cf8e33a81541e9ca689757241899fd4abdd778770f92d4
data/README.md CHANGED
@@ -10,13 +10,13 @@ Zero dependências de runtime (só biblioteca padrão: `net/http`, `json`, `open
10
10
  ## Instalação
11
11
 
12
12
  ```bash
13
- gem install bzapper -v 0.8.1
13
+ gem install bzapper -v 0.9.0
14
14
  ```
15
15
 
16
16
  Ou no `Gemfile` — **fixe a versão exata** (cada release declara se muda a superfície pública):
17
17
 
18
18
  ```ruby
19
- gem "bzapper", "0.8.1"
19
+ gem "bzapper", "0.9.0"
20
20
  ```
21
21
 
22
22
  ## Hello world
@@ -81,9 +81,11 @@ spec OpenAPI em snake_case (`sendText` → `send_text`):
81
81
 
82
82
  | Recurso | O que tem |
83
83
  | --- | --- |
84
- | `client.messages` | `send_text`, `send_image`, `send_video`, `send_document`, `send_audio`, `send_sticker`, `send_location`, `send_contact`, `send_poll`, `send_reaction`, `send_buttons`, `send_list`, `send_otp`, `mark_read`, `presence_chat` |
84
+ | `client.messages` | `send_text`, `send_image`, `send_video`, `send_document`, `send_audio`, `send_sticker`, `send_location`, `send_contact`, `send_poll`, `send_reaction`, `send_buttons`, `send_list`, `send_otp`, `send_template` (trilho oficial), `mark_read`, `presence_chat` |
85
85
  | `client.scheduling` | `list_scheduled`, `cancel_scheduled` |
86
- | `client.instances` | números: `list_instances`, `create_instance`, `connect_instance` (QR/código), `get_instance`, `disconnect_instance`, `logout_instance`, `clear_instance_session`, `archive_instance`, proxy, filtros de entrada, conta oficial… |
86
+ | `client.instances` | números: `list_instances`, `create_instance`, `connect_instance` (QR/código), `get_instance`, `disconnect_instance`, `logout_instance`, `clear_instance_session`, `archive_instance`, proxy, filtros de entrada… |
87
+ | `client.official` | trilho oficial (WhatsApp Cloud API): `get_official_account`, `connect_official_account`, `disconnect_official_account`, `get_official_status`, Embedded Signup (`get_official_signup_config`, `complete_official_signup`), números da WABA (`list_official_numbers`, `list_available_official_numbers`, `add_official_number`, `set_default_official_number`, `disconnect_official_number`), perfil comercial (`get/update_official_profile`, `upload_official_profile_photo`, `reregister_official_profile` e as variantes `*_official_number_profile*` por número) |
88
+ | `client.templates` | templates aprovados pela Meta: `list_templates`, `create_template`, `get_template`, `delete_template`, `sync_templates`, `upload_template_media`, `get/set_fallback_template` |
87
89
  | `client.groups` | `list_groups`, `create_group`, `get_group`, `update_group`, `update_group_participants`, `group_invite_link`, `join_group`, `preview_group_invite`, `leave_group`, pedidos de entrada |
88
90
  | `client.conversations` | `list_conversations`, `conversation_history` |
89
91
  | `client.advanced` | editar/apagar/encaminhar mensagem, perfil, privacidade, arquivar/fixar/ler/silenciar chat, etiquetas, bloqueio, chamadas |
@@ -125,7 +127,7 @@ m.send_document(to: to, media: { url: "https://example.com/nota.pdf", filename:
125
127
  m.send_audio(to: to, media: { url: "https://example.com/audio.ogg", ptt: true }) # ptt = mensagem de voz
126
128
  m.send_sticker(to: to, media: { url: "https://example.com/sticker.webp" })
127
129
  m.send_location(to: to, latitude: -23.5613, longitude: -46.6565, name: "Av. Paulista")
128
- m.send_contact(to: to, contact_name: "Berni Software", contact_vcard: "BEGIN:VCARD…")
130
+ m.send_contact(to: to, contact_name: "Berni Software", contact_phone: "+5511977776666")
129
131
  m.send_poll(to: to, name: "Pizza ou sushi?", options: %w[Pizza Sushi], selectable_count: 1)
130
132
  m.send_reaction(to: to, quoted_message_id: "ABCD1234", emoji: "👍") # emoji "" remove
131
133
  m.send_buttons(to: to, body: "Escolha:", buttons: [{ id: "a", title: "Opção A" }, { id: "b", title: "Opção B" }])
@@ -68,10 +68,10 @@ module Bzapper
68
68
  request("GET", "/campaigns/estimate", query: query, timeout: timeout)
69
69
  end
70
70
 
71
- # Per-number campaign eligibility (connection + warm-up). `GET /campaigns/eligibility`
71
+ # Per-number campaign eligibility (connection and age). `GET /campaigns/eligibility`
72
72
  #
73
- # Same engine the dispatcher uses: which numbers can send campaigns now, the account's anti-ban
74
- # policy (warm-up days, minimum numbers) and whether a campaign can be started.
73
+ # Same engine the dispatcher uses: which numbers can send campaigns now, the account's campaign
74
+ # policy (minimum connection age, minimum numbers) and whether a campaign can be started.
75
75
  #
76
76
  # @param pool_id [String, nil] (query) Restrict to a pool.
77
77
  # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
@@ -30,6 +30,23 @@ module Bzapper
30
30
  idempotency_key: idempotency_key,
31
31
  timeout: timeout)
32
32
  end
33
+
34
+ # Convert a partner-created account to general use (admin). The connection stays: the partner
35
+ # keeps working and any partnership discount keeps applying. What changes is that the account
36
+ # may issue its own API keys. Irreversible. `POST /me/connections/{id}/standalone`
37
+ #
38
+ # @param id [String] Connected partner app (connection) ID (UUID).
39
+ # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
40
+ # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
41
+ # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
42
+ # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
43
+ # @raise [ArgumentError] parâmetro de caminho vazio, "." ou "..".
44
+ def convert_connected_app_to_standalone(id, idempotency_key: nil, timeout: nil)
45
+ request("POST",
46
+ "/me/connections/#{segment(id, "id")}/standalone",
47
+ idempotency_key: idempotency_key,
48
+ timeout: timeout)
49
+ end
33
50
  end
34
51
  end
35
52
  end
@@ -210,7 +210,29 @@ module Bzapper
210
210
  timeout: timeout)
211
211
  end
212
212
 
213
- # The WhatsApp Business (Cloud API) account connected to the project. `GET /official/account`
213
+ # Set the instance proxy (network / IP isolation). `PATCH /instances/{id}/proxy`
214
+ #
215
+ # @param id [String] Instance ID (UUID).
216
+ # @param proxy_url [String] (corpo) Proxy URL (empty removes it).
217
+ # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
218
+ # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
219
+ # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
220
+ # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
221
+ # @raise [ArgumentError] parâmetro de caminho vazio, "." ou "..".
222
+ def set_instance_proxy(id, proxy_url:, idempotency_key: nil, timeout: nil)
223
+ payload = compact(
224
+ "proxy_url" => proxy_url
225
+ )
226
+ request("PATCH",
227
+ "/instances/#{segment(id, "id")}/proxy",
228
+ body: payload,
229
+ idempotency_key: idempotency_key,
230
+ timeout: timeout)
231
+ end
232
+
233
+ # Read the WhatsApp Business Account connected to the project. `GET /official/account`
234
+ #
235
+ # Mantido aqui por compatibilidade — o mesmo que `client.official.get_official_account`.
214
236
  #
215
237
  # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
216
238
  # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
@@ -219,23 +241,30 @@ module Bzapper
219
241
  request("GET", "/official/account", timeout: timeout)
220
242
  end
221
243
 
222
- # Connect a WhatsApp Business account to the project (manual credentials). `POST
223
- # /official/account`
244
+ # Connect (or reconnect) a WhatsApp Business Account to the project. `POST /official/account`
245
+ #
246
+ # Mantido aqui por compatibilidade — o mesmo que `client.official.connect_official_account`.
224
247
  #
225
- # Manual connection with credentials (support fallback for the Embedded Signup). The access
226
- # token is stored encrypted and never returned.
248
+ # Stores the customer's Meta credentials for the project. Calling it again replaces them — that
249
+ # is the reconnection path when a token is revoked, and it never creates a second account for
250
+ # the same project. `phone_number_id` is optional: when omitted, the number is discovered from
251
+ # the WABA. If the WABA holds more than one number the call returns 409 with the list, so the
252
+ # choice stays with the account owner instead of being guessed.
227
253
  #
228
254
  # @param waba_id [String] (corpo)
229
- # @param phone_number_id [String] (corpo)
230
- # @param access_token [String] (corpo)
255
+ # @param phone_number_id [String, nil] (corpo) Optional — discovered from the WABA when omitted.
256
+ # @param access_token [String] (corpo) The customer's WABA token, stored encrypted at rest. A
257
+ # token taken from Meta's "API Setup" screen expires in 24h; for a lasting connection use a
258
+ # system user with `whatsapp_business_messaging` + `whatsapp_business_management`.
231
259
  # @param display_number [String, nil] (corpo)
232
260
  # @param verified_name [String, nil] (corpo)
233
- # @param status [String, nil] (corpo) Initial status. Omit for PENDENTE.
261
+ # @param status [String, nil] (corpo) Empty means PENDENTE, which is the correct state coming
262
+ # out of Embedded Signup.
234
263
  # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
235
264
  # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
236
265
  # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
237
266
  # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
238
- def connect_official_account(waba_id:, phone_number_id:, access_token:,
267
+ def connect_official_account(waba_id:, access_token:, phone_number_id: UNSET,
239
268
  display_number: UNSET, verified_name: UNSET, status: UNSET,
240
269
  idempotency_key: nil, timeout: nil)
241
270
  payload = compact(
@@ -253,7 +282,9 @@ module Bzapper
253
282
  timeout: timeout)
254
283
  end
255
284
 
256
- # Disconnect the project's WhatsApp Business account. `DELETE /official/account`
285
+ # Disconnect the account from the project. `DELETE /official/account`
286
+ #
287
+ # Mantido aqui por compatibilidade — o mesmo que `client.official.disconnect_official_account`.
257
288
  #
258
289
  # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
259
290
  # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
@@ -262,26 +293,6 @@ module Bzapper
262
293
  def disconnect_official_account(idempotency_key: nil, timeout: nil)
263
294
  request("DELETE", "/official/account", idempotency_key: idempotency_key, timeout: timeout)
264
295
  end
265
-
266
- # Set the instance proxy (network / IP isolation). `PATCH /instances/{id}/proxy`
267
- #
268
- # @param id [String] Instance ID (UUID).
269
- # @param proxy_url [String] (corpo) Proxy URL (empty removes it).
270
- # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
271
- # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
272
- # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
273
- # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
274
- # @raise [ArgumentError] parâmetro de caminho vazio, "." ou "..".
275
- def set_instance_proxy(id, proxy_url:, idempotency_key: nil, timeout: nil)
276
- payload = compact(
277
- "proxy_url" => proxy_url
278
- )
279
- request("PATCH",
280
- "/instances/#{segment(id, "id")}/proxy",
281
- body: payload,
282
- idempotency_key: idempotency_key,
283
- timeout: timeout)
284
- end
285
296
  end
286
297
  end
287
298
  end
@@ -17,7 +17,9 @@ module Bzapper
17
17
  # instance_id/pool_id, it AUTOMATICALLY reuses the number that already talks to `to`, ensuring
18
18
  # the whole interaction stays on the same number. Default **true**; send **false** to force
19
19
  # rotation (e.g. campaign/broadcast).
20
- # @param to [String] (corpo) Destination E.164 phone or JID.
20
+ # @param to [String] (corpo) Destination: E.164 phone (+DDIdigits), contact JID
21
+ # (…@s.whatsapp.net), group JID (…@g.us) or the contact's @lid. A @lid is translated to the
22
+ # phone when the connected number knows it; the official rail accepts phone only.
21
23
  # @param quoted_message_id [String, nil] (corpo) Quoted wa_message_id (reply).
22
24
  # @param quoted_participant [String, nil] (corpo) Author (phone or JID) of the quoted/reacted
23
25
  # message. Only needed in groups when the quoted message is not in bZapper history — otherwise
@@ -80,7 +82,9 @@ module Bzapper
80
82
  # instance_id/pool_id, it AUTOMATICALLY reuses the number that already talks to `to`, ensuring
81
83
  # the whole interaction stays on the same number. Default **true**; send **false** to force
82
84
  # rotation (e.g. campaign/broadcast).
83
- # @param to [String] (corpo) Destination E.164 phone or JID.
85
+ # @param to [String] (corpo) Destination: E.164 phone (+DDIdigits), contact JID
86
+ # (…@s.whatsapp.net), group JID (…@g.us) or the contact's @lid. A @lid is translated to the
87
+ # phone when the connected number knows it; the official rail accepts phone only.
84
88
  # @param quoted_message_id [String, nil] (corpo) Quoted wa_message_id (reply).
85
89
  # @param quoted_participant [String, nil] (corpo) Author (phone or JID) of the quoted/reacted
86
90
  # message. Only needed in groups when the quoted message is not in bZapper history — otherwise
@@ -101,7 +105,8 @@ module Bzapper
101
105
  # @param force [Boolean, nil] (corpo) OPTIONAL. When true, bypasses an inferred suppression
102
106
  # (e.g. opt-out inferred from behaviour) for this send. Does NOT override an explicit
103
107
  # suppression entry (`/suppressions`) — use with care and only with a lawful basis.
104
- # @param media [Hash] (corpo) Media by URL **or** base64 (never both).
108
+ # @param media [Hash] (corpo) Media by URL **or** base64 (never both) — or, on the official
109
+ # rail, by `id` (a file already uploaded with `uploadOfficialMedia`).
105
110
  # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
106
111
  # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
107
112
  # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
@@ -143,7 +148,9 @@ module Bzapper
143
148
  # instance_id/pool_id, it AUTOMATICALLY reuses the number that already talks to `to`, ensuring
144
149
  # the whole interaction stays on the same number. Default **true**; send **false** to force
145
150
  # rotation (e.g. campaign/broadcast).
146
- # @param to [String] (corpo) Destination E.164 phone or JID.
151
+ # @param to [String] (corpo) Destination: E.164 phone (+DDIdigits), contact JID
152
+ # (…@s.whatsapp.net), group JID (…@g.us) or the contact's @lid. A @lid is translated to the
153
+ # phone when the connected number knows it; the official rail accepts phone only.
147
154
  # @param quoted_message_id [String, nil] (corpo) Quoted wa_message_id (reply).
148
155
  # @param quoted_participant [String, nil] (corpo) Author (phone or JID) of the quoted/reacted
149
156
  # message. Only needed in groups when the quoted message is not in bZapper history — otherwise
@@ -164,7 +171,8 @@ module Bzapper
164
171
  # @param force [Boolean, nil] (corpo) OPTIONAL. When true, bypasses an inferred suppression
165
172
  # (e.g. opt-out inferred from behaviour) for this send. Does NOT override an explicit
166
173
  # suppression entry (`/suppressions`) — use with care and only with a lawful basis.
167
- # @param media [Hash] (corpo) Media by URL **or** base64 (never both).
174
+ # @param media [Hash] (corpo) Media by URL **or** base64 (never both) — or, on the official
175
+ # rail, by `id` (a file already uploaded with `uploadOfficialMedia`).
168
176
  # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
169
177
  # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
170
178
  # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
@@ -206,7 +214,9 @@ module Bzapper
206
214
  # instance_id/pool_id, it AUTOMATICALLY reuses the number that already talks to `to`, ensuring
207
215
  # the whole interaction stays on the same number. Default **true**; send **false** to force
208
216
  # rotation (e.g. campaign/broadcast).
209
- # @param to [String] (corpo) Destination E.164 phone or JID.
217
+ # @param to [String] (corpo) Destination: E.164 phone (+DDIdigits), contact JID
218
+ # (…@s.whatsapp.net), group JID (…@g.us) or the contact's @lid. A @lid is translated to the
219
+ # phone when the connected number knows it; the official rail accepts phone only.
210
220
  # @param quoted_message_id [String, nil] (corpo) Quoted wa_message_id (reply).
211
221
  # @param quoted_participant [String, nil] (corpo) Author (phone or JID) of the quoted/reacted
212
222
  # message. Only needed in groups when the quoted message is not in bZapper history — otherwise
@@ -227,7 +237,8 @@ module Bzapper
227
237
  # @param force [Boolean, nil] (corpo) OPTIONAL. When true, bypasses an inferred suppression
228
238
  # (e.g. opt-out inferred from behaviour) for this send. Does NOT override an explicit
229
239
  # suppression entry (`/suppressions`) — use with care and only with a lawful basis.
230
- # @param media [Hash] (corpo) Media by URL **or** base64 (never both).
240
+ # @param media [Hash] (corpo) Media by URL **or** base64 (never both) — or, on the official
241
+ # rail, by `id` (a file already uploaded with `uploadOfficialMedia`).
231
242
  # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
232
243
  # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
233
244
  # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
@@ -270,7 +281,9 @@ module Bzapper
270
281
  # instance_id/pool_id, it AUTOMATICALLY reuses the number that already talks to `to`, ensuring
271
282
  # the whole interaction stays on the same number. Default **true**; send **false** to force
272
283
  # rotation (e.g. campaign/broadcast).
273
- # @param to [String] (corpo) Destination E.164 phone or JID.
284
+ # @param to [String] (corpo) Destination: E.164 phone (+DDIdigits), contact JID
285
+ # (…@s.whatsapp.net), group JID (…@g.us) or the contact's @lid. A @lid is translated to the
286
+ # phone when the connected number knows it; the official rail accepts phone only.
274
287
  # @param quoted_message_id [String, nil] (corpo) Quoted wa_message_id (reply).
275
288
  # @param quoted_participant [String, nil] (corpo) Author (phone or JID) of the quoted/reacted
276
289
  # message. Only needed in groups when the quoted message is not in bZapper history — otherwise
@@ -291,7 +304,8 @@ module Bzapper
291
304
  # @param force [Boolean, nil] (corpo) OPTIONAL. When true, bypasses an inferred suppression
292
305
  # (e.g. opt-out inferred from behaviour) for this send. Does NOT override an explicit
293
306
  # suppression entry (`/suppressions`) — use with care and only with a lawful basis.
294
- # @param media [Hash] (corpo) Media by URL **or** base64 (never both).
307
+ # @param media [Hash] (corpo) Media by URL **or** base64 (never both) — or, on the official
308
+ # rail, by `id` (a file already uploaded with `uploadOfficialMedia`).
295
309
  # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
296
310
  # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
297
311
  # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
@@ -333,7 +347,9 @@ module Bzapper
333
347
  # instance_id/pool_id, it AUTOMATICALLY reuses the number that already talks to `to`, ensuring
334
348
  # the whole interaction stays on the same number. Default **true**; send **false** to force
335
349
  # rotation (e.g. campaign/broadcast).
336
- # @param to [String] (corpo) Destination E.164 phone or JID.
350
+ # @param to [String] (corpo) Destination: E.164 phone (+DDIdigits), contact JID
351
+ # (…@s.whatsapp.net), group JID (…@g.us) or the contact's @lid. A @lid is translated to the
352
+ # phone when the connected number knows it; the official rail accepts phone only.
337
353
  # @param quoted_message_id [String, nil] (corpo) Quoted wa_message_id (reply).
338
354
  # @param quoted_participant [String, nil] (corpo) Author (phone or JID) of the quoted/reacted
339
355
  # message. Only needed in groups when the quoted message is not in bZapper history — otherwise
@@ -354,7 +370,8 @@ module Bzapper
354
370
  # @param force [Boolean, nil] (corpo) OPTIONAL. When true, bypasses an inferred suppression
355
371
  # (e.g. opt-out inferred from behaviour) for this send. Does NOT override an explicit
356
372
  # suppression entry (`/suppressions`) — use with care and only with a lawful basis.
357
- # @param media [Hash] (corpo) Media by URL **or** base64 (never both).
373
+ # @param media [Hash] (corpo) Media by URL **or** base64 (never both) — or, on the official
374
+ # rail, by `id` (a file already uploaded with `uploadOfficialMedia`).
358
375
  # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
359
376
  # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
360
377
  # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
@@ -397,7 +414,9 @@ module Bzapper
397
414
  # instance_id/pool_id, it AUTOMATICALLY reuses the number that already talks to `to`, ensuring
398
415
  # the whole interaction stays on the same number. Default **true**; send **false** to force
399
416
  # rotation (e.g. campaign/broadcast).
400
- # @param to [String] (corpo) Destination E.164 phone or JID.
417
+ # @param to [String] (corpo) Destination: E.164 phone (+DDIdigits), contact JID
418
+ # (…@s.whatsapp.net), group JID (…@g.us) or the contact's @lid. A @lid is translated to the
419
+ # phone when the connected number knows it; the official rail accepts phone only.
401
420
  # @param quoted_message_id [String, nil] (corpo) Quoted wa_message_id (reply).
402
421
  # @param quoted_participant [String, nil] (corpo) Author (phone or JID) of the quoted/reacted
403
422
  # message. Only needed in groups when the quoted message is not in bZapper history — otherwise
@@ -467,7 +486,9 @@ module Bzapper
467
486
  # instance_id/pool_id, it AUTOMATICALLY reuses the number that already talks to `to`, ensuring
468
487
  # the whole interaction stays on the same number. Default **true**; send **false** to force
469
488
  # rotation (e.g. campaign/broadcast).
470
- # @param to [String] (corpo) Destination E.164 phone or JID.
489
+ # @param to [String] (corpo) Destination: E.164 phone (+DDIdigits), contact JID
490
+ # (…@s.whatsapp.net), group JID (…@g.us) or the contact's @lid. A @lid is translated to the
491
+ # phone when the connected number knows it; the official rail accepts phone only.
471
492
  # @param quoted_message_id [String, nil] (corpo) Quoted wa_message_id (reply).
472
493
  # @param quoted_participant [String, nil] (corpo) Author (phone or JID) of the quoted/reacted
473
494
  # message. Only needed in groups when the quoted message is not in bZapper history — otherwise
@@ -488,8 +509,12 @@ module Bzapper
488
509
  # @param force [Boolean, nil] (corpo) OPTIONAL. When true, bypasses an inferred suppression
489
510
  # (e.g. opt-out inferred from behaviour) for this send. Does NOT override an explicit
490
511
  # suppression entry (`/suppressions`) — use with care and only with a lawful basis.
491
- # @param contact_name [String, nil] (corpo)
492
- # @param contact_vcard [String, nil] (corpo)
512
+ # @param contact_name [String, nil] (corpo) Name shown on the card.
513
+ # @param contact_phone [String, nil] (corpo) The CARD CONTACT's phone in E.164 — the person
514
+ # being shared, never the destination. Required with contact_name (not needed when you send a
515
+ # ready contact_vcard); it is what makes WhatsApp recognise the card as a contact.
516
+ # @param contact_vcard [String, nil] (corpo) Ready vCard; when present,
517
+ # contact_name/contact_phone are not used to build one.
493
518
  # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
494
519
  # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
495
520
  # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
@@ -498,7 +523,8 @@ module Bzapper
498
523
  quoted_message_id: UNSET, quoted_participant: UNSET,
499
524
  client_reference: UNSET, mentions: UNSET, scheduled_at: UNSET,
500
525
  groups: UNSET, tags: UNSET, force: UNSET, contact_name: UNSET,
501
- contact_vcard: UNSET, idempotency_key: nil, timeout: nil)
526
+ contact_phone: UNSET, contact_vcard: UNSET, idempotency_key: nil,
527
+ timeout: nil)
502
528
  payload = compact(
503
529
  "instance_id" => instance_id,
504
530
  "pool_id" => pool_id,
@@ -513,6 +539,7 @@ module Bzapper
513
539
  "tags" => tags,
514
540
  "force" => force,
515
541
  "contact_name" => contact_name,
542
+ "contact_phone" => contact_phone,
516
543
  "contact_vcard" => contact_vcard
517
544
  )
518
545
  request("POST",
@@ -533,7 +560,9 @@ module Bzapper
533
560
  # instance_id/pool_id, it AUTOMATICALLY reuses the number that already talks to `to`, ensuring
534
561
  # the whole interaction stays on the same number. Default **true**; send **false** to force
535
562
  # rotation (e.g. campaign/broadcast).
536
- # @param to [String] (corpo) Destination E.164 phone or JID.
563
+ # @param to [String] (corpo) Destination: E.164 phone (+DDIdigits), contact JID
564
+ # (…@s.whatsapp.net), group JID (…@g.us) or the contact's @lid. A @lid is translated to the
565
+ # phone when the connected number knows it; the official rail accepts phone only.
537
566
  # @param quoted_message_id [String, nil] (corpo) Quoted wa_message_id (reply).
538
567
  # @param quoted_participant [String, nil] (corpo) Author (phone or JID) of the quoted/reacted
539
568
  # message. Only needed in groups when the quoted message is not in bZapper history — otherwise
@@ -600,7 +629,9 @@ module Bzapper
600
629
  # instance_id/pool_id, it AUTOMATICALLY reuses the number that already talks to `to`, ensuring
601
630
  # the whole interaction stays on the same number. Default **true**; send **false** to force
602
631
  # rotation (e.g. campaign/broadcast).
603
- # @param to [String] (corpo) Destination E.164 phone or JID.
632
+ # @param to [String] (corpo) Destination: E.164 phone (+DDIdigits), contact JID
633
+ # (…@s.whatsapp.net), group JID (…@g.us) or the contact's @lid. A @lid is translated to the
634
+ # phone when the connected number knows it; the official rail accepts phone only.
604
635
  # @param quoted_message_id [String] (corpo) Quoted wa_message_id (reply).
605
636
  # @param quoted_participant [String, nil] (corpo) Author (phone or JID) of the quoted/reacted
606
637
  # message. Only needed in groups when the quoted message is not in bZapper history — otherwise
@@ -666,7 +697,9 @@ module Bzapper
666
697
  # instance_id/pool_id, it AUTOMATICALLY reuses the number that already talks to `to`, ensuring
667
698
  # the whole interaction stays on the same number. Default **true**; send **false** to force
668
699
  # rotation (e.g. campaign/broadcast).
669
- # @param to [String] (corpo) Destination E.164 phone or JID.
700
+ # @param to [String] (corpo) Destination: E.164 phone (+DDIdigits), contact JID
701
+ # (…@s.whatsapp.net), group JID (…@g.us) or the contact's @lid. A @lid is translated to the
702
+ # phone when the connected number knows it; the official rail accepts phone only.
670
703
  # @param quoted_message_id [String, nil] (corpo) Quoted wa_message_id (reply).
671
704
  # @param quoted_participant [String, nil] (corpo) Author (phone or JID) of the quoted/reacted
672
705
  # message. Only needed in groups when the quoted message is not in bZapper history — otherwise
@@ -734,7 +767,9 @@ module Bzapper
734
767
  # instance_id/pool_id, it AUTOMATICALLY reuses the number that already talks to `to`, ensuring
735
768
  # the whole interaction stays on the same number. Default **true**; send **false** to force
736
769
  # rotation (e.g. campaign/broadcast).
737
- # @param to [String] (corpo) Destination E.164 phone or JID.
770
+ # @param to [String] (corpo) Destination: E.164 phone (+DDIdigits), contact JID
771
+ # (…@s.whatsapp.net), group JID (…@g.us) or the contact's @lid. A @lid is translated to the
772
+ # phone when the connected number knows it; the official rail accepts phone only.
738
773
  # @param quoted_message_id [String, nil] (corpo) Quoted wa_message_id (reply).
739
774
  # @param quoted_participant [String, nil] (corpo) Author (phone or JID) of the quoted/reacted
740
775
  # message. Only needed in groups when the quoted message is not in bZapper history — otherwise
@@ -808,7 +843,9 @@ module Bzapper
808
843
  # instance_id/pool_id, it AUTOMATICALLY reuses the number that already talks to `to`, ensuring
809
844
  # the whole interaction stays on the same number. Default **true**; send **false** to force
810
845
  # rotation (e.g. campaign/broadcast).
811
- # @param to [String] (corpo) Destination E.164 phone or JID.
846
+ # @param to [String] (corpo) Destination: E.164 phone (+DDIdigits), contact JID
847
+ # (…@s.whatsapp.net), group JID (…@g.us) or the contact's @lid. A @lid is translated to the
848
+ # phone when the connected number knows it; the official rail accepts phone only.
812
849
  # @param quoted_message_id [String, nil] (corpo) Quoted wa_message_id (reply).
813
850
  # @param quoted_participant [String, nil] (corpo) Author (phone or JID) of the quoted/reacted
814
851
  # message. Only needed in groups when the quoted message is not in bZapper history — otherwise
@@ -866,6 +903,101 @@ module Bzapper
866
903
  timeout: timeout)
867
904
  end
868
905
 
906
+ # Send an approved template by name. `POST /messages/template`
907
+ #
908
+ # The ONLY way to start a conversation outside the 24-hour service window. You pass the template
909
+ # NAME and the values; the id Meta assigned to it never appears. `language` may be omitted when
910
+ # the name exists in a single language — asking for it when there is no ambiguity would be
911
+ # paperwork. If the name exists in more than one, the answer is 409 `template_ambiguous`,
912
+ # because picking the wrong language for someone is worse than asking. The number of `variables`
913
+ # must match the approved body exactly. We check that here rather than spending the call: a
914
+ # mismatch is the number one cause of Meta error 132000. For an AUTHENTICATION template, send
915
+ # the code in `code` — Meta requires it both in the body and in the copy-code button, and we
916
+ # place it in both.
917
+ #
918
+ # @param instance_id [String, nil] (corpo) OPTIONAL. Only `to` is required. Omit `instance_id`
919
+ # to let the gateway auto-pick a number from your pool (rotation + conversation affinity) — the
920
+ # recommended path. Provide it ONLY to FORCE the send from a specific number. Get ids from `GET
921
+ # /instances`.
922
+ # @param pool_id [String, nil] (corpo) Rotates within this pool (when instance_id is omitted).
923
+ # @param sticky [Boolean, nil] (corpo) Conversation affinity (support): without
924
+ # instance_id/pool_id, it AUTOMATICALLY reuses the number that already talks to `to`, ensuring
925
+ # the whole interaction stays on the same number. Default **true**; send **false** to force
926
+ # rotation (e.g. campaign/broadcast).
927
+ # @param to [String] (corpo) Destination: E.164 phone (+DDIdigits), contact JID
928
+ # (…@s.whatsapp.net), group JID (…@g.us) or the contact's @lid. A @lid is translated to the
929
+ # phone when the connected number knows it; the official rail accepts phone only.
930
+ # @param quoted_message_id [String, nil] (corpo) Quoted wa_message_id (reply).
931
+ # @param quoted_participant [String, nil] (corpo) Author (phone or JID) of the quoted/reacted
932
+ # message. Only needed in groups when the quoted message is not in bZapper history — otherwise
933
+ # it is resolved automatically.
934
+ # @param client_reference [String, nil] (corpo) Client end-to-end correlation.
935
+ # @param mentions [Array<String>, nil] (corpo) Mentioned people (group): phones ("5511…", "+55
936
+ # 11 9…") or JIDs. The body must contain "@<digits>" for the mention to be highlighted.
937
+ # @param scheduled_at [Time, String, nil] (corpo) OPTIONAL. Schedule the send for a future
938
+ # RFC3339 timestamp. The gateway holds the message and dispatches it at that exact time (the
939
+ # number is picked at send time). Max lead time by plan: Free 24h, Pro 30 days, and up to 1 year
940
+ # with the "Extended scheduling" add-on. Returns status `scheduled` with a `scheduled_id`. OTP
941
+ # cannot be scheduled.
942
+ # @param groups [Array<String>, nil] (corpo) OPTIONAL. Contact-group keys to correlate/stamp
943
+ # onto the recipient contact when this send resolves (see `GET /contact-groups`). Does not send
944
+ # the message to a WhatsApp group.
945
+ # @param tags [Array<String>, nil] (corpo) OPTIONAL. Tag keys to correlate/stamp onto the
946
+ # recipient contact when this send resolves (see `GET /tags`).
947
+ # @param force [Boolean, nil] (corpo) OPTIONAL. When true, bypasses an inferred suppression
948
+ # (e.g. opt-out inferred from behaviour) for this send. Does NOT override an explicit
949
+ # suppression entry (`/suppressions`) — use with care and only with a lawful basis.
950
+ # @param template [String] (corpo) Template NAME. The id Meta assigned to it never appears here.
951
+ # @param language [String, nil] (corpo) e.g. pt_BR. May be omitted when the name exists in a
952
+ # single language; if it exists in more than one, the answer is 409 template_ambiguous.
953
+ # @param variables [Array<String>, nil] (corpo) Body values, in order ({{1}}, {{2}}, …). The
954
+ # count must match the approved template exactly — a mismatch is the number one cause of Meta
955
+ # error 132000.
956
+ # @param header_variables [Array<String>, nil] (corpo) Text header: the value of its variable.
957
+ # Image, video or document header: the media URL for THIS send in the first position — omitted,
958
+ # the sample media registered when the template was created goes out (Meta requires the media on
959
+ # every send).
960
+ # @param button_variables [Array<String>, nil] (corpo) Values for dynamic URL buttons, by button
961
+ # index. Empty entries are skipped.
962
+ # @param code [String, nil] (corpo) AUTHENTICATION templates only. Meta requires the code both
963
+ # in the body and in the copy-code button; we place it in both.
964
+ # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
965
+ # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
966
+ # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
967
+ # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
968
+ def send_template(to:, template:, instance_id: UNSET, pool_id: UNSET, sticky: UNSET,
969
+ quoted_message_id: UNSET, quoted_participant: UNSET,
970
+ client_reference: UNSET, mentions: UNSET, scheduled_at: UNSET,
971
+ groups: UNSET, tags: UNSET, force: UNSET, language: UNSET,
972
+ variables: UNSET, header_variables: UNSET, button_variables: UNSET,
973
+ code: UNSET, idempotency_key: nil, timeout: nil)
974
+ payload = compact(
975
+ "instance_id" => instance_id,
976
+ "pool_id" => pool_id,
977
+ "sticky" => sticky,
978
+ "to" => to,
979
+ "quoted_message_id" => quoted_message_id,
980
+ "quoted_participant" => quoted_participant,
981
+ "client_reference" => client_reference,
982
+ "mentions" => mentions,
983
+ "scheduled_at" => scheduled_at,
984
+ "groups" => groups,
985
+ "tags" => tags,
986
+ "force" => force,
987
+ "template" => template,
988
+ "language" => language,
989
+ "variables" => variables,
990
+ "header_variables" => header_variables,
991
+ "button_variables" => button_variables,
992
+ "code" => code
993
+ )
994
+ request("POST",
995
+ "/messages/template",
996
+ body: payload,
997
+ idempotency_key: idempotency_key,
998
+ timeout: timeout)
999
+ end
1000
+
869
1001
  # Mark messages as read. `POST /messages/{id}/read`
870
1002
  #
871
1003
  # @param id [String] WhatsApp message id to mark read (used when the body has no `message_ids`).