SDK Blip para TS
npm install @nmultifibra/ts-blipts-blip é um SDK TypeScript para integração com a plataforma BLiP, focado em envio de mensagens (imediatas e agendadas), gestão de contatos e rastreamento de eventos, com suporte especial ao canal WhatsApp Cloud API.
bash
npm install @nmultifibra/ts-blip
`
Configuração
Crie um arquivo .env com as variáveis necessárias:
`
ROUTER_KEY="Key ..."
BLIP_URL="https://.http.msging.net"
ATTENDENCE_BOT_KEY="Key ..."
`
Principais Classes e Métodos
$3
Gerencia contatos, variáveis de contexto e estados de usuário.
`ts
import { BlipContacts } from '@nmultifibra/ts-blip';
const contacts = new BlipContacts(network, process.env.ROUTER_KEY, process.env.BLIP_URL);
await contacts.init();
`
$3
Envia mensagens (imediatas e agendadas), templates, rastreia eventos e integra com o Scheduler.
`ts
import { BlipMessaging } from '@nmultifibra/ts-blip';
const messaging = new BlipMessaging(network, process.env.ROUTER_KEY, contacts, process.env.BLIP_URL);
await messaging.init();
`
$3
`ts
import { DeskCore } from '@nmultifibra/ts-blip';
const blipDesk = new DeskCore(network, process.env.ATTENDENCE_BOT_KEY, process.env.BLIP_URL);
await blipDesk.init();
`
$3
`ts
import { BlipChatHistory } from '@nmultifibra/ts-blip';
const history = new BlipChatHistory(
network,
process.env.ROUTER_KEY,
process.env.BLIP_URL
);
await history.init();
`
Controle de Acesso e Segurança
As classes possuem dois níveis de proteção interna:
| Estado | Descrição |
| --------------- | ------------------------------------- |
| isInstancied | Indica se init() foi executado |
| accessGranted | Indica se a chave de API foi validada |
Sendo possível verificar pela propriedade `accessStatus` presente em todas, ex:
`ts
history.accessStatus
OUTPUT:
{
isInstancied: boolean;
accessGranted: boolean;
}
`
Registro de Uso da SDK
Método interno — executado automaticamente no `init()`
`ts
sendUseRegister(blipApiKey: string)
`
Realiza o registro de uso da classe BlipChatHistory junto à API do BLiP.
Esse registro é obrigatório para liberar o acesso aos recursos de histórico.
$3
- Nome da classe
- Identificador único da instância
- Data/hora (America/Sao_Paulo)
- Resumo do módulo de rede
- Categoria: sdkuse.ts-blip
$3
`ts
Promise<{
status: "success" | "failure";
message: string;
}[]>
`
Envio de Mensagens
$3
`ts
const result = await messaging.sendGrowthMessage(myBroad,{ignore_onboarding: true,retrieve_on_flow: false,force_active: false});
`
$3
- ignore_onboarding : boolean (true or false)
- Decide se os clientes que não estão em onboarding serão ignorados
- retrieve_on_flow: boolean (true or false)
- Decide se o cliente será retirado ou não do flow, se for true deverá ser passado o bot e o bloco para onde ele irá
- force_active: boolean (true or false)
- Decide se deverá forçar o envio de disparo ativo mesmo se o contato tiver sessão ativa
$3
O método sendGrowthMessage tenta agendar a mensagem se o contato possui sessão ativa (<24h). Caso o canal não suporte agendamento (ex: WhatsApp Cloud API), o SDK pode realizar fallback automático para envio imediato.
#### Exemplo de Broadcast
`ts
const broadcast = {
clients: [
{
id: 'uuid',
name: 'Cliente',
number: '551199999999',
extras: {},
component: [
{ type: 'body', parameters: [ { type: 'text', text: 'Lucas' } ] }
]
}
],
template_name: 'nome_template',
stateidentifier: 'id_fluxo'
};
`
Montagem de Template
Use mountMessageTemplate para gerar o objeto broadcast a partir de arrays de clientes e componentes:
`ts
const broadcast = messaging.mountMessageTemplate(clientes, componentes, 'nome_template', 'id_fluxo');
`
Observações Importantes
- Logs: O SDK gera logs detalhados para payloads, autenticação e troubleshooting.
- Templates: Certifique-se de que o template está aprovado no BLiP e que os parâmetros estejam corretos.
Exemplos de Uso Completo
Veja main.sample.ts para um fluxo completo de envio:
`ts
import { BlipContacts, BlipMessaging } from '@nmultifibra/ts-blip';
// ...configuração de network, keys, etc
const contacts = new BlipContacts(network, routerKey, blipUrl);
await contacts.init();
const messaging = new BlipMessaging(network, routerKey, contacts, blipUrl);
await messaging.init();
const result = await messaging.sendGrowthMessage(broadcast, { ignore_onboarding: true });
`
Troubleshooting
- Verifique os logs para detalhes de payloads e autenticação.
- Certifique-se de que as variáveis de ambiente estão corretas.
- Para canais que não suportam agendamento, utilize sempre o envio imediato.
Referências
- Documentação BLiP
- Exemplo de uso no main.sample.ts
---
Contribuições e sugestões são bem-vindas!
Documentação de Filtros — DeskCore (Tickets)
Esta documentação descreve todos os filtros disponíveis, seus formatos, regras lógicas e exemplos práticos utilizados no método:
`ts
get_all_active_tickets(maxlimit: number, input?: GetTicketsInput)
`
- maxlimit: valor máximo de tickets filtrados, se -1 então usa o limite default de 900, o valor mínimo é 100, qualquer valor passado que seja menor é mudado para 100 internamente
Importante o `maxlimit` é só o tamanho máximo do array de Tickets, para limitar mais, melhore o filtro
| Valor | Comportamento |
| ------- | ------------------------ |
| -1 | Busca até ~900 tickets |
| n > 100 | Processa até n tickets |
| n < 100 | Transformado para 100 |
---
`ts
type GetTicketsInput = {
filter?: FilterForTickets
}
type FilterForTickets = {
status?: FilterStatus | boolean | FilterStatus[]
team?:string | boolean | any[]
storageDate?:FilterDate | boolean | FilterDate[]
sequentialId?:number | boolean | number[]
customerIdentity?:string | boolean | string[]
agentIdentity?:string | boolean | string[]
extras?:ExtrasFilter | boolean
}
`
$3
- Lógica entre propriedades: AND entre propriedades diferentes
> Todas as propriedades devem ser satisfeitas
| Valor | Comportamento |
| ------- | ------------------------ |
| true | Ignora o filtro |
| false | Elimina todos os tickets |
Quando um filtro recebe um array, o comportamento padrão é OR:
`ts
status: [FilterStatus.Open, FilterStatus.Waiting]
`
Retorna tickets com qualquer um dos valores
Filtros diretos usam comparação exata (===) :
`ts
{
status: FilterStatus.Waiting, // [FilterStatus.Open,FilterStatus.Close]
team:"Comercial",
storageDate: {
value: new Date("2026-01-05T00:00:00.000Z"),
compare: LogicalComparission.GTE
}
`
$3
`ts
export enum FilterStatus {
Open = "Open",
Closed = "Closed",
Waiting ="Waiting",
ClosedAttendant = "ClosedAttendant",
ClosedClient = "ClosedClient",
ClosedClientInactivity = "ClosedClientInactivity",
Assigned = "Assigned",
Transferred="Transferred"
}
`
$3
A propriedade storageDate suporta comparações lógicas avançadas.
`ts
type FilterDate = {
value: Date
compare: LogicalComparission
}
`
`ts
enum LogicalComparission {
GTE = "GTE", // >=
LTE = "LTE", // <=
EQ = "EQ" // ===
MAX = "MAX", // Maior valor
MIN = "MIN" // Menor valor
}
`
Comparação de Data Simples:
`ts
storageDate: {
value: new Date("2026-01-05T00:00:00.000Z"),
compare: LogicalComparission.GTE
}
`
Intervalo de Datas (FilterDate[]) :
`ts
storageDate: [
{
value: new Date("2026-01-01T00:00:00.000Z"),
compare: LogicalComparission.GTE
},
{
value: new Date("2026-01-07T00:00:00.000Z"),
compare: LogicalComparission.LTE
}
]
`
$3
Utilizando esse formato também é possível filtrar dentro do extras do contato com:
`ts
extras: {
Key: "Value"
}
`
$3
`ts
const input: GetTicketsInput = {
filter: {
status: FilterStatus.Waiting, // [FilterStatus.Open,FilterStatus.Close]
team:"Comercial",
/* storageDate: {
value: new Date("2026-01-05T00:00:00.000Z"),
compare: LogicalComparission.GTE
} */
//sequentialId:[744]
[
{
value: new Date("2026-01-01T00:00:00.000Z"),
compare: LogicalComparission.GTE
},
{
value: new Date("2026-01-07T00:00:00.000Z"),
compare: LogicalComparission.LTE
}
]
extras: {
ID: "60743"
}
}
}
`
$3
| Tipo de Array | Lógica |
| ------------------------- | ------- |
| status[], team[], etc | OR |
| storageDate[] | AND |
Fechamento de tickets
`ts
close_tickets(
maxlimit: number,
input: GetTicketsInput,
as: ByConfigure
)
`
Exemplo:
`ts
await blipDesk.close_tickets(
100,
input,
{
type: AsType.User,
tags: ["Encerrado via SDK"]
}
);
`
$3
`ts
export type ByConfigure = {
agentIdentity?: string
closeStatus?: string
type: AsType
tags: string[]
}
`
Essa estrutura define o contexto do fechamento, ou seja:
> Quem está fechando, como o ticket será fechado e quais tags serão aplicadas.
$3
- Status padrão de fechamento: ClosedAttendant
Pode ser sobrescrito com as.closeStatus
> Se type === AsType.Agent, é obrigatório informar agentIdentity
- type: AsType (obrigatório)
> Define quem executa o fechamento.
`ts
export enum AsType {
Agent = "Agent",
User = "User"
}
`
- `AsType.User`
> Simula o fechamento como usuário final
> Não associa um agente
> O campo agentIdentity é ignorado
Uso típico:
`ts
{
type: AsType.User,
tags: ["Encerrado automaticamente"]
}
`
- `AsType.Agent`
> Fecha o ticket em nome de um agente
> Obrigatório informar agentIdentity
> O BLiP registra o encerramento como ação humana
`ts
{
type: AsType.Agent,
agentIdentity: "joao.silva@empresa.com",
tags: ["Resolvido pelo agente"]
}
`
- `closeStatus?: string` (opcional)
> Define qual status final será aplicado ao ticket.
- Status padrão: ClosedAttendant
Exemplos de uso:
`ts
{
closeStatus: "ClosedClient",
}
{
closeStatus: "ClosedClientInactivity"
}
`
Importante
O SDK não valida se o status é válido, se um status inválido for informado a API do BLiP pode rejeitar ou aceitar silenciosamente
- `tags: string[] (obrigatório)`
> Tags aplicadas ao ticket no momento do fechamento.
> São acumulativas
`ts
tags: ["FechadoViaSDK", "Reprocessado"]
`
Transferência de tickets
O método transfer_ticket permite transferir tickets ativos em massa para um time específico do BLiP Desk, aplicando filtros avançados, validações de segurança e controle de agentes online.
`ts
transfer_ticket(
maxlimit: number,
input: GetTicketsInput,
target_team: string,
securityTransfer?: SecurityTransfer
): Promise<{ id: string; res: number }[]>
`
$3
- `maxlimit: number`
> Define o número máximo de tickets a serem processados.
| Valor | Comportamento |
| ------- | ------------------------ |
| -1 | Busca até ~900 tickets |
| n > 100 | Processa até n tickets |
| n < 100 | Transformado para 100 |
---
- `target_team: string`
> Nome exato do time de destino no BLiP Desk.
O método valida:
- Se o time existe
- Se o nome é exatamente igual ao cadastrado
---
- `igone_online?: boolean` (opcional)
Controla se a transferência pode ocorrer mesmo sem agentes online no time de destino.
| Valor | Comportamento |
| ---------------- | ---------------------------------------------- |
| false (padrão) | Bloqueia transferência se agentsOnline === 0 |
| true | Força a transferência |
---
- `securityTransfer` (opcional)
Configurações de segurança:
- `igone_online`: Se true, transfere mesmo que não haja atendentes online.
- `maxTicketsPerTeam`: Limite máximo de tickets que a equipe de destino pode ter (abertos + fila) antes de bloquear novas transferências.
> Segurança: Valida existência da equipe, status online de agentes e volumetria máxima permitida.
Exemplo de utilização:
`ts
const input: GetTicketsInput = {
filter: {
status: FilterStatus.Waiting, /
team:"Default"
}
}
const security_transfer: SecurityTransfer = {
maxTicketsPerTeam:2,
igone_online:true //default: false
}
const transfer = await result.transfer_ticket(100,input,"Financeiro",security_transfer)
`
---
Obtenção de metricas de times
Obtém métricas de monitoramento em tempo real das equipes, permitindo filtrar por produtividade ou volume.
`ts
const teamMetricsInput: TeamMetricsFilter = {
//waitingTickets: { value: 1, compare: LogicalComparission.GTE },
//openedTickets: { value: 0, compare: LogicalComparission.EQ }
team: "Financeiro",
/* averageResponseTime: {
value: "00:01:00",
compare: LogicalComparission.LTE
} */
/* averageAttendanceTime: [
{ value: "00:00:30", compare: LogicalComparission.LTE },
{ value: "00:02:00", compare: LogicalComparission.GTE }
] */
}
const teamsMetrics = await result.get_teams_metrics(teamMetricsInput)
`
Filtros disponíveis:
`ts
export type TeamMetrics = {
name: string,
waitingTickets: number,
openedTickets: number,
closedTickets: number,
averageAttendanceTime: string,
averageResponseTime: string,
ticketsCount: number
}
`
Obtenção de todos os times
Retorna a lista completa de todas as equipes configuradas no bot de atendimento.
`ts
const teams = await result.get_all_teams()
`
---
Métricas de Agentes
Obtém métricas em tempo real dos atendentes (agents), com suporte a filtros avançados.
`ts
get_agents_metrics(filter?: AgentsMetricsFilter): Promise
`
$3
`ts
const agentsMetrics = await blipDesk.get_agents_metrics({
team: "Financeiro",
online: true
});
`
$3
`ts
{
total: number;
items: AgentMetrics[];
}
`
---
Métricas de Times
Obtém métricas de monitoramento em tempo real das equipes.
`ts
get_teams_metrics(filter?: TeamMetricsFilter): Promise
`
$3
`ts
const teamMetricsInput: TeamMetricsFilter = {
team: "Financeiro",
waitingTickets: { value: 1, compare: LogicalComparission.GTE }
};
const teamsMetrics = await blipDesk.get_teams_metrics(teamMetricsInput);
`
$3
`ts
{
total: number;
items: TeamMetrics[];
}
`
---
Regras de Atendimento
$3
`ts
get_attendance_rules(filter?: AttendanceRulesFilter): Promise
`
`ts
const rules = await blipDesk.get_attendance_rules({ team: "Financeiro" });
`
---
$3
`ts
create_attendance_rule(data: AttendanceRulesPayload): Promise
`
`ts
await blipDesk.create_attendance_rule({
team: "Financeiro",
priority: 1
});
`
---
Horário de Atendimento do Bot
Obtém as janelas de atendimento configuradas no bot.
`ts
get_attendence_hours(botSlug: string): Promise<{ total: number; items: any[] }>
`
`ts
const hours = await blipDesk.get_attendence_hours("meu-bot-slug");
`
---
Agentes Online
Retorna todos os agentes online no momento.
`ts
get_online_agents(): Promise<{ total: number; items: any[] }>
`
`ts
const onlineAgents = await blipDesk.get_online_agents();
`
---
Gestão de Agentes
$3
Cria um novo atendente no BLiP Desk, validando previamente se os times informados existem.
`ts
add_new_agent(agent: AgentPayload): Promise
`
$3
* Todos os times informados em agent.teams devem existir no bot
* Caso contrário, o método lança erro
`ts
const newAgent: AgentPayload = {
identity: "joao.silva@empresa.com",
teams: ["Financeiro", "Suporte"],
isOnline: true
};
await blipDesk.add_new_agent(newAgent);
`
---
Tickets
$3
`ts
create_new_ticket(customerIdentity: string): Promise
`
`ts
await blipDesk.create_new_ticket("551199999999@wa.gw.msging.net");
`
---
$3
Adiciona tags em massa nos tickets ativos com opções de segurança.
`ts
add_tags_on_tikcets(
maxlimit: number,
tags: string[],
input: GetTicketsInput,
secureConfigs?: Secure_add_tags
): Promise
`
$3
* overwrite: sobrescreve tags existentes
* enableAutoComplete: reutiliza tags atuais automaticamente
`ts
await blipDesk.add_tags_on_tikcets(
100,
["Urgente", "VIP"],
input,
{ enableAutoComplete: true }
);
`
---
Histórico de Conversas e Mensagens — BlipChatHistory
A classe BlipChatHistory fornece acesso ao histórico de conversas, mensagens, logs globais e eventos (notifications) do BLiP, permitindo auditoria completa do ciclo de vida das mensagens.
$3
`ts
get_last_threads(): Promise
`
Retorna as conversas mais recentes (threads) do bot.
Retorno
`ts
{
total: number;
items: ConversationItem[];
}
`
$3
`ts
get_last_messages(contactId: string): Promise
`
Retorna todas as mensagens associadas a uma thread específica.
Parâmetros
- `contactId: string`: Identificador do contato
Retorno
`ts
{
total: number;
items: any[];
}
`
$3
`ts
get_logged_messages(): Promise
`
Retorna o log global de mensagens processadas pelo bot.
Retorno
`ts
{
total: number;
items: any[];
}
`
$3
`ts
get_logged_notifications(messageId?: string): Promise
`
Retorna eventos do ciclo de vida das mensagens, como:
- accepted
- dispatched
- received
- failed
Retorno
`ts
{
total: number;
items: any[];
}
`
Parâmetros
- `messageId?: string` (opcional): Id da mensagem a ser filtrada, no formato: `fwd:fwd:cb789e9b-63dc-4562-b65d-881237335c14`
Retorno
`ts
{
total: number;
items: MessageEvent[];
}
``