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.
@@ -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