@botozap/sdk 0.11.0 → 0.13.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.
- package/CHANGELOG.md +15 -0
- package/README.md +68 -2
- package/dist/index.cjs +71 -4
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +248 -14
- package/dist/index.d.ts +248 -14
- package/dist/index.js +71 -4
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,20 @@
|
|
|
1
1
|
# @botozap/sdk
|
|
2
2
|
|
|
3
|
+
## 0.13.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- 8d27c17: Busca de conhecimento híbrida: `AiKnowledgeHit` ganha `score` (fusão vetorial +
|
|
8
|
+
textual), `vector_rank` e `text_rank`; `similarity` passa a ser `number | null`
|
|
9
|
+
(nula quando o trecho veio só da busca por palavras).
|
|
10
|
+
|
|
11
|
+
## 0.12.0
|
|
12
|
+
|
|
13
|
+
### Minor Changes
|
|
14
|
+
|
|
15
|
+
- ab0ddbc: Add Instagram interactive button/card/gallery sends with human_agent and channel receipts, extended comment-rule fields and deletion, and messenger-profile read/update/delete/sync across SDK, CLI and MCP. Preserve WhatsApp interactive formats and partial PATCH semantics, and expose messenger-profile scopes and structured results.
|
|
16
|
+
- df51d96: Add Instagram comment-rule button and delivery fields, message-rule CRUD with trigger/action types and message-rules scopes, and comment-rule metrics by period across SDK, CLI and MCP. Preserve nullable fields and partial PATCH bodies, advertise typed MCP results, and support JSON input for comment and message rules in the CLI.
|
|
17
|
+
|
|
3
18
|
## 0.11.0
|
|
4
19
|
|
|
5
20
|
### Minor Changes
|
package/README.md
CHANGED
|
@@ -163,6 +163,36 @@ no WhatsApp a API recusa com `channel_not_supported`; acima de 13 opções,
|
|
|
163
163
|
`quick_reply_title_too_long`; fora da janela, `quick_replies_window_closed`.
|
|
164
164
|
No Instagram não existe `caption` em mídia (`unsupported_caption`).
|
|
165
165
|
|
|
166
|
+
### Botões e cards no Instagram
|
|
167
|
+
|
|
168
|
+
```ts
|
|
169
|
+
await boto.messages.sendInteractive({
|
|
170
|
+
to: "17841400000000123", from: contaInstagramId,
|
|
171
|
+
interactive: { type: "button", body: { text: "Como posso ajudar?" }, action: { buttons: [
|
|
172
|
+
{ type: "web_url", title: "Ver loja", url: "https://exemplo.com" },
|
|
173
|
+
{ type: "postback", title: "Horários", payload: "horarios" },
|
|
174
|
+
] } },
|
|
175
|
+
}, { idempotencyKey: chaveDaIntencao });
|
|
176
|
+
await boto.messages.sendInteractive({
|
|
177
|
+
to: "17841400000000123", from: contaInstagramId,
|
|
178
|
+
interactive: { type: "generic", elements: [{
|
|
179
|
+
title: "Produto", subtitle: "Disponível na loja",
|
|
180
|
+
image_url: "https://exemplo.com/foto.jpg",
|
|
181
|
+
default_action: { type: "web_url", url: "https://exemplo.com/produto" },
|
|
182
|
+
buttons: [{ type: "postback", title: "Quero saber mais", payload: "produto" }],
|
|
183
|
+
}] },
|
|
184
|
+
});
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
`button` aceita 1–3 botões e texto até 640 caracteres; `generic` aceita 1–10
|
|
188
|
+
cards com título (até 80 caracteres) e ao menos uma propriedade adicional.
|
|
189
|
+
Subtítulo: até 80 caracteres; até 3 botões por card. Botões usam título de até
|
|
190
|
+
20 caracteres e postback de até 1000 caracteres; links são HTTPS. A API valida
|
|
191
|
+
os limites (`422`). `tag: "human_agent"` é opcional e depende da flag e da
|
|
192
|
+
janela autorizada pela API. O recibo traz `wamid: null`, `external_id`,
|
|
193
|
+
`channel: "instagram"` e `type: "interactive"`. Os formatos WhatsApp
|
|
194
|
+
`button` com `reply`, `list` e `cta_url` continuam disponíveis.
|
|
195
|
+
|
|
166
196
|
## Contas de canal e Regras de comentário
|
|
167
197
|
|
|
168
198
|
```ts
|
|
@@ -188,7 +218,12 @@ await boto.channelAccounts.updateCommentRule(conta.id, regra.id, { is_active: fa
|
|
|
188
218
|
`keyword` vazia vale para qualquer comentário e `media_id` vazio para todos os
|
|
189
219
|
posts. Criar ou ativar exige plano com Regras de comentário (`422
|
|
190
220
|
plan_restricted`); a mesma palavra-chave no mesmo alvo é `409 duplicate_rule`.
|
|
191
|
-
|
|
221
|
+
`deleteCommentRule(conta.id, regra.id)` exclui e retorna `{ id, deleted: true }`.
|
|
222
|
+
`keywords` (até 20 expressões), `excluded_keywords` (até 20 exclusões),
|
|
223
|
+
`reply_variations` (até 10 respostas públicas) e `next_post` estão disponíveis
|
|
224
|
+
na criação, leitura e atualização. `keywords` prevalece sobre `keyword`, e
|
|
225
|
+
`reply_variations` sobre `reply_text`; `[]` limpa a lista. `next_post: true`
|
|
226
|
+
aguarda o próximo post e não deve ser combinado com `media_id` explícito.
|
|
192
227
|
|
|
193
228
|
Com `token_status` `expired`, `invalid` ou `revoked`, os envios pela conta
|
|
194
229
|
falham até reconectá-la em Canais. Mensagens do Instagram editadas pelo contato
|
|
@@ -196,6 +231,30 @@ trazem o conteúdo atualizado com `content.edited` (`{ count, at }`); as apagada
|
|
|
196
231
|
`revoked_at`. Os Eventos `instagram.message.edited` e `instagram.message.revoked`
|
|
197
232
|
chegam pelo webhook e por `events.list`.
|
|
198
233
|
|
|
234
|
+
### Perguntas e menu do Instagram
|
|
235
|
+
|
|
236
|
+
```ts
|
|
237
|
+
const perfil = await boto.channelAccounts.getMessengerProfile(conta.id);
|
|
238
|
+
await boto.channelAccounts.updateMessengerProfile(conta.id, {
|
|
239
|
+
ice_breakers: [{ question: "Quais os horários?", payload: "horarios" }],
|
|
240
|
+
persistent_menu: [{ type: "web_url", title: "Ver loja", url: "https://exemplo.com" }],
|
|
241
|
+
});
|
|
242
|
+
await boto.channelAccounts.updateMessengerProfile(conta.id, { ice_breakers: null });
|
|
243
|
+
await boto.channelAccounts.syncMessengerProfile(conta.id);
|
|
244
|
+
await boto.channelAccounts.deleteMessengerProfile(conta.id);
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
GET usa `messenger-profile:read`; PATCH, DELETE e sync usam
|
|
248
|
+
`messenger-profile:write`. Sem sandbox. PATCH preserva seções ausentes;
|
|
249
|
+
`null` ou `[]` remove a seção. Até 4 perguntas e 5 itens de menu (`postback`
|
|
250
|
+
ou `web_url`). Perguntas: 80 caracteres; títulos: 20; payloads: 1000; URLs
|
|
251
|
+
http/https: 2000. Os quatro métodos retornam o snapshot com
|
|
252
|
+
`channel_account_id`, `config`, `revision`, `sync_status`, `synced_at`,
|
|
253
|
+
`last_error_code` e `updated_at`. GET lê o espelho salvo; sync verifica/reaplica
|
|
254
|
+
explicitamente o desejado. Falhas de aplicação conservam a configuração para
|
|
255
|
+
retry; `profile_busy` e `profile_sync_unconfirmed` pedem reconciliar após um
|
|
256
|
+
minuto. Sync sem configuração salva retorna `profile_not_configured`.
|
|
257
|
+
|
|
199
258
|
## Clientes e templates
|
|
200
259
|
|
|
201
260
|
```ts
|
|
@@ -360,7 +419,7 @@ O SDK cobre os recursos da API `/v1`:
|
|
|
360
419
|
- `contacts` — listar, buscar, criar, atualizar, remover; `display_name` é o nome que a empresa dá ao Contato (1–200 caracteres; `null` limpa), separado do `profile_name` que vem do canal
|
|
361
420
|
- `conversations` — listar (filtros `channel` e `channel_account_id`), buscar, atualizar, responder, atribuições; leituras trazem `entry_point` (`ctwa`/`organic`/`null`), `referral` do último clique em anúncio Click-to-WhatsApp, `fep_expires_at` (fim da janela grátis informado pela Meta) e `fep_reply_by` (estimativa do prazo para responder)
|
|
362
421
|
- `webhooks` — CRUD e teste; `customer_id` opcional limita as entregas a um Cliente da Conta (`null` no update remove o filtro)
|
|
363
|
-
- `channelAccounts` — listar e buscar Contas de canal (WhatsApp e Instagram); **Regras de comentário** do Instagram (listar, buscar, criar, atualizar)
|
|
422
|
+
- `channelAccounts` — listar e buscar Contas de canal (WhatsApp e Instagram); **Regras de comentário** do Instagram (listar, buscar, criar, atualizar, excluir) e **Perguntas e menu** (ler, salvar/aplicar, remover, verificar/reaplicar)
|
|
364
423
|
- `phoneNumbers` — listar, buscar, **atualizar o `label`** (nome local, até 100 caracteres; `null` limpa), remover, saúde
|
|
365
424
|
- `media` — subir arquivo (obter um media_id) e **buscar metadados + URL de download** de uma mídia recebida
|
|
366
425
|
- `events` — reler inbound e mudanças de status pelo cursor durável da Conta/ambiente
|
|
@@ -561,3 +620,10 @@ nova intenção. `unknown` ou `accepted` exigem conciliação antes de considera
|
|
|
561
620
|
outro envio. SDK e MCP preservam `outcome` e `retry` da API. Resultados concluídos
|
|
562
621
|
vencidos são removidos pelo cron a cada minuto; claims incertas não são removidas
|
|
563
622
|
por tempo, conforme o runbook `botozap/docs/ops/message-send-receipts.md`.
|
|
623
|
+
|
|
624
|
+
## Instagram — onda 2
|
|
625
|
+
|
|
626
|
+
Regras de comentário incluem `dm_button_title`, `delivery_text` e `delivery_media`.
|
|
627
|
+
Regras de mensagem têm CRUD com gatilhos e ações tipados (`message-rules:read/write`);
|
|
628
|
+
métricas de comentário recebem `from`/`to` (`comment-rules:read`).
|
|
629
|
+
[Contrato e exemplos de SDK, CLI e MCP](../../docs/instagram-wave-two.md).
|
package/dist/index.cjs
CHANGED
|
@@ -5209,13 +5209,19 @@ var Messages = class {
|
|
|
5209
5209
|
return assertSendResult(result);
|
|
5210
5210
|
}
|
|
5211
5211
|
/**
|
|
5212
|
-
* Envia
|
|
5213
|
-
*
|
|
5212
|
+
* Envia button/list/cta_url no WhatsApp ou button/generic no Instagram.
|
|
5213
|
+
* Mensagem livre sujeita à janela do canal.
|
|
5214
5214
|
*/
|
|
5215
5215
|
async sendInteractive(params, options = {}) {
|
|
5216
5216
|
return postMessage(
|
|
5217
5217
|
this.client,
|
|
5218
|
-
{
|
|
5218
|
+
{
|
|
5219
|
+
to: params.to,
|
|
5220
|
+
from: params.from,
|
|
5221
|
+
type: "interactive",
|
|
5222
|
+
interactive: params.interactive,
|
|
5223
|
+
...params.tag !== void 0 ? { tag: params.tag } : {}
|
|
5224
|
+
},
|
|
5219
5225
|
options
|
|
5220
5226
|
);
|
|
5221
5227
|
}
|
|
@@ -5802,7 +5808,7 @@ var ChannelAccounts = class {
|
|
|
5802
5808
|
}
|
|
5803
5809
|
/**
|
|
5804
5810
|
* Altera uma Regra de comentário (só os campos enviados). comment-rules:write.
|
|
5805
|
-
* `is_active: false` desliga a regra
|
|
5811
|
+
* `is_active: false` desliga a regra.
|
|
5806
5812
|
*/
|
|
5807
5813
|
updateCommentRule(channelAccountId, ruleId, params) {
|
|
5808
5814
|
return this.client.requestItem(
|
|
@@ -5811,10 +5817,71 @@ var ChannelAccounts = class {
|
|
|
5811
5817
|
{ body: params }
|
|
5812
5818
|
);
|
|
5813
5819
|
}
|
|
5820
|
+
/** Exclui uma Regra de comentário. comment-rules:write. */
|
|
5821
|
+
deleteCommentRule(channelAccountId, ruleId) {
|
|
5822
|
+
return this.client.requestItem(
|
|
5823
|
+
"DELETE",
|
|
5824
|
+
`/channel_accounts/${enc7(channelAccountId)}/comment-rules/${enc7(ruleId)}`
|
|
5825
|
+
);
|
|
5826
|
+
}
|
|
5827
|
+
/** Resultados da Regra por período e post. comment-rules:read. */
|
|
5828
|
+
getCommentRuleMetrics(channelAccountId, ruleId, params) {
|
|
5829
|
+
return this.client.requestItem(
|
|
5830
|
+
"GET",
|
|
5831
|
+
`/channel_accounts/${enc7(channelAccountId)}/comment-rules/${enc7(ruleId)}/metrics`,
|
|
5832
|
+
{ query: { from: params.from, to: params.to } }
|
|
5833
|
+
);
|
|
5834
|
+
}
|
|
5835
|
+
/** Lista Regras de mensagem com paginação offset. message-rules:read. */
|
|
5836
|
+
listMessageRules(channelAccountId, params = {}) {
|
|
5837
|
+
return this.client.requestOffsetList(
|
|
5838
|
+
"GET",
|
|
5839
|
+
messageRulesPath(channelAccountId),
|
|
5840
|
+
{ query: { page: params.page, per_page: params.per_page } }
|
|
5841
|
+
);
|
|
5842
|
+
}
|
|
5843
|
+
/** Busca uma Regra de mensagem. message-rules:read. */
|
|
5844
|
+
getMessageRule(channelAccountId, ruleId) {
|
|
5845
|
+
return this.client.requestItem("GET", messageRulesPath(channelAccountId, ruleId));
|
|
5846
|
+
}
|
|
5847
|
+
/** Cria uma Regra de mensagem. message-rules:write. */
|
|
5848
|
+
createMessageRule(channelAccountId, params) {
|
|
5849
|
+
return this.client.requestItem("POST", messageRulesPath(channelAccountId), { body: params });
|
|
5850
|
+
}
|
|
5851
|
+
/** PATCH parcial; a API valida o estado final. message-rules:write. */
|
|
5852
|
+
updateMessageRule(channelAccountId, ruleId, params) {
|
|
5853
|
+
return this.client.requestItem("PATCH", messageRulesPath(channelAccountId, ruleId), { body: params });
|
|
5854
|
+
}
|
|
5855
|
+
/** Exclui a Regra preservando Disparos e Eventos. message-rules:write. */
|
|
5856
|
+
deleteMessageRule(channelAccountId, ruleId) {
|
|
5857
|
+
return this.client.requestItem("DELETE", messageRulesPath(channelAccountId, ruleId));
|
|
5858
|
+
}
|
|
5859
|
+
/** Lê o espelho salvo (sem consultar a Meta). messenger-profile:read; sem sandbox. */
|
|
5860
|
+
getMessengerProfile(channelAccountId) {
|
|
5861
|
+
return this.client.requestItem("GET", profilePath(channelAccountId));
|
|
5862
|
+
}
|
|
5863
|
+
/** Salva/aplica apenas as seções enviadas. messenger-profile:write; sem sandbox. */
|
|
5864
|
+
updateMessengerProfile(channelAccountId, params) {
|
|
5865
|
+
return this.client.requestItem("PATCH", profilePath(channelAccountId), { body: params });
|
|
5866
|
+
}
|
|
5867
|
+
/** Remove perguntas e menu, conservando configuração vazia. messenger-profile:write. */
|
|
5868
|
+
deleteMessengerProfile(channelAccountId) {
|
|
5869
|
+
return this.client.requestItem("DELETE", profilePath(channelAccountId));
|
|
5870
|
+
}
|
|
5871
|
+
/** Verifica/reaplica explicitamente o desejado salvo. messenger-profile:write. */
|
|
5872
|
+
syncMessengerProfile(channelAccountId) {
|
|
5873
|
+
return this.client.requestItem("POST", `${profilePath(channelAccountId)}/sync`);
|
|
5874
|
+
}
|
|
5814
5875
|
};
|
|
5876
|
+
function profilePath(id) {
|
|
5877
|
+
return `/channel_accounts/${enc7(id)}/messenger-profile`;
|
|
5878
|
+
}
|
|
5815
5879
|
function enc7(id) {
|
|
5816
5880
|
return encodeURIComponent(id);
|
|
5817
5881
|
}
|
|
5882
|
+
function messageRulesPath(id, ruleId) {
|
|
5883
|
+
return `/channel_accounts/${enc7(id)}/message-rules${ruleId === void 0 ? "" : `/${enc7(ruleId)}`}`;
|
|
5884
|
+
}
|
|
5818
5885
|
|
|
5819
5886
|
// src/resources/media.ts
|
|
5820
5887
|
var Media = class {
|