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

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[];

}

ts-blip SDK

Instalação

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[];

}