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.

1. Contatos

1.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.
 * @param {string[]} tagIds - Caso queira vincular tags ao um contato.
 * @param {string} platform - Caso queira que o contato possua uma plataforma exclusiva.
 * @param {boolean} isIgnored - Se 'true' o OMC não interceptará mensagens desse contato.
 */
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)

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

await this.contactApi.update(payload)

1.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)

1.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)

1.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)

1.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)

1.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)

1.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)

2. Tags

2.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)

2.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)

2.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)

2.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)

2.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)

2.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)

3. Mensagens

3.1 Iniciar Conversa

  • Inicia uma nova conversa com um contato. O campo companyId é obrigatório apenas quando o provedor é 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 (número de telefone, etc).
 * @param {string} userName - Nome do usuário.
 * @param {string} companyName - Nome da empresa (obrigatório apenas 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: '5521988887777',
    userName: 'João Silva',
    companyName: 'Empresa XYZ'
}

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

3.2 Enviar Mensagem de Texto

  • Envia uma mensagem de texto em uma conversa existente.

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} text - Texto da mensagem.
 * @param {object} quotedMessage - Mensagem citada (opcional).
 */
const payload: SendMessageDto = {
    agentName: 'Atendente João',
    sessionId: '64ef5c85f9deb132696591a0',
    text: 'Olá! Como posso ajudá-lo hoje?'
}

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

3.3 Enviar Mensagem de Mídia

  • Envia uma mensagem contendo mídia (imagem, vídeo, documento, etc).

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 João',
    sessionId: '64ef5c85f9deb132696591a0',
    mediaUri: 'https://exemplo.com/imagem.jpg'
}

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

3.4 Enviar Mensagem Interativa

  • Não implementado.

3.5 Enviar Mensagem Proativa

  • Envia uma mensagem proativa para iniciar ou continuar uma conversa.

Exemplo:

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

constructor(private readonly messageApi: MessageApi) {}

/**
 * @param {string} channelId - Identificador do canal.
 * @param {string} recipientNumber - Número do destinatário.
 * @param {string} platform - Plataforma utilizada.
 * @param {string} text - Texto da mensagem (opcional).
 * @param {string} mediaUri - URL da mídia (opcional).
 * @param {object} quotedMessage - Mensagem citada (opcional).
 */
const payload: SendPlatformMessagePayload = {
    channelId: '64ef5c84f9deb1326965919e',
    recipientNumber: '5521988887777',
    platform: 'karoochat',
    text: 'Mensagem proativa de exemplo'
}

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

3.6 Enviar Mensagem para Grupo

  • Envia uma mensagem para uma conversa em 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)

3.7 Deletar Mensagem

  • Remove uma mensagem específica da conversa.

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)