Ir para o conteúdo principal

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

/**
 * @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} 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',
    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) {}

/**
 * @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 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)