ts-blip SDK

O ts-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.

Instalação

npm install @nmultifibra/ts-blip

Configuração

Crie um arquivo .env com as variáveis necessárias:

ROUTER_KEY="Key ..."
BLIP_URL="https://<seu-endpoint>.http.msging.net"
ATTENDENCE_BOT_KEY="Key ..."

Principais Classes e Métodos

BlipContacts

Gerencia contatos, variáveis de contexto e estados de usuário.

import { BlipContacts } from '@nmultifibra/ts-blip';
const contacts = new BlipContacts(network, process.env.ROUTER_KEY, process.env.BLIP_URL);
await contacts.init();

BlipMessaging

Envia mensagens (imediatas e agendadas), templates, rastreia eventos e integra com o Scheduler.

import { BlipMessaging } from '@nmultifibra/ts-blip';
const messaging = new BlipMessaging(network, process.env.ROUTER_KEY, contacts, process.env.BLIP_URL);
await messaging.init();

DeskCore

import { DeskCore } from '@nmultifibra/ts-blip';
const blipDesk = new DeskCore(network, process.env.ATTENDENCE_BOT_KEY, process.env.BLIP_URL);
await blipDesk.init();

Chat History

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:

history.accessStatus

OUTPUT:

{
  isInstancied: boolean;
  accessGranted: boolean;
}

Registro de Uso da SDK

Método interno — executado automaticamente no init()

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.

O que é enviado no tracking

• Nome da classe

• Identificador único da instância

• Data/hora (America/Sao_Paulo)

• Resumo do módulo de rede

• Categoria: sdkuse.ts-blip

Retorno interno

Promise<{
  status: "success" | "failure";
  message: string;
}[]>

Envio de Mensagens

Mensagem Imediata (WhatsApp Cloud API)

const result = await messaging.sendGrowthMessage(myBroad,{ignore_onboarding: true,retrieve_on_flow: false,force_active: false});

Parâmetros de condicionamento

• 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

Mensagem Agendada (Scheduler)

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

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:

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:

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:

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 |

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
}

Regras Globais de Funcionamento

• 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:

status: [FilterStatus.Open, FilterStatus.Waiting]

Retorna tickets com qualquer um dos valores

Filtros diretos usam comparação exata (===) :

{
  status: FilterStatus.Waiting, // [FilterStatus.Open,FilterStatus.Close]
  team:"Comercial",
  storageDate: {
    value: new Date("2026-01-05T00:00:00.000Z"),
    compare: LogicalComparission.GTE
}

Todos os status mapeados

export enum FilterStatus  {
  Open = "Open",
  Closed = "Closed",
  Waiting ="Waiting",
  ClosedAttendant = "ClosedAttendant",
  ClosedClient = "ClosedClient",
  ClosedClientInactivity =  "ClosedClientInactivity",
  Assigned = "Assigned",
  Transferred="Transferred"
}

Filtro de Data

A propriedade storageDate suporta comparações lógicas avançadas.

type FilterDate = {
    value: Date
    compare: LogicalComparission
}

enum LogicalComparission {
    GTE = "GTE", // >=
    LTE = "LTE", // <=
    EQ  = "EQ"   // ===
    MAX = "MAX", // Maior valor
    MIN = "MIN" // Menor valor
}

Comparação de Data Simples:

storageDate: {
    value: new Date("2026-01-05T00:00:00.000Z"),
    compare: LogicalComparission.GTE
}

Intervalo de Datas (FilterDate[]) :

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
    }
]

Filtro de extras

Utilizando esse formato também é possível filtrar dentro do extras do contato com:

extras: {
   Key: "Value"
}

Exemplo estruturado:

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"
                }
            }
        }

Importante — Diferença de Comportamento

| Tipo de Array | Lógica | | ------------------------- | ------- | | status[], team[], etc | OR | | storageDate[] | AND |

Fechamento de tickets

close_tickets(
  maxlimit: number,
  input: GetTicketsInput,
  as: ByConfigure
)

Exemplo:

await blipDesk.close_tickets(
  100,
  input,
  {
    type: AsType.User,
    tags: ["Encerrado via SDK"]
  }
);

Estrutura ByConfigure

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.

Regras importantes

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

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:

{
  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

{
  type: AsType.Agent,
  agentIdentity: "[email protected]",
  tags: ["Resolvido pelo agente"]
}

• closeStatus?: string (opcional)

Define qual status final será aplicado ao ticket.

• Status padrão: ClosedAttendant

Exemplos de uso:

{
  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

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.

transfer_ticket(
  maxlimit: number,
  input: GetTicketsInput,
  target_team: string,
  securityTransfer?: SecurityTransfer
): Promise<{ id: string; res: number }[]>

Parâmetros

• 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:

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.

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:

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.

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.

get_agents_metrics(filter?: AgentsMetricsFilter): Promise<AgentsMetricsResponse>

Exemplo de uso

const agentsMetrics = await blipDesk.get_agents_metrics({
  team: "Financeiro",
  online: true
});

Retorno

{
  total: number;
  items: AgentMetrics[];
}

Métricas de Times

Obtém métricas de monitoramento em tempo real das equipes.

get_teams_metrics(filter?: TeamMetricsFilter): Promise<TeamsMetricsResponse>

Exemplo

const teamMetricsInput: TeamMetricsFilter = {
  team: "Financeiro",
  waitingTickets: { value: 1, compare: LogicalComparission.GTE }
};

const teamsMetrics = await blipDesk.get_teams_metrics(teamMetricsInput);

Retorno

{
  total: number;
  items: TeamMetrics[];
}

Regras de Atendimento

Listar regras de atendimento

get_attendance_rules(filter?: AttendanceRulesFilter): Promise<AttendanceRuleResponse>

const rules = await blipDesk.get_attendance_rules({ team: "Financeiro" });

Criar nova regra de atendimento

create_attendance_rule(data: AttendanceRulesPayload): Promise<boolean>

await blipDesk.create_attendance_rule({
  team: "Financeiro",
  priority: 1
});

Horário de Atendimento do Bot

Obtém as janelas de atendimento configuradas no bot.

get_attendence_hours(botSlug: string): Promise<{ total: number; items: any[] }>

const hours = await blipDesk.get_attendence_hours("meu-bot-slug");

Agentes Online

Retorna todos os agentes online no momento.

get_online_agents(): Promise<{ total: number; items: any[] }>

const onlineAgents = await blipDesk.get_online_agents();

Gestão de Agentes

Criar novo agente

Cria um novo atendente no BLiP Desk, validando previamente se os times informados existem.

add_new_agent(agent: AgentPayload): Promise<boolean>

Validação importante

• Todos os times informados em agent.teams devem existir no bot
• Caso contrário, o método lança erro

const newAgent: AgentPayload = {
  identity: "[email protected]",
  teams: ["Financeiro", "Suporte"],
  isOnline: true
};

await blipDesk.add_new_agent(newAgent);

Tickets

Criar novo ticket

create_new_ticket(customerIdentity: string): Promise<boolean>

await blipDesk.create_new_ticket("[email protected]");

Adicionar tags em tickets ativos

Adiciona tags em massa nos tickets ativos com opções de segurança.

add_tags_on_tikcets(
  maxlimit: number,
  tags: string[],
  input: GetTicketsInput,
  secureConfigs?: Secure_add_tags
): Promise<any[]>

Configurações de segurança (Secure_add_tags)

• overwrite: sobrescreve tags existentes
• enableAutoComplete: reutiliza tags atuais automaticamente

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.

Obter últimas threads (conversas)

get_last_threads(): Promise<LastThreadsResponse>

Retorna as conversas mais recentes (threads) do bot.

Retorno

{
  total: number;
  items: ConversationItem[];
}

Obter mensagens de uma conversa

get_last_messages(contactId: string): Promise<LastMessagesResponse>

Retorna todas as mensagens associadas a uma thread específica.

Parâmetros

• contactId: string: Identificador do contato

Retorno

{
  total: number;
  items: any[];
}

Obter mensagens registradas (log global)

get_logged_messages(): Promise<LoggedMessagesResponse>

Retorna o log global de mensagens processadas pelo bot.

Retorno

{
  total: number;
  items: any[];
}

Obter notificações de mensagens (eventos)

get_logged_notifications(messageId?: string): Promise<MessageEventResponse>

Retorna eventos do ciclo de vida das mensagens, como:

• accepted

• dispatched

• received

• failed

Retorno

{
  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

{
  total: number;
  items: MessageEvent[];
}