Ir para o conteúdo principal

WhatsApp (Web)

Visão Geral

Este documento descreve as funcionalidades disponíveis para a integração com o WhatsApp Web no sistema Omnichannel, incluindo exemplos de chamadas nos métodos disponíveis na lib.

Nota: Esta documentação apresenta exemplos utilizando NestJS com injeção de dependência, mas a biblioteca pode ser utilizada em qualquer projeto JavaScript/TypeScript. Para uso fora do NestJS, utilize o método getInstance() das classes (ex: SetupApi.getInstance(), MessageApi.getInstance()).

1. Configuração e Setup

1.1 Setup do Provedor WhatsApp Web

  • Configura um novo canal WhatsApp Web com as credenciais e parâmetros necessários. O WhatsApp Web requer o campo companyId obrigatório.

Exemplo:

import { SetupApi, SetupWhatsappWebDto, MessageServiceEnum } from '@cirrus/omnichannel_api'

constructor(private readonly setupApi: SetupApi) {}

/**
 * @param {string} clientIdentifier - Identificador único do cliente.
 * @param {object} provider - Configurações do provedor WhatsApp Web.
 * @param {string} provider.clientNumber - Número do cliente (obrigatório).
 * @param {string} provider.companyId - ID da empresa (obrigatório).
 * @param {string} startingPlatform - Plataforma inicial.
 * @param {array} platforms - Configurações das plataformas.
 * @param {string} description - Descrição do canal (opcional).
 */
const setupDto: SetupWhatsappWebDto = {
    clientIdentifier: '9a92ea44-244c-4cda-86be-6a9e32ba8f34',
    provider: {
        clientNumber: '5521999999999',
        companyId: 'my_company_id'
    },
    startingPlatform: 'karoochat',
    platforms: [
        {
            callbackUrl: 'https://myapp.com/webhook',
            slug: 'karoochat'
        }
    ],
    description: 'Canal WhatsApp Web para atendimento'
}

const platformConfig = await this.setupApi.setup(setupDto, MessageServiceEnum.whatsappweb)

1.2 Onboarding WhatsApp Web

  • Realiza o processo de onboarding através de popup para escaneamento do QR Code. Este processo conecta o WhatsApp Web ao sistema.

Exemplo:

import { WhatsappWebUtils, OnboardingProps } from '@cirrus/omnichannel_api'

/**
 * @param {string} providerId - Identificador do provedor.
 * @param {function} onConnect - Callback executado quando conecta.
 * @param {function} onError - Callback executado em caso de erro.
 * @param {string} platformConfigId - ID da configuração da plataforma (opcional).
 * @param {string} channelId - ID do canal (opcional).
 */
const onboardingProps: OnboardingProps = {
    providerId: '5521999999999',
    onConnect: () => {
        console.log('WhatsApp Web conectado com sucesso!')
    },
    onError: (error) => {
        console.error('Erro na conexão:', error)
    },
    platformConfigId: '64ef5c84f9deb1326965919f',
    channelId: '64ef5c84f9deb1326965919e'
}

const whatsappUtils = await WhatsappWebUtils.getInstance()
await whatsappUtils.onboarding(onboardingProps)

2. Contatos

2.1 Criação de Contatos

  • Atualmente, existem dois tipos de contatos: individuais e grupos. Ao cadastrar, o parâmetro type deve ser definido como 'individual' ou 'group', respectivamente. Visto que a implementação atual suporta apenas o WhatsApp, o parâmetro channelType deve ser obrigatoriamente 'whatsapp'.

Exemplo:

import { ContactApi, CreateContactDto } from '@cirrus/omnichannel_api'

constructor(private readonly contactApi: ContactApi) {}

/**
 * @param {string} clientIdentifier - Identificador único da conta.
 * @param {string} channelId - Identificador do canal.
 * @param {string} contactIdentifier - Contato do usuário (número de telefone, token (Telegram, etc).
 * @param {string} name - Ordem em que os itens serão buscados (crescente ou decrescente).
 * @param {string} type - Tipo do contato.
 * @param {string} channelType - Tipo do canal.
 * @param {string} customName - Nome customizado para o contato.    
 * @param {string} photo - Url da foto de perfil do contato no S3 (opcional).
 * @param {string[]} tagIds - Caso queira vincular tags ao um contato (opcional).
 * @param {string} platform - Caso queira que o contato possua uma plataforma exclusiva (opcional).
 * @param {boolean} isIgnored - Se 'true' o OMC não interceptará mensagens desse contato (opcional).
 */
const payload: CreateContactDto = {
    clientIdentifier: '9a92ea44-244c-4cda-86be-6a9e32ba8f34',
    channelId: '689a05215b711247e8f54022',
    contactIdentifier: '5521999999999',
    name: 'João Silva',
    type: 'individual',
    channelType: 'whatsapp',
    customName: 'João (Mercearia)',
}

await this.contactApi.create(payload)

2.2 Edição de Contatos

  • Edita um contato previamente cadastrado.

Exemplo:

import { ContactApi, UpdateContactDto } from '@cirrus/omnichannel_api'

constructor(private readonly contactApi: ContactApi) {}

/**
 * @param {string} clientIdentifier - Identificador único da conta.
 * @param {string} contactId - Identificador do contato.
 * @param {string} customName - Nome customizado para o contato (opcional).    
 * @param {string} platform - Caso queira que o contato possua uma plataforma exclusiva (opcional).
 * @param {string[]} tagIds - Caso queira vincular tags ao um contato (opcional).
 * @param {string} contactIdentifier - Contato do usuário, número de telefone, token Telegram, etc... (opcional).
 * @param {boolean} isIgnored - Se 'true' o OMC não interceptará mensagens desse contato (opcional).
 */
const payload: UpdateContactDto = {
    clientIdentifier: '9a92ea44-244c-4cda-86be-6a9e32ba8f34',
    contactId: '68e54649a3744412be5cc107',
    customName: 'Nome Modificado',
    platform: 'karoochatnew',
}

await this.contactApi.update(payload)

2.3 Listar Contato por Id

  • Busca um contato de uma conta (clientIdentifier) pelo seu identificador (contactId).

Exemplo:

import { ContactApi, GetContactDto } from '@cirrus/omnichannel_api'

constructor(private readonly contactApi: ContactApi) {}

/**
 * @param {string} clientIdentifier - Identificador único da conta.
 * @param {string} contactId - Identificador único do contato.
 */
const payload: GetContactDto = {
    clientIdentifier: '9a92ea44-244c-4cda-86be-6a9e32ba8f34',
    contactId: '68e54649a3744412be5cc107',
}

await this.contactApi.getById(payload)

2.4 Listar Contatos com Paginação

  • Busca uma lista paginada de contatos com filtros opcionais.

Exemplo:

import { ContactApi, GetContactsDto } from '@cirrus/omnichannel_api'

constructor(private readonly contactApi: ContactApi) {}

/**
 * @param {string} clientIdentifier - Identificador único da conta.
 * @param {number} page - Número da página (padrão: 1).
 * @param {number} limit - Limite de itens por página (padrão: 30).
 * @param {string} order - Ordem de classificação ('asc' ou 'desc').
 * @param {string} type - Tipo do contato ('individual' ou 'group').
 * @param {string} channelType - Tipo do canal.
 * @param {string} name - Filtro por nome do contato.
 * @param {string} contactIdentifier - Filtro por identificador do contato.
 * @param {string[]} tagIds - Filtro por IDs de tags associadas.
 */
const payload: GetContactsDto = {
    clientIdentifier: '9a92ea44-244c-4cda-86be-6a9e32ba8f34',
    page: 1,
    limit: 10,
    order: 'desc',
    type: 'individual',
    channelType: 'whatsapp',
    name: 'João'
}

const response = await this.contactApi.get(payload)

2.5 Remover Plataforma do Contato

  • Remove a associação de plataforma de um contato específico.

Exemplo:

import { ContactApi, DeleteContactPlatformDto } from '@cirrus/omnichannel_api'

constructor(private readonly contactApi: ContactApi) {}

/**
 * @param {string} clientIdentifier - Identificador único da conta.
 * @param {string} contactId - Identificador único do contato.
 */
const payload: DeleteContactPlatformDto = {
    clientIdentifier: '9a92ea44-244c-4cda-86be-6a9e32ba8f34',
    contactId: '68e54649a3744412be5cc107'
}

await this.contactApi.deletePlatform(payload)

2.6 Listar Tags do Contato

  • Obtém todas as tags associadas a um contato específico.

Exemplo:

import { ContactApi, GetTagsByContactIdDto } from '@cirrus/omnichannel_api'

constructor(private readonly contactApi: ContactApi) {}

/**
 * @param {string} clientIdentifier - Identificador único da conta.
 * @param {string} contactId - Identificador único do contato.
 */
const payload: GetTagsByContactIdDto = {
    clientIdentifier: '9a92ea44-244c-4cda-86be-6a9e32ba8f34',
    contactId: '68e54649a3744412be5cc107'
}

const tags = await this.contactApi.getTagsByContacId(payload)

2.7 Adicionar Tags ao Contato

  • Adiciona uma ou mais tags a um contato existente.

Exemplo:

import { ContactApi, AddContactTagDto } from '@cirrus/omnichannel_api'

constructor(private readonly contactApi: ContactApi) {}

/**
 * @param {string} clientIdentifier - Identificador único da conta.
 * @param {string} contactId - Identificador único do contato.
 * @param {string[]} tagIds - Array com os IDs das tags a serem adicionadas.
 */
const payload: AddContactTagDto = {
    clientIdentifier: '9a92ea44-244c-4cda-86be-6a9e32ba8f34',
    contactId: '68e54649a3744412be5cc107',
    tagIds: ['tag1', 'tag2', 'tag3']
}

const updatedContact = await this.contactApi.addTags(payload)

2.8 Remover Tags do Contato

  • Remove uma ou mais tags de um contato existente.

Exemplo:

import { ContactApi, RemoveContactTagDto } from '@cirrus/omnichannel_api'

constructor(private readonly contactApi: ContactApi) {}

/**
 * @param {string} clientIdentifier - Identificador único da conta.
 * @param {string} contactId - Identificador único do contato.
 * @param {string[]} tagIds - Array com os IDs das tags a serem removidas.
 */
const payload: RemoveContactTagDto = {
    clientIdentifier: '9a92ea44-244c-4cda-86be-6a9e32ba8f34',
    contactId: '68e54649a3744412be5cc107',
    tagIds: ['tag1', 'tag2']
}

const updatedContact = await this.contactApi.removeTags(payload)

3. Tags

3.1 Criação de Tags

  • Cria uma nova tag para organizar e categorizar contatos.

Exemplo:

import { TagApi, CreateTagDto } from '@cirrus/omnichannel_api'

constructor(private readonly tagApi: TagApi) {}

/**
 * @param {string} clientIdentifier - Identificador único da conta.
 * @param {string} name - Nome da tag.
 * @param {string} color - Cor da tag em formato hexadecimal.
 */
const payload: CreateTagDto = {
    clientIdentifier: '9a92ea44-244c-4cda-86be-6a9e32ba8f34',
    name: 'Cliente VIP',
    color: '#ff0000'
}

const tag = await this.tagApi.create(payload)

3.2 Listar Tags

  • Obtém uma lista de tags com filtro opcional por nome.

Exemplo:

import { TagApi, GetTagsDto } from '@cirrus/omnichannel_api'

constructor(private readonly tagApi: TagApi) {}

/**
 * @param {string} clientIdentifier - Identificador único da conta.
 * @param {string} name - Filtro por nome da tag (opcional).
 */
const payload: GetTagsDto = {
    clientIdentifier: '9a92ea44-244c-4cda-86be-6a9e32ba8f34',
    name: 'VIP'
}

const tags = await this.tagApi.get(payload)

3.3 Buscar Tag por ID

  • Obtém uma tag específica pelo seu identificador.

Exemplo:

import { TagApi, GetTagByIdDto } from '@cirrus/omnichannel_api'

constructor(private readonly tagApi: TagApi) {}

/**
 * @param {string} clientIdentifier - Identificador único da conta.
 * @param {string} tagId - Identificador único da tag.
 */
const payload: GetTagByIdDto = {
    clientIdentifier: '9a92ea44-244c-4cda-86be-6a9e32ba8f34',
    tagId: '68e54649a3744412be5cc107'
}

const tag = await this.tagApi.getById(payload)

3.4 Atualizar Tag

  • Atualiza as informações de uma tag existente.

Exemplo:

import { TagApi, UpdateTagDto } from '@cirrus/omnichannel_api'

constructor(private readonly tagApi: TagApi) {}

/**
 * @param {string} clientIdentifier - Identificador único da conta.
 * @param {string} tagId - Identificador único da tag.
 * @param {string} name - Novo nome da tag (opcional).
 * @param {string} color - Nova cor da tag em formato hexadecimal (opcional).
 */
const payload: UpdateTagDto = {
    clientIdentifier: '9a92ea44-244c-4cda-86be-6a9e32ba8f34',
    tagId: '68e54649a3744412be5cc107',
    name: 'Cliente Premium',
    color: '#00ff00'
}

const updatedTag = await this.tagApi.update(payload)

3.5 Deletar Tag

  • Remove uma tag cadastrada.

Exemplo:

import { TagApi, DeleteTagDto } from '@cirrus/omnichannel_api'

constructor(private readonly tagApi: TagApi) {}

/**
 * @param {string} clientIdentifier - Identificador único da conta.
 * @param {string} tagId - Identificador único da tag a ser removida.
 */
const payload: DeleteTagDto = {
    clientIdentifier: '9a92ea44-244c-4cda-86be-6a9e32ba8f34',
    tagId: '68e54649a3744412be5cc107'
}

await this.tagApi.delete(payload)

3.6 Listar Contatos por Tag

  • Obtém todos os contatos que possuem uma tag específica.

Exemplo:

import { TagApi, GetContactsByTagIdDto } from '@cirrus/omnichannel_api'

constructor(private readonly tagApi: TagApi) {}

/**
 * @param {string} clientIdentifier - Identificador único da conta.
 * @param {string} tagId - Identificador único da tag.
 */
const payload: GetContactsByTagIdDto = {
    clientIdentifier: '9a92ea44-244c-4cda-86be-6a9e32ba8f34',
    tagId: '68e54649a3744412be5cc107'
}

const contacts = await this.tagApi.getContactsByTagId(payload)

4. Conversa

4.1 Iniciar Conversa

  • Inicia uma nova conversa com um contato via WhatsApp Web. O campo companyName é obrigatório para WhatsApp Web.

Exemplo:

import { MessageApi, StartConversationDto, MessageServiceEnum } from '@cirrus/omnichannel_api'

constructor(private readonly messageApi: MessageApi) {}

/**
 * @param {string} platformConfigId - Identificador da configuração da plataforma.
 * @param {string} channelId - Identificador do canal.
 * @param {string} clientProviderId - Identificador do cliente no provedor.
 * @param {string} userName - Nome do usuário.
 * @param {string} companyName - Nome da empresa (obrigatório para WhatsApp Web).
 * @param {string} platform - Plataforma específica.
 * @param {boolean} sessionWithPriority - Se a sessão deve ter prioridade.
 */
const payload: StartConversationDto = {
    platformConfigId: '64ef5c84f9deb1326965919f',
    channelId: '64ef5c84f9deb1326965919e',
    clientProviderId: '5521999999999',
    userName: 'João Silva',
    companyName: 'Minha Empresa Ltda',
    platform: 'karoochat',
    sessionWithPriority: false
}

const response = await this.messageApi.startConversation(payload, MessageServiceEnum.whatsappweb)

5. Mensagens individuais

5.1 Enviar Mensagem de Texto

  • Envia uma mensagem de texto para um contato individual.

Exemplo:

import { MessageApi, SendMessageDto } from '@cirrus/omnichannel_api'

constructor(private readonly messageApi: MessageApi) {}

/**
 * @param {string} agentName - Nome do agente.
 * @param {string} sessionId - Identificador da sessão.
 * @param {string} text - Texto da mensagem.
 */
const payload: SendMessageDto = {
    agentName: 'Atendente João',
    sessionId: '64ef5c85f9deb132696591a0',
    text: 'Olá! Como posso ajudá-lo hoje?'
}

const response = await this.messageApi.sendMessage(payload)

5.2  Enviar Mensagem de Mídia

  • Envia mensagens com anexos de mídia (imagens, vídeos, documentos, áudios).

Exemplo:

import { MessageApi, SendMessageDto } from '@cirrus/omnichannel_api'

constructor(private readonly messageApi: MessageApi) {}

/**
 * @param {string} agentName - Nome do agente que está enviando a mensagem.
 * @param {string} sessionId - Identificador da sessão.
 * @param {string} mediaUri - URL da mídia a ser enviada.
 */
const payload: SendMessageDto = {
    agentName: 'Atendente Maria',
    sessionId: '64ef5c85f9deb132696591a0',
    mediaUri: 'https://exemplo.com/documento.pdf'
}

const response = await this.messageApi.sendMessage(payload)

5.3 Envio de Mídias com Legenda

  • Não implementado.

5.4 Enviar Sticker

  • (Adicionar documentação)

5.5 Enviar Contatos

  • (Adicionar documentação)

5.6 Enviar Reação em Mensagens Individuais

  • (Adicionar documentação)

5.7 Enviar Mensagem Interativa

  • O D360 suporta mensagens interativas avançadas, incluindo botões e listas. Esta é uma funcionalidade exclusiva do D360 (API Oficial) não disponível no WhatsApp Web.

Exemplo - Lista Interativa:

import { MessageApi, SendMessageDto } from '@cirrus/omnichannel_api'

constructor(private readonly messageApi: MessageApi) {}

/**
 * @param {string} agentName - Nome do agente que está enviando a mensagem.
 * @param {string} sessionId - Identificador da sessão.
 * @param {string} mediaUri - URL da mídia a ser enviada.
 */
const payload: SendMessageDto = {
    agentName: 'Atendente Maria',
    sessionId: '64ef5c85f9deb132696591a0',
    mediaUri: 'https://exemplo.com/documento.pdf'
}

const response = await this.messageApi.sendMessage(payload)

Exemplo - Botões Interativos:

import { MessageApi, SendMessageDto } from '@cirrus/omnichannel_api'

constructor(private readonly messageApi: MessageApi) {}

/**
 * @param {string} agentName - Nome do agente que está enviando a mensagem.
 * @param {string} sessionId - Identificador da sessão.
 * @param {string} mediaUri - URL da mídia a ser enviada.
 */
const payload: SendMessageDto = {
    agentName: 'Atendente Maria',
    sessionId: '64ef5c85f9deb132696591a0',
    mediaUri: 'https://exemplo.com/documento.pdf'
}

const response = await this.messageApi.sendMessage(payload)

5.8 Enviar Localização

  • Não implementado.

5.9 Enviar Endereço

  • Não implementado.

5.10 Solicitação de Localização

  • Não implementado.

5.11 Encaminhar mensagem

  • Não implementado.

5.12 Deletar Mensagem Individual

  • Método não suportado pela plataforma.

6. Mensagens de Grupo

6.1 Enviar Mensagem de Texto para Grupo

  • Envia uma mensagem de texto para um grupo.

Exemplo:

import { MessageApi, SendPlatformMessagePayload } from '@cirrus/omnichannel_api'

constructor(private readonly messageApi: MessageApi) {}

/**
 * @param {string} channelId - Identificador do canal.
 * @param {string} recipientNumber - Identificador do grupo.
 * @param {string} platform - Plataforma utilizada.
 * @param {string} text - Texto da mensagem (opcional).
 * @param {string} mediaUri - URL da mídia (opcional).
 */
const payload: SendPlatformMessagePayload = {
    channelId: '64ef5c84f9deb1326965919e',
    recipientNumber: 'grupo123',
    platform: 'karoochat',
    text: 'Mensagem para o grupo'
}

const response = await this.messageApi.sendGroupMessage(payload)

6.2 Enviar Mensagem de Mídia para Grupo

  • Envia mensagens com anexos de mídia para um grupo (imagens, vídeos, documentos, áudios).

Exemplo:

6.3 Envio de Mídias com Legenda para Grupos

  • Não implementado.

6.4 Enviar Sticker para Grupos

  • Não implementado.

6.5 Enviar Contatos para Grupos

  • Não implementado.

6.6 Enviar Reação em Mensagens de Grupos

  • Não implementado.

6.7 Enviar Mensagem Interativa em Grupos

  • O D360 suporta mensagens interativas avançadas, incluindo botões e listas. Esta é uma funcionalidade exclusiva do D360 (API Oficial) não disponível no WhatsApp Web.

Exemplo - Lista Interativa:
Exemplo - Botões Interativos:

6.8 Enviar Localização em Grupos

  • Não implementado.

6.9 Enviar Endereço

  • Não implementado.

6.10 Solicitação de Localização

  • Não implementado.

6.11 Encaminhar Mensagem

  • Não implementado.

6.12 Deletar Mensagem de Grupo

  • Remove uma mensagem específica de uma conversa em um grupo

Exemplo:

import { MessageApi, DeleteMessageDto } from '@cirrus/omnichannel_api'

constructor(private readonly messageApi: MessageApi) {}

/**
 * @param {string} messageId - Identificador da mensagem a ser deletada.
 * @param {string} senderId - Identificador do remetente.
 * @param {string} channelSlug - Slug do canal.
 */
const payload: DeleteMessageDto = {
    messageId: 'msg_123456789',
    senderId: 'sender_123',
    channelSlug: 'karoochat'
}

await this.messageApi.deleteMessage(payload)