Ir para o conteúdo principal

WhatsApp (Web) - Em construção

Visão Geral

Este documento descreve as funcionalidades disponíveis para as integrações 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. Mensagens

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

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

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