bzapper 0.8.2 → 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: c256b4bd21ae63812d103200cd409f3219afd1312e5bd1294a35c6bc917b437c
4
- data.tar.gz: 2d90d51e0b528128c7d86096cb865116089c4fe4a88f7be2a5fa82f118994979
3
+ metadata.gz: 1a8e0c8a695ae7a7806613f902d9355715a0239d1f34b54bd795b9360ad54466
4
+ data.tar.gz: d40cdd05ab273cc3bf98b9e14c5aabf23c4ff2ac44dc13f5bbb2fbcf855c40ab
5
5
  SHA512:
6
- metadata.gz: 4649dc966b6e70b094a9df4474312444d0e62b7b5b3c247ca23faa8d469b1a361768060e96aaeb00e45a9e062fc3164070e1bf5e2bd89fdddbea5d8ba3bd28e1
7
- data.tar.gz: cbf1117963bde306d24d7044531758245712e71dabed736281ee20496476dda531aee8be965a98fa93402d645e11cf840a8b332a6abe4135040dd463efec77a5
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.2
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.2"
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 |
@@ -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
@@ -105,7 +105,8 @@ module Bzapper
105
105
  # @param force [Boolean, nil] (corpo) OPTIONAL. When true, bypasses an inferred suppression
106
106
  # (e.g. opt-out inferred from behaviour) for this send. Does NOT override an explicit
107
107
  # suppression entry (`/suppressions`) — use with care and only with a lawful basis.
108
- # @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`).
109
110
  # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
110
111
  # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
111
112
  # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
@@ -170,7 +171,8 @@ module Bzapper
170
171
  # @param force [Boolean, nil] (corpo) OPTIONAL. When true, bypasses an inferred suppression
171
172
  # (e.g. opt-out inferred from behaviour) for this send. Does NOT override an explicit
172
173
  # suppression entry (`/suppressions`) — use with care and only with a lawful basis.
173
- # @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`).
174
176
  # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
175
177
  # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
176
178
  # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
@@ -235,7 +237,8 @@ module Bzapper
235
237
  # @param force [Boolean, nil] (corpo) OPTIONAL. When true, bypasses an inferred suppression
236
238
  # (e.g. opt-out inferred from behaviour) for this send. Does NOT override an explicit
237
239
  # suppression entry (`/suppressions`) — use with care and only with a lawful basis.
238
- # @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`).
239
242
  # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
240
243
  # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
241
244
  # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
@@ -301,7 +304,8 @@ module Bzapper
301
304
  # @param force [Boolean, nil] (corpo) OPTIONAL. When true, bypasses an inferred suppression
302
305
  # (e.g. opt-out inferred from behaviour) for this send. Does NOT override an explicit
303
306
  # suppression entry (`/suppressions`) — use with care and only with a lawful basis.
304
- # @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`).
305
309
  # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
306
310
  # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
307
311
  # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
@@ -366,7 +370,8 @@ module Bzapper
366
370
  # @param force [Boolean, nil] (corpo) OPTIONAL. When true, bypasses an inferred suppression
367
371
  # (e.g. opt-out inferred from behaviour) for this send. Does NOT override an explicit
368
372
  # suppression entry (`/suppressions`) — use with care and only with a lawful basis.
369
- # @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`).
370
375
  # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
371
376
  # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
372
377
  # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
@@ -898,6 +903,101 @@ module Bzapper
898
903
  timeout: timeout)
899
904
  end
900
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
+
901
1001
  # Mark messages as read. `POST /messages/{id}/read`
902
1002
  #
903
1003
  # @param id [String] WhatsApp message id to mark read (used when the body has no `message_ids`).
@@ -0,0 +1,499 @@
1
+ # frozen_string_literal: true
2
+
3
+ # GERADO por script/generate.rb a partir de packages/sdk/openapi.yaml — não edite à mão.
4
+
5
+ module Bzapper
6
+ module Resources
7
+ # Trilho oficial (WhatsApp Cloud API): conta WABA, Embedded Signup, números e perfil comercial — `client.official`.
8
+ class Official < Base
9
+ # Read the WhatsApp Business Account connected to the project. `GET /official/account`
10
+ #
11
+ # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
12
+ # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
13
+ # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
14
+ def get_official_account(timeout: nil)
15
+ request("GET", "/official/account", timeout: timeout)
16
+ end
17
+
18
+ # Connect (or reconnect) a WhatsApp Business Account to the project. `POST /official/account`
19
+ #
20
+ # Stores the customer's Meta credentials for the project. Calling it again replaces them — that
21
+ # is the reconnection path when a token is revoked, and it never creates a second account for
22
+ # the same project. `phone_number_id` is optional: when omitted, the number is discovered from
23
+ # the WABA. If the WABA holds more than one number the call returns 409 with the list, so the
24
+ # choice stays with the account owner instead of being guessed.
25
+ #
26
+ # @param waba_id [String] (corpo)
27
+ # @param phone_number_id [String, nil] (corpo) Optional — discovered from the WABA when omitted.
28
+ # @param access_token [String] (corpo) The customer's WABA token, stored encrypted at rest. A
29
+ # token taken from Meta's "API Setup" screen expires in 24h; for a lasting connection use a
30
+ # system user with `whatsapp_business_messaging` + `whatsapp_business_management`.
31
+ # @param display_number [String, nil] (corpo)
32
+ # @param verified_name [String, nil] (corpo)
33
+ # @param status [String, nil] (corpo) Empty means PENDENTE, which is the correct state coming
34
+ # out of Embedded Signup.
35
+ # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
36
+ # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
37
+ # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
38
+ # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
39
+ def connect_official_account(waba_id:, access_token:, phone_number_id: UNSET,
40
+ display_number: UNSET, verified_name: UNSET, status: UNSET,
41
+ idempotency_key: nil, timeout: nil)
42
+ payload = compact(
43
+ "waba_id" => waba_id,
44
+ "phone_number_id" => phone_number_id,
45
+ "access_token" => access_token,
46
+ "display_number" => display_number,
47
+ "verified_name" => verified_name,
48
+ "status" => status
49
+ )
50
+ request("POST",
51
+ "/official/account",
52
+ body: payload,
53
+ idempotency_key: idempotency_key,
54
+ timeout: timeout)
55
+ end
56
+
57
+ # Disconnect the account from the project. `DELETE /official/account`
58
+ #
59
+ # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
60
+ # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
61
+ # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
62
+ # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
63
+ def disconnect_official_account(idempotency_key: nil, timeout: nil)
64
+ request("DELETE", "/official/account", idempotency_key: idempotency_key, timeout: timeout)
65
+ end
66
+
67
+ # Read what the browser needs to open Meta's Embedded Signup. `GET /official/signup-config`
68
+ #
69
+ # Returns the app and configuration ids the Meta JS SDK needs. Both are public by nature — the
70
+ # customer's browser sees them. The app secret never leaves the server: the one-time `code` the
71
+ # popup returns is exchanged for a token server-side. `enabled` false means this installation
72
+ # has no Embedded Signup configured, and the UI should offer the manual path instead of a button
73
+ # that cannot work.
74
+ #
75
+ # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
76
+ # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
77
+ # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
78
+ def get_official_signup_config(timeout: nil)
79
+ request("GET", "/official/signup-config", timeout: timeout)
80
+ end
81
+
82
+ # Finish the connection with the code returned by Meta's popup. `POST /official/embedded-signup`
83
+ #
84
+ # Exchanges the one-time `code` for a lasting token, subscribes the app to the WABA's webhooks
85
+ # and registers the number on the Cloud API. The customer never sees or types a credential. The
86
+ # code expires about 30 seconds after the popup closes, so send it straight through. A non-fatal
87
+ # step that fails comes back in `warning` instead of losing the whole connection: the account is
88
+ # stored either way and the UI offers a retry.
89
+ #
90
+ # @param code [String] (corpo) One-time code from the Embedded Signup callback (~30s lifetime).
91
+ # @param waba_id [String] (corpo)
92
+ # @param phone_number_id [String, nil] (corpo) Optional — discovered from the WABA when the
93
+ # popup does not provide it.
94
+ # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
95
+ # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
96
+ # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
97
+ # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
98
+ def complete_official_signup(code:, waba_id:, phone_number_id: UNSET, idempotency_key: nil,
99
+ timeout: nil)
100
+ payload = compact(
101
+ "code" => code,
102
+ "waba_id" => waba_id,
103
+ "phone_number_id" => phone_number_id
104
+ )
105
+ request("POST",
106
+ "/official/embedded-signup",
107
+ body: payload,
108
+ idempotency_key: idempotency_key,
109
+ timeout: timeout)
110
+ end
111
+
112
+ # What is ready and what is missing, checked live against Meta. `GET /official/status`
113
+ #
114
+ # Joins what we store with what Meta reports right now: whether the number is verified, whether
115
+ # the display name and the business passed review, quality and volume tier. `live` false means
116
+ # Meta could not be reached and the values are the last known ones — the difference between
117
+ # "this is how it is" and "we could not check" matters to the caller.
118
+ #
119
+ # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
120
+ # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
121
+ # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
122
+ def get_official_status(timeout: nil)
123
+ request("GET", "/official/status", timeout: timeout)
124
+ end
125
+
126
+ # Upload a file to Meta once and reuse it in many sends (multipart). `POST /official/media`
127
+ #
128
+ # Uploads the file to Meta through the project's default number (or `instance_id`) and returns
129
+ # its `id`. Send it as `media.id` in any media send — Meta does not download the file again for
130
+ # each message, which is what you want for the same image in a whole campaign. The id is valid
131
+ # for 30 days and only for sends from the number that uploaded it. Accepted (Meta's limits):
132
+ # image JPEG/PNG up to 5 MB, sticker WebP up to 500 KB, video MP4/3GP and audio
133
+ # AAC/AMR/MP3/MP4/OGG up to 16 MB, document PDF/Office/text up to 64 MB.
134
+ #
135
+ # @param file [String, IO, Pathname] conteúdo do arquivo (bytes), um IO ou o caminho no disco.
136
+ # @param filename [String, nil] nome do arquivo (padrão: o do caminho, senão "file").
137
+ # @param content_type [String, nil] tipo MIME (padrão: application/octet-stream).
138
+ # @param instance_id [String, nil] (query) Number that uploads (and may send) it. Default: the
139
+ # project default.
140
+ # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
141
+ # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
142
+ # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
143
+ # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
144
+ def upload_official_media(file:, filename: nil, content_type: nil, instance_id: nil,
145
+ idempotency_key: nil, timeout: nil)
146
+ query = {
147
+ "instance_id" => instance_id
148
+ }
149
+ request("POST",
150
+ "/official/media",
151
+ query: query,
152
+ multipart: upload("file", file, filename, content_type),
153
+ idempotency_key: idempotency_key,
154
+ timeout: timeout)
155
+ end
156
+
157
+ # Check that a media id is still valid. `GET /official/media/{media_id}`
158
+ #
159
+ # Returns what Meta knows about the file (type, size, sha256). Meta's download URL is not
160
+ # returned: it only opens with the account token, which never leaves bZapper.
161
+ #
162
+ # @param media_id [String] parâmetro de caminho
163
+ # @param instance_id [String, nil] (query) Number that uploaded it. Default: the project
164
+ # default.
165
+ # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
166
+ # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
167
+ # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
168
+ # @raise [ArgumentError] parâmetro de caminho vazio, "." ou "..".
169
+ def get_official_media(media_id, instance_id: nil, timeout: nil)
170
+ query = {
171
+ "instance_id" => instance_id
172
+ }
173
+ request("GET",
174
+ "/official/media/#{segment(media_id, "media_id")}",
175
+ query: query,
176
+ timeout: timeout)
177
+ end
178
+
179
+ # Delete a media file from Meta before it expires. `DELETE /official/media/{media_id}`
180
+ #
181
+ # @param media_id [String] parâmetro de caminho
182
+ # @param instance_id [String, nil] (query) Number that uploaded it. Default: the project
183
+ # default.
184
+ # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
185
+ # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
186
+ # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
187
+ # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
188
+ # @raise [ArgumentError] parâmetro de caminho vazio, "." ou "..".
189
+ def delete_official_media(media_id, instance_id: nil, idempotency_key: nil, timeout: nil)
190
+ query = {
191
+ "instance_id" => instance_id
192
+ }
193
+ request("DELETE",
194
+ "/official/media/#{segment(media_id, "media_id")}",
195
+ query: query,
196
+ idempotency_key: idempotency_key,
197
+ timeout: timeout)
198
+ end
199
+
200
+ # List the raw events Meta sent for the project's accounts. `GET /official/webhook-events`
201
+ #
202
+ # The "Meta → bZapper" side of webhooks: each event Meta delivered for the project's business
203
+ # accounts, exactly as Meta signed it, with how bZapper processed it (`pending`, `running`,
204
+ # `done` or `failed`, attempts and the last error). Together with the webhook deliveries
205
+ # (`listWebhookDeliveries`), it shows the whole chain — and, when an event does not reach your
206
+ # system, on which side it stopped. Newest first; pass the last `id` as `before` to page back.
207
+ # Events are kept for 3 days after being applied, 30 when they failed. Requires the
208
+ # `webhooks:manage` scope.
209
+ #
210
+ # @param limit [Integer, nil] (query) 1–200 (default 50).
211
+ # @param before [Integer, nil] (query) Return only events older than this id (pagination).
212
+ # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
213
+ # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
214
+ # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
215
+ def list_meta_webhook_events(limit: nil, before: nil, timeout: nil)
216
+ query = {
217
+ "limit" => limit,
218
+ "before" => before
219
+ }
220
+ request("GET", "/official/webhook-events", query: query, timeout: timeout)
221
+ end
222
+
223
+ # List the numbers connected to the project. `GET /official/numbers`
224
+ #
225
+ # Meta allows several numbers on one business account. Each connected number has an
226
+ # `instance_id` — the same value you pass in a send to choose which number it goes out from,
227
+ # exactly as on the unofficial rail. The one flagged `is_default` sends when the request does
228
+ # not pick one.
229
+ #
230
+ # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
231
+ # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
232
+ # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
233
+ def list_official_numbers(timeout: nil)
234
+ request("GET", "/official/numbers", timeout: timeout)
235
+ end
236
+
237
+ # Connect one more number from the same business account. `POST /official/numbers`
238
+ #
239
+ # Reuses the authorization already stored — it belongs to the account, not to the number — so
240
+ # nothing has to be authorized again. Pick the id from GET /official/numbers/available. The
241
+ # number is checked against Meta before it is saved, so a wrong id fails here and not on the
242
+ # first send.
243
+ #
244
+ # @param phone_number_id [String] (corpo) Meta's id of the number (`id` from GET
245
+ # /official/numbers/available).
246
+ # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
247
+ # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
248
+ # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
249
+ # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
250
+ def add_official_number(phone_number_id:, idempotency_key: nil, timeout: nil)
251
+ payload = compact(
252
+ "phone_number_id" => phone_number_id
253
+ )
254
+ request("POST",
255
+ "/official/numbers",
256
+ body: payload,
257
+ idempotency_key: idempotency_key,
258
+ timeout: timeout)
259
+ end
260
+
261
+ # List the account's numbers that are not connected to the project yet. `GET
262
+ # /official/numbers/available`
263
+ #
264
+ # What feeds "add a number": the numbers the business account holds on Meta, minus the ones
265
+ # already connected here — without opening Meta's dashboard.
266
+ #
267
+ # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
268
+ # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
269
+ # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
270
+ def list_available_official_numbers(timeout: nil)
271
+ request("GET", "/official/numbers/available", timeout: timeout)
272
+ end
273
+
274
+ # Choose the number that sends when the request does not pick one. `PUT
275
+ # /official/numbers/{id}/default`
276
+ #
277
+ # @param id [String] parâmetro de caminho
278
+ # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
279
+ # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
280
+ # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
281
+ # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
282
+ # @raise [ArgumentError] parâmetro de caminho vazio, "." ou "..".
283
+ def set_default_official_number(id, idempotency_key: nil, timeout: nil)
284
+ request("PUT",
285
+ "/official/numbers/#{segment(id, "id")}/default",
286
+ idempotency_key: idempotency_key,
287
+ timeout: timeout)
288
+ end
289
+
290
+ # Disconnect one number. `DELETE /official/numbers/{id}`
291
+ #
292
+ # The conversation history stays: the mirror instance is archived, not deleted. Removing the
293
+ # default promotes the oldest of the remaining numbers, so the project never ends up with
294
+ # numbers and no default.
295
+ #
296
+ # @param id [String] parâmetro de caminho
297
+ # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
298
+ # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
299
+ # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
300
+ # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
301
+ # @raise [ArgumentError] parâmetro de caminho vazio, "." ou "..".
302
+ def disconnect_official_number(id, idempotency_key: nil, timeout: nil)
303
+ request("DELETE",
304
+ "/official/numbers/#{segment(id, "id")}",
305
+ idempotency_key: idempotency_key,
306
+ timeout: timeout)
307
+ end
308
+
309
+ # Read the business profile of the project's default number. `GET /official/profile`
310
+ #
311
+ # The business profile is what the end customer sees when opening the chat: short "about" line,
312
+ # description, address, e-mail, sector and up to two websites. It lives on the NUMBER, not on
313
+ # the account — with several numbers, each has its own.
314
+ #
315
+ # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
316
+ # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
317
+ # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
318
+ def get_official_profile(timeout: nil)
319
+ request("GET", "/official/profile", timeout: timeout)
320
+ end
321
+
322
+ # Update the business profile of the project's default number. `PUT /official/profile`
323
+ #
324
+ # Validated against Meta's published limits BEFORE sending (about 139 characters, description
325
+ # 512, address 256, at most 2 websites, a closed list of sectors), so a refusal names the field
326
+ # and by how much it overflowed instead of Meta's generic "Invalid parameter". Send the WHOLE
327
+ # profile: an empty field is not "unchanged", it clears that field on Meta. Read it first with
328
+ # GET and send it back with your edits.
329
+ #
330
+ # @param about [String, nil] (corpo) Short line under the name.
331
+ # @param description [String, nil] (corpo)
332
+ # @param address [String, nil] (corpo)
333
+ # @param email [String, nil] (corpo)
334
+ # @param vertical [String, nil] (corpo) Business sector (closed list defined by Meta).
335
+ # @param websites [Array<String>, nil] (corpo)
336
+ # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
337
+ # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
338
+ # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
339
+ # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
340
+ def update_official_profile(about: UNSET, description: UNSET, address: UNSET, email: UNSET,
341
+ vertical: UNSET, websites: UNSET, idempotency_key: nil,
342
+ timeout: nil)
343
+ payload = compact(
344
+ "about" => about,
345
+ "description" => description,
346
+ "address" => address,
347
+ "email" => email,
348
+ "vertical" => vertical,
349
+ "websites" => websites
350
+ )
351
+ request("PUT",
352
+ "/official/profile",
353
+ body: payload,
354
+ idempotency_key: idempotency_key,
355
+ timeout: timeout)
356
+ end
357
+
358
+ # Replace the profile photo of the project's default number (multipart, JPEG/PNG up to 5 MB).
359
+ # `POST /official/profile/photo`
360
+ #
361
+ # Uploads the image to Meta and sets it as the profile photo in one call. WhatsApp Business has
362
+ # only the round profile photo — there is no cover image. Meta recommends 640x640.
363
+ #
364
+ # @param file [String, IO, Pathname] conteúdo do arquivo (bytes), um IO ou o caminho no disco.
365
+ # @param filename [String, nil] nome do arquivo (padrão: o do caminho, senão "file").
366
+ # @param content_type [String, nil] tipo MIME (padrão: application/octet-stream).
367
+ # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
368
+ # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
369
+ # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
370
+ # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
371
+ def upload_official_profile_photo(file:, filename: nil, content_type: nil,
372
+ idempotency_key: nil, timeout: nil)
373
+ request("POST",
374
+ "/official/profile/photo",
375
+ multipart: upload("file", file, filename, content_type),
376
+ idempotency_key: idempotency_key,
377
+ timeout: timeout)
378
+ end
379
+
380
+ # Re-register the project's default number on the Cloud API. `POST /official/profile/reregister`
381
+ #
382
+ # The step people forget after Meta approves a new display name: until the number is
383
+ # re-registered it keeps showing the old name. Requesting the name change itself is not an API
384
+ # call (it is done in WhatsApp Manager); this is the half that is. Already registered counts as
385
+ # success.
386
+ #
387
+ # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
388
+ # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
389
+ # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
390
+ # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
391
+ def reregister_official_profile(idempotency_key: nil, timeout: nil)
392
+ request("POST",
393
+ "/official/profile/reregister",
394
+ idempotency_key: idempotency_key,
395
+ timeout: timeout)
396
+ end
397
+
398
+ # Read the business profile of the number given in the path. `GET
399
+ # /official/numbers/{id}/profile`
400
+ #
401
+ # The business profile is what the end customer sees when opening the chat: short "about" line,
402
+ # description, address, e-mail, sector and up to two websites. It lives on the NUMBER, not on
403
+ # the account — with several numbers, each has its own.
404
+ #
405
+ # @param id [String] Connected number id (`id` from GET /official/numbers).
406
+ # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
407
+ # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
408
+ # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
409
+ # @raise [ArgumentError] parâmetro de caminho vazio, "." ou "..".
410
+ def get_official_number_profile(id, timeout: nil)
411
+ request("GET", "/official/numbers/#{segment(id, "id")}/profile", timeout: timeout)
412
+ end
413
+
414
+ # Update the business profile of the number given in the path. `PUT
415
+ # /official/numbers/{id}/profile`
416
+ #
417
+ # Validated against Meta's published limits BEFORE sending (about 139 characters, description
418
+ # 512, address 256, at most 2 websites, a closed list of sectors), so a refusal names the field
419
+ # and by how much it overflowed instead of Meta's generic "Invalid parameter". Send the WHOLE
420
+ # profile: an empty field is not "unchanged", it clears that field on Meta. Read it first with
421
+ # GET and send it back with your edits.
422
+ #
423
+ # @param id [String] Connected number id (`id` from GET /official/numbers).
424
+ # @param about [String, nil] (corpo) Short line under the name.
425
+ # @param description [String, nil] (corpo)
426
+ # @param address [String, nil] (corpo)
427
+ # @param email [String, nil] (corpo)
428
+ # @param vertical [String, nil] (corpo) Business sector (closed list defined by Meta).
429
+ # @param websites [Array<String>, nil] (corpo)
430
+ # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
431
+ # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
432
+ # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
433
+ # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
434
+ # @raise [ArgumentError] parâmetro de caminho vazio, "." ou "..".
435
+ def update_official_number_profile(id, about: UNSET, description: UNSET, address: UNSET,
436
+ email: UNSET, vertical: UNSET, websites: UNSET,
437
+ idempotency_key: nil, timeout: nil)
438
+ payload = compact(
439
+ "about" => about,
440
+ "description" => description,
441
+ "address" => address,
442
+ "email" => email,
443
+ "vertical" => vertical,
444
+ "websites" => websites
445
+ )
446
+ request("PUT",
447
+ "/official/numbers/#{segment(id, "id")}/profile",
448
+ body: payload,
449
+ idempotency_key: idempotency_key,
450
+ timeout: timeout)
451
+ end
452
+
453
+ # Replace the profile photo of the number given in the path (multipart, JPEG/PNG up to 5 MB).
454
+ # `POST /official/numbers/{id}/profile/photo`
455
+ #
456
+ # Uploads the image to Meta and sets it as the profile photo in one call. WhatsApp Business has
457
+ # only the round profile photo — there is no cover image. Meta recommends 640x640.
458
+ #
459
+ # @param id [String] Connected number id (`id` from GET /official/numbers).
460
+ # @param file [String, IO, Pathname] conteúdo do arquivo (bytes), um IO ou o caminho no disco.
461
+ # @param filename [String, nil] nome do arquivo (padrão: o do caminho, senão "file").
462
+ # @param content_type [String, nil] tipo MIME (padrão: application/octet-stream).
463
+ # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
464
+ # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
465
+ # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
466
+ # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
467
+ # @raise [ArgumentError] parâmetro de caminho vazio, "." ou "..".
468
+ def upload_official_number_profile_photo(id, file:, filename: nil, content_type: nil,
469
+ idempotency_key: nil, timeout: nil)
470
+ request("POST",
471
+ "/official/numbers/#{segment(id, "id")}/profile/photo",
472
+ multipart: upload("file", file, filename, content_type),
473
+ idempotency_key: idempotency_key,
474
+ timeout: timeout)
475
+ end
476
+
477
+ # Re-register the number given in the path on the Cloud API. `POST
478
+ # /official/numbers/{id}/profile/reregister`
479
+ #
480
+ # The step people forget after Meta approves a new display name: until the number is
481
+ # re-registered it keeps showing the old name. Requesting the name change itself is not an API
482
+ # call (it is done in WhatsApp Manager); this is the half that is. Already registered counts as
483
+ # success.
484
+ #
485
+ # @param id [String] Connected number id (`id` from GET /official/numbers).
486
+ # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
487
+ # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
488
+ # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
489
+ # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
490
+ # @raise [ArgumentError] parâmetro de caminho vazio, "." ou "..".
491
+ def reregister_official_number_profile(id, idempotency_key: nil, timeout: nil)
492
+ request("POST",
493
+ "/official/numbers/#{segment(id, "id")}/profile/reregister",
494
+ idempotency_key: idempotency_key,
495
+ timeout: timeout)
496
+ end
497
+ end
498
+ end
499
+ end
@@ -0,0 +1,171 @@
1
+ # frozen_string_literal: true
2
+
3
+ # GERADO por script/generate.rb a partir de packages/sdk/openapi.yaml — não edite à mão.
4
+
5
+ module Bzapper
6
+ module Resources
7
+ # Templates de mensagem aprovados pela Meta (trilho oficial): criar, sincronizar, mídia e fallback — `client.templates`.
8
+ class Templates < Base
9
+ # List the project templates. `GET /templates`
10
+ #
11
+ # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
12
+ # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
13
+ # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
14
+ def list_templates(timeout: nil)
15
+ request("GET", "/templates", timeout: timeout)
16
+ end
17
+
18
+ # Create a template and submit it to Meta for review. `POST /templates`
19
+ #
20
+ # You describe header, body, footer and buttons; we build the component format Meta expects —
21
+ # with its examples nested three levels deep and the rules it does not document alongside.
22
+ # Validation happens BEFORE submission, and that is where this endpoint earns its keep: Meta
23
+ # takes up to 24 hours to answer, rejects with a terse reason, and caps how many templates you
24
+ # may submit. A variable at the start or end of the body, numbering that skips, two variables
25
+ # side by side, a missing example — each returns 422 with a message that says what to fix.
26
+ # `advice` comes back with things that did not block the submission but change the outcome —
27
+ # promotional wording in a UTILITY template, for instance, which Meta reclassifies on its own,
28
+ # and reclassification changes what the conversation COSTS. The decision arrives later through
29
+ # the `template.approved` / `template.rejected` webhooks.
30
+ #
31
+ # @param name [String] (corpo) Lowercase letters, numbers and _. This is the name you send by.
32
+ # @param language [String] (corpo) e.g. pt_BR. Both pt-BR and pt_BR are accepted.
33
+ # @param category [String] (corpo) Decides what the conversation COSTS and what Meta accepts in
34
+ # the content — not an administrative label. UTILITY is cheaper but only covers what the
35
+ # customer already expects; promotional wording in it gets reclassified, and the price changes
36
+ # with it.
37
+ # @param header [Hash, nil] (corpo)
38
+ # @param body [Hash] (corpo)
39
+ # @param footer [String, nil] (corpo) Up to 60 characters. Accepts no variables.
40
+ # @param buttons [Array<Hash>, nil] (corpo)
41
+ # @param code_expiry_minutes [Integer, nil] (corpo) AUTHENTICATION only, 1 to 90. In that
42
+ # category Meta writes the text itself and adds the copy-code button; this is the only thing you
43
+ # set.
44
+ # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
45
+ # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
46
+ # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
47
+ # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
48
+ def create_template(name:, language:, category:, body:, header: UNSET, footer: UNSET,
49
+ buttons: UNSET, code_expiry_minutes: UNSET, idempotency_key: nil,
50
+ timeout: nil)
51
+ payload = compact(
52
+ "name" => name,
53
+ "language" => language,
54
+ "category" => category,
55
+ "header" => header,
56
+ "body" => body,
57
+ "footer" => footer,
58
+ "buttons" => buttons,
59
+ "code_expiry_minutes" => code_expiry_minutes
60
+ )
61
+ request("POST",
62
+ "/templates",
63
+ body: payload,
64
+ idempotency_key: idempotency_key,
65
+ timeout: timeout)
66
+ end
67
+
68
+ # Get one template. `GET /templates/{id}`
69
+ #
70
+ # @param id [String] parâmetro de caminho
71
+ # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
72
+ # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
73
+ # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
74
+ # @raise [ArgumentError] parâmetro de caminho vazio, "." ou "..".
75
+ def get_template(id, timeout: nil)
76
+ request("GET", "/templates/#{segment(id, "id")}", timeout: timeout)
77
+ end
78
+
79
+ # Delete a template. `DELETE /templates/{id}`
80
+ #
81
+ # Removes it here and at Meta. Meta deletes ALL languages of a name at once — so when another
82
+ # language of the same name is still registered here, we leave Meta alone rather than delete
83
+ # something you did not ask to delete.
84
+ #
85
+ # @param id [String] parâmetro de caminho
86
+ # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
87
+ # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
88
+ # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
89
+ # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
90
+ # @raise [ArgumentError] parâmetro de caminho vazio, "." ou "..".
91
+ def delete_template(id, idempotency_key: nil, timeout: nil)
92
+ request("DELETE",
93
+ "/templates/#{segment(id, "id")}",
94
+ idempotency_key: idempotency_key,
95
+ timeout: timeout)
96
+ end
97
+
98
+ # Import templates that exist at Meta and not here. `POST /templates/sync`
99
+ #
100
+ # For the account that already used the Cloud API before bZapper and created templates in
101
+ # WhatsApp Manager, and to repair a webhook that never arrived. Without it those templates would
102
+ # exist for Meta and be invisible here — and sending by name would say they do not exist.
103
+ #
104
+ # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
105
+ # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
106
+ # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
107
+ # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
108
+ def sync_templates(idempotency_key: nil, timeout: nil)
109
+ request("POST", "/templates/sync", idempotency_key: idempotency_key, timeout: timeout)
110
+ end
111
+
112
+ # Get the project fallback template. `GET /templates/fallback`
113
+ #
114
+ # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
115
+ # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
116
+ # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
117
+ def get_fallback_template(timeout: nil)
118
+ request("GET", "/templates/fallback", timeout: timeout)
119
+ end
120
+
121
+ # Set the template sent when the 24-hour window is closed. `PUT /templates/fallback`
122
+ #
123
+ # This is what makes the same `POST /messages/text` work inside and outside the window. When the
124
+ # contact has not written for over 24 hours, free text is refused by Meta; with a fallback
125
+ # configured, the platform sends this approved template instead and reports the detour in the
126
+ # `delivery` field of the response. Only an APPROVED template is accepted: a fallback that
127
+ # cannot be sent would only postpone the failure to the first send outside the window. An empty
128
+ # `template_id` clears it.
129
+ #
130
+ # @param template_id [String, nil] (corpo) Empty clears the fallback.
131
+ # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
132
+ # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
133
+ # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
134
+ # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
135
+ def set_fallback_template(template_id: UNSET, idempotency_key: nil, timeout: nil)
136
+ payload = compact(
137
+ "template_id" => template_id
138
+ )
139
+ request("PUT",
140
+ "/templates/fallback",
141
+ body: payload,
142
+ idempotency_key: idempotency_key,
143
+ timeout: timeout)
144
+ end
145
+
146
+ # Upload the header sample of a template (multipart, JPEG/PNG/MP4/PDF up to 10 MB). `POST
147
+ # /templates/media`
148
+ #
149
+ # Meta reviews media headers from a sample file. Upload it here and pass the returned `url` as
150
+ # `header.media_url` in POST /templates — no need to host the file anywhere. It is only the
151
+ # sample Meta reviews, not the media that goes out on each send. Samples never used by a
152
+ # template are cleaned up.
153
+ #
154
+ # @param file [String, IO, Pathname] conteúdo do arquivo (bytes), um IO ou o caminho no disco.
155
+ # @param filename [String, nil] nome do arquivo (padrão: o do caminho, senão "file").
156
+ # @param content_type [String, nil] tipo MIME (padrão: application/octet-stream).
157
+ # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
158
+ # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
159
+ # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
160
+ # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
161
+ def upload_template_media(file:, filename: nil, content_type: nil, idempotency_key: nil,
162
+ timeout: nil)
163
+ request("POST",
164
+ "/templates/media",
165
+ multipart: upload("file", file, filename, content_type),
166
+ idempotency_key: idempotency_key,
167
+ timeout: timeout)
168
+ end
169
+ end
170
+ end
171
+ end
@@ -124,6 +124,27 @@ module Bzapper
124
124
  request("GET", "/webhooks/#{segment(id, "id")}/deliveries", query: query, timeout: timeout)
125
125
  end
126
126
 
127
+ # Redeliver a failed delivery. `POST /webhooks/{id}/deliveries/{delivery_id}/redeliver`
128
+ #
129
+ # Sends a FAILED delivery again: same body and same event_id (your idempotency keeps working),
130
+ # signed with the webhook's CURRENT secret. One attempt; the outcome updates the delivery. Only
131
+ # deliveries that failed in the last 7 days can be redelivered — the body carries conversation
132
+ # content and is kept only for that long.
133
+ #
134
+ # @param id [String] Webhook ID (UUID).
135
+ # @param delivery_id [String] Delivery id (from listWebhookDeliveries).
136
+ # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
137
+ # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
138
+ # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
139
+ # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
140
+ # @raise [ArgumentError] parâmetro de caminho vazio, "." ou "..".
141
+ def redeliver_webhook_delivery(id, delivery_id, idempotency_key: nil, timeout: nil)
142
+ request("POST",
143
+ "/webhooks/#{segment(id, "id")}/deliveries/#{segment(delivery_id, "delivery_id")}/redeliver",
144
+ idempotency_key: idempotency_key,
145
+ timeout: timeout)
146
+ end
147
+
127
148
  # Emit a sample event to the project's stream and webhooks (like `stripe trigger`). `POST
128
149
  # /webhooks/trigger`
129
150
  #
@@ -19,6 +19,8 @@ require_relative "resources/advisories"
19
19
  require_relative "resources/webhooks"
20
20
  require_relative "resources/pools"
21
21
  require_relative "resources/connect"
22
+ require_relative "resources/official"
23
+ require_relative "resources/templates"
22
24
  require_relative "resources/partner"
23
25
 
24
26
  module Bzapper
@@ -73,8 +75,14 @@ module Bzapper
73
75
  # @return [Resources::Connect] bZapper Connect do lado do CLIENTE: apps parceiros conectados à conta.
74
76
  attr_reader :connect
75
77
 
78
+ # @return [Resources::Official] Trilho oficial (WhatsApp Cloud API): conta WABA, Embedded Signup, números e perfil comercial.
79
+ attr_reader :official
80
+
81
+ # @return [Resources::Templates] Templates de mensagem aprovados pela Meta (trilho oficial): criar, sincronizar, mídia e fallback.
82
+ attr_reader :templates
83
+
76
84
  # Nomes dos recursos, na ordem da spec.
77
- RESOURCES = %i[accounts contacts usage billing advanced conversations instances groups system messages scheduling campaigns advisories webhooks pools connect].freeze
85
+ RESOURCES = %i[accounts contacts usage billing advanced conversations instances groups system messages scheduling campaigns advisories webhooks pools connect official templates].freeze
78
86
 
79
87
  private
80
88
 
@@ -95,6 +103,8 @@ module Bzapper
95
103
  @webhooks = Resources::Webhooks.new(transport)
96
104
  @pools = Resources::Pools.new(transport)
97
105
  @connect = Resources::Connect.new(transport)
106
+ @official = Resources::Official.new(transport)
107
+ @templates = Resources::Templates.new(transport)
98
108
  end
99
109
  end
100
110
  end
@@ -3,5 +3,5 @@
3
3
  module Bzapper
4
4
  # Versão da gem. O `scripts/release-sdks.sh` do monorepo bumpa a linha abaixo por regex
5
5
  # (ancorada no início da linha) e o `bzapper.gemspec` lê daqui — não mude o formato dela.
6
- VERSION = "0.8.2"
6
+ VERSION = "0.9.0"
7
7
  end
@@ -30,6 +30,10 @@ module Bzapper
30
30
  group.joined group.left group.participant_added group.participant_removed
31
31
  group.participant_promoted group.participant_demoted
32
32
  group.subject_changed group.description_changed
33
+ template.approved template.rejected template.paused template.quality_changed
34
+ template.categorized instance.quality_changed instance.limit_changed
35
+ instance.name_decided account.status_changed account.alert contact.opted_in
36
+ usage.threshold billing.past_due billing.recovered advisory.published
33
37
  connect.completed connect.suspended connect.resumed connect.revoked
34
38
  ].freeze
35
39
 
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: bzapper
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.8.2
4
+ version: 0.9.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Berni Software
@@ -36,10 +36,12 @@ files:
36
36
  - lib/bzapper/resources/groups.rb
37
37
  - lib/bzapper/resources/instances.rb
38
38
  - lib/bzapper/resources/messages.rb
39
+ - lib/bzapper/resources/official.rb
39
40
  - lib/bzapper/resources/partner.rb
40
41
  - lib/bzapper/resources/pools.rb
41
42
  - lib/bzapper/resources/scheduling.rb
42
43
  - lib/bzapper/resources/system.rb
44
+ - lib/bzapper/resources/templates.rb
43
45
  - lib/bzapper/resources/usage.rb
44
46
  - lib/bzapper/resources/webhooks.rb
45
47
  - lib/bzapper/transport.rb