@botozap/sdk 0.14.0 → 0.16.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 +22 -0
- package/README.md +46 -1
- package/dist/index.cjs +20 -0
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +124 -1
- package/dist/index.d.ts +124 -1
- package/dist/index.js +20 -0
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,27 @@
|
|
|
1
1
|
# @botozap/sdk
|
|
2
2
|
|
|
3
|
+
## 0.16.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- d51f908: Adiciona IA de comentários do Instagram (#740): configuração opt-in por Conta de canal, limite diário, prontidão e histórico paginado de decisões/envios.
|
|
8
|
+
|
|
9
|
+
SDK: channelAccounts.getCommentAi, updateCommentAi e listCommentAiRuns, com tipos de configuração, histórico, custo de execução e evento de resposta. CLI: channel-accounts comment-ai get|set|runs, com --enabled, --agent e --daily-limit no set.
|
|
10
|
+
|
|
11
|
+
MCP (catálogo completo): get_instagram_comment_ai, update_instagram_comment_ai e list_instagram_comment_ai_runs, com escopos agents:read/write, sem sandbox e anotações de efeito público. O perfil assistant permanece inalterado; PATCH via OAuth é exclusivo do painel.
|
|
12
|
+
|
|
13
|
+
## 0.15.0
|
|
14
|
+
|
|
15
|
+
### Minor Changes
|
|
16
|
+
|
|
17
|
+
- 45169ad: Webhooks por canal: `channel_account_ids` em create/update (ausente = todos no
|
|
18
|
+
create e sem mudança no update; `null` volta a todos) e, na leitura,
|
|
19
|
+
`channel_account_ids` e `channels_health` (saúde por canal, só dos canais em
|
|
20
|
+
falha). CLI ganha `--channel-account-id` (repetível) e `--all-channels`, e mostra
|
|
21
|
+
canais e saúde por canal em `webhooks get/list`. MCP aceita `channel_account_ids`
|
|
22
|
+
em `create_webhook`/`update_webhook` e devolve os campos novos na saída
|
|
23
|
+
estruturada.
|
|
24
|
+
|
|
3
25
|
## 0.14.0
|
|
4
26
|
|
|
5
27
|
### Minor Changes
|
package/README.md
CHANGED
|
@@ -394,6 +394,25 @@ e `app_messages`, opt-in, com `whatsapp.message.echo`, `.edited` e `.revoked` do
|
|
|
394
394
|
app WhatsApp Business em coexistência. Em `webhookDeliveries.list`, o status
|
|
395
395
|
`limited` marca a entrega cortada pelo limite de repasse do Free (sem retry).
|
|
396
396
|
|
|
397
|
+
`channel_account_ids` limita um Endpoint a alguns canais (ids de
|
|
398
|
+
`channelAccounts.list`, os mesmos de `channel_account.id` nos payloads; 1 a
|
|
399
|
+
100). No create, omitido ou `null` = todos os canais. No update, omitido não
|
|
400
|
+
muda, `null` volta a todos e um array substitui a lista. A leitura devolve
|
|
401
|
+
`channel_account_ids` (`null` = todos; vazio quando os canais marcados foram
|
|
402
|
+
excluídos, e o Endpoint então não recebe eventos) e `channels_health`, só com
|
|
403
|
+
os canais em falha (`channel_account_id: null` = eventos sem canal). A espera,
|
|
404
|
+
as falhas seguidas e a pausa (na 15ª falha) contam por canal: um canal pausado
|
|
405
|
+
não para os outros. `health_status` e `failure_streak` do Endpoint resumem o
|
|
406
|
+
pior canal; `paused` só aparece quando todos os canais com falha estão
|
|
407
|
+
pausados. Erros: `422 invalid_channel_account_ids` e
|
|
408
|
+
`404 channel_account_not_found`.
|
|
409
|
+
|
|
410
|
+
```ts
|
|
411
|
+
await boto.webhooks.update(endpointId, { channel_account_ids: [canalId] });
|
|
412
|
+
await boto.webhooks.update(endpointId, { channel_account_ids: null }); // todos
|
|
413
|
+
const { channels_health } = await boto.webhooks.get(endpointId);
|
|
414
|
+
```
|
|
415
|
+
|
|
397
416
|
## Configuração
|
|
398
417
|
|
|
399
418
|
```ts
|
|
@@ -418,7 +437,7 @@ O SDK cobre os recursos da API `/v1`:
|
|
|
418
437
|
- `broadcasts` — criar, destinatários, agendar, enviar, cancelar
|
|
419
438
|
- `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
|
|
420
439
|
- `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)
|
|
421
|
-
- `webhooks` — CRUD e teste; `customer_id` opcional limita as entregas a um Cliente da Conta (`null` no update remove o filtro)
|
|
440
|
+
- `webhooks` — CRUD e teste; `customer_id` opcional limita as entregas a um Cliente da Conta (`null` no update remove o filtro); `channel_account_ids` limita a alguns canais (`null` = todos) e `channels_health` traz a saúde por canal
|
|
422
441
|
- `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)
|
|
423
442
|
- `phoneNumbers` — listar, buscar, **atualizar o `label`** (nome local, até 100 caracteres; `null` limpa), remover, saúde
|
|
424
443
|
- `media` — subir arquivo (obter um media_id) e **buscar metadados + URL de download** de uma mídia recebida
|
|
@@ -644,3 +663,29 @@ const nonFollowers = await boto.conversations.list({ ig_follows_business: false
|
|
|
644
663
|
As Regras de mensagem retornam `ref_link` (`https://ig.me/m/usuario?ref=...` ou `null`). Regras de comentário aceitam `live`; as métricas incluem `posts[].live`. Servidores sem lives habilitadas devolvem `422 feature_unavailable`. Não combine `live: true` com `media_id` ou `next_post`.
|
|
645
664
|
|
|
646
665
|
Ambos os tipos de regra aceitam `require_follow` e `non_follower_text`. Nas regras de comentário, a condição exige botão e texto para quem não segue (até 640 caracteres); nas de mensagem, esse texto é opcional e limitado a 1.000 bytes. `null` limpa o texto; campos ausentes no PATCH preservam o valor. Contatos expõem somente para leitura `ig_follows_business`, `ig_followed_by_business`, `ig_follower_count`, `ig_verified` e `ig_follow_checked_at`; valores desconhecidos são `null` e ficam fora dos filtros `true` e `false`. Eventos `instagram.message_rule.failed` podem ter `message_id: null` quando vêm de referral sem mensagem.
|
|
666
|
+
|
|
667
|
+
### IA de comentários do Instagram
|
|
668
|
+
|
|
669
|
+
```ts
|
|
670
|
+
const config = await boto.channelAccounts.getCommentAi(channelAccountId);
|
|
671
|
+
await boto.channelAccounts.updateCommentAi(channelAccountId, {
|
|
672
|
+
enabled: true, agent_id: publishedAgentId, daily_limit: 50,
|
|
673
|
+
});
|
|
674
|
+
const runs = await boto.channelAccounts.listCommentAiRuns(channelAccountId, { page: 1, per_page: 30 });
|
|
675
|
+
await boto.channelAccounts.updateCommentAi(channelAccountId, { enabled: false });
|
|
676
|
+
```
|
|
677
|
+
|
|
678
|
+
Leitura e histórico exigem `agents:read`; PATCH exige `agents:write` e capacidade
|
|
679
|
+
`ai` do plano, exceto o patch que somente desliga. Sem sandbox; no OAuth, PATCH
|
|
680
|
+
é exclusivo do painel. Ativar pode publicar respostas e enviar DMs automáticas.
|
|
681
|
+
Campos ausentes preservam a configuração; `agent_id: null` limpa o agente quando
|
|
682
|
+
desligada. `daily_limit` aceita inteiros de 1 a 200; o dia usa `America/Sao_Paulo`.
|
|
683
|
+
`answered_today` conta respostas públicas confirmadas e `reserved_today` inclui
|
|
684
|
+
tentativas incertas. `status`, `gate_mode` e `readiness` descrevem a prontidão.
|
|
685
|
+
|
|
686
|
+
`InstagramCommentAi` e `InstagramCommentAiRun` tipam os retornos. Execuções deste
|
|
687
|
+
recurso incluem `estimated_cost_usd?: number | null` e `finish_reason` com prefixo
|
|
688
|
+
`comment_ai_`; `source` continua `live`. `InstagramCommentAiRepliedEvent` tipa
|
|
689
|
+
`instagram.comment.replied` com `automation.kind = instagram_comment_ai`,
|
|
690
|
+
`execution_id` e `comment_id`. A Private Reply em `instagram.message.sent` traz
|
|
691
|
+
`source: agent`, `ai_execution_id` e `comment_id` no conteúdo da mensagem.
|
package/dist/index.cjs
CHANGED
|
@@ -5793,6 +5793,26 @@ var ChannelAccounts = class {
|
|
|
5793
5793
|
disconnect(id) {
|
|
5794
5794
|
return this.client.requestItem("DELETE", `/channel_accounts/${enc7(id)}/connection`);
|
|
5795
5795
|
}
|
|
5796
|
+
/** Configuração, uso diário e prontidão. agents:read; sem sandbox. */
|
|
5797
|
+
getCommentAi(channelAccountId) {
|
|
5798
|
+
return this.client.requestItem("GET", `/channel_accounts/${enc7(channelAccountId)}/comment-ai`);
|
|
5799
|
+
}
|
|
5800
|
+
/**
|
|
5801
|
+
* PATCH parcial. Ativar pode publicar respostas e enviar DMs automáticas.
|
|
5802
|
+
* agents:write e capacidade ai (desligar somente é livre); sem sandbox.
|
|
5803
|
+
* Chave de API; no OAuth a configuração é exclusiva do painel.
|
|
5804
|
+
*/
|
|
5805
|
+
updateCommentAi(channelAccountId, params) {
|
|
5806
|
+
return this.client.requestItem("PATCH", `/channel_accounts/${enc7(channelAccountId)}/comment-ai`, { body: params });
|
|
5807
|
+
}
|
|
5808
|
+
/** Histórico, mais recente primeiro, com paginação offset. agents:read; sem sandbox. */
|
|
5809
|
+
listCommentAiRuns(channelAccountId, params = {}) {
|
|
5810
|
+
return this.client.requestOffsetList(
|
|
5811
|
+
"GET",
|
|
5812
|
+
`/channel_accounts/${enc7(channelAccountId)}/comment-ai/runs`,
|
|
5813
|
+
{ query: { page: params.page, per_page: params.per_page } }
|
|
5814
|
+
);
|
|
5815
|
+
}
|
|
5796
5816
|
/** QR do ref_link, PNG por padrão; 404 sem link. message-rules:read. */
|
|
5797
5817
|
getMessageRuleQr(id, ruleId, params = {}) {
|
|
5798
5818
|
return this.client.requestBinary("GET", `${messageRulesPath(id, ruleId)}/qr`, { query: { format: params.format } });
|