WhatsApp (D360)

Visão Geral

Este documento descreve as funcionalidades disponíveis para a integração com o WhatsApp (D360) 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 D360

Configura um novo canal D360 com as credenciais e parâmetros necessários. O D360 suporta modo sandbox para testes e modo produção.

Exemplo:

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

constructor(private readonly setupApi: SetupApi) {}

/**
 * @param {string} clientIdentifier - Identificador único do cliente.
 * @param {object} provider - Configurações do provedor D360.
 * @param {string} provider.token - Token de API do D360.
 * @param {string} provider.clientNumber - Número do cliente (opcional).
 * @param {string} provider.namespace - Namespace do D360 (opcional).
 * @param {string} provider.template - Template padrão (opcional).
 * @param {boolean} provider.isSandbox - Se está em modo sandbox.
 * @param {string} provider.accountName - Nome da conta (opcional).
 * @param {string} startingPlatform - Plataforma inicial.
 * @param {array} platforms - Configurações das plataformas.
 * @param {string} description - Descrição do canal (opcional).
 */
const setupDto: SetupD360Dto = {
    clientIdentifier: '9a92ea44-244c-4cda-86be-6a9e32ba8f34',
    provider: {
        token: 'your_d360_api_token',
        clientNumber: '5521999999999',
        namespace: 'your_namespace',
        template: 'hello_world',
        isSandbox: false,
        accountName: 'My Company'
    },
    startingPlatform: 'karoochat',
    platforms: [
        {
            callbackUrl: 'https://myapp.com/webhook',
            slug: 'karoochat'
        }
    ],
    description: 'Canal D360 para atendimento'
}

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

1.2 Onboarding D360

Realiza o processo de onboarding automatizado para múltiplos canais D360. Este processo configura automaticamente os webhooks e credenciais necessárias.

Exemplo:

import { SetupApi, OnboardingParamsDto, OnboardingResponseDto } from '@cirrus/omnichannel_api'

constructor(private readonly setupApi: SetupApi) {}

/**
 * @param {string} client - Identificador do cliente.
 * @param {string[]} channels - Lista de canais para onboarding.
 * @param {string[]} revoked - Lista de canais revogados (opcional).
 * @param {string} template - Template padrão (opcional).
 * @param {string} redirect - URL de redirecionamento (opcional).
 * @param {string} clientIdentifier - Identificador único do cliente.
 * @param {string} startingPlatform - Plataforma inicial.
 */
const onboardingParams: OnboardingParamsDto = {
    client: 'my_company',
    channels: ['5521999999999', '5521888888888'],
    revoked: ['5521777777777'],
    template: 'hello_world',
    redirect: 'https://myapp.com/onboarding-success',
    clientIdentifier: '9a92ea44-244c-4cda-86be-6a9e32ba8f34',
    startingPlatform: 'karoochat'
}

const response: OnboardingResponseDto[] = await this.setupApi.onboarding(onboardingParams)

// Resposta quando redirect não é fornecido:
// [
//   {
//     "channel": "5521999999999",
//     "clientNumber": "5521999999999",
//     "platformConfigId": "64ec8226e35a9b6ce663bf07",
//     "channelId": "64ec9650a1ebf28cb9fa37f0",
//     "namespace": "your_namespace",
//     "token": "your_api_key"
//   }
// ]

2. Contatos

No momento a regra de negócio só está permitindo cadastrar contatos de Whatsapp Web.

3. Tags

No momento a regra de negócio só está permitindo cadastrar tags para contatos de Whatsapp Web.

4. Conversa

4.1 Iniciar Conversa

Inicia uma nova conversa com um contato via D360. O campo companyName não é obrigatório para D360.

Exemplo:

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

constructor(private readonly messageApi: MessageApi) {}

const payload: StartConversationDto = {
    platformConfigId: '64ef5c84f9deb1326965919f',
    channelId: '64ef5c84f9deb1326965919e',
    clientProviderId: '5521999999999',
    userName: 'João Silva',
    platform: 'karoochat',
    sessionWithPriority: false
}

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

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) {}

const payload: SendMessageDto = {
    agentName: 'Atendente Maria',
    sessionId: '64ef5c85f9deb132696591a0',
    mediaUri: 'https://exemplo.com/documento.pdf'
}

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

5.3 Enviar Sticker

Não implementado.

5.4 Enviar Contatos

Não implementado.

5.5 Enviar Reação

Não implementado.

5.6 Enviar Botões Interativos

Envia mensagens com botões interativos 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 {object} interactive - Objeto com configuração dos botões interativos.
 */
const payload: SendMessageDto = {
    agentName: 'Atendente João',
    sessionId: '64ef5c85f9deb132696591a0',
    interactive: {
        type: 'button',
        body: {
            text: 'Como posso ajudá-lo hoje?'
        },
        action: {
            buttons: [
                {
                    type: 'reply',
                    reply: {
                        id: '1',
                        title: 'Suporte'
                    }
                },
                {
                    type: 'reply',
                    reply: {
                        id: '2',
                        title: 'Vendas'
                    }
                }
            ]
        }
    }
}

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