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 Envio de Mídias com Legenda

Não implementado.

5.4 Enviar Sticker

Não implementado.

5.5 Enviar Contatos

Não implementado.

5.6 Enviar Reação em Mensagens Individuais

Não implementado.

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} sessionId - Identificador da sessão.
 * @param {string} agentName - Nome do agente que está enviando a mensagem.
 * @param {object} interactive - Objeto da mensagem interativa.
 * @param {string} interactive.type - Tipo da mensagem interativa (list).
 * @param {object} interactive.body - Corpo da mensagem.
 * @param {string} interactive.body.text - Texto principal da mensagem.
 * @param {object} interactive.action - Ações disponíveis.
 * @param {string} interactive.action.button - Texto do botão principal.
 * @param {array} interactive.action.sections - Seções com opções.
 */
const payload: SendMessageDto = {
    sessionId: '651f0e422ed69abd580b3761',
    agentName: 'Atendente Maria',
    interactive: {
        type: 'list',
        body: {
            text: 'Escolha uma das opções abaixo:'
        },
        action: {
            button: 'Ver Opções',
            sections: [
                {
                    rows: [
                        {
                            id: 'opcao_1',
                            title: 'Suporte Técnico',
                            description: 'Problemas com produtos ou serviços'
                        },
                        {
                            id: 'opcao_2',
                            title: 'Vendas',
                            description: 'Informações sobre produtos'
                        },
                        {
                            id: 'opcao_3',
                            title: 'Financeiro',
                            description: 'Dúvidas sobre pagamentos'
                        }
                    ]
                }
            ]
        }
    }
}

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} sessionId - Identificador da sessão.
 * @param {string} agentName - Nome do agente que está enviando a mensagem.
 * @param {object} interactive - Objeto da mensagem interativa.
 * @param {string} interactive.type - Tipo da mensagem interativa (button).
 * @param {object} interactive.body - Corpo da mensagem.
 * @param {string} interactive.body.text - Texto principal da mensagem.
 * @param {object} interactive.action - Ações disponíveis.
 * @param {array} interactive.action.buttons - Array de botões.
 */
const payload: SendMessageDto = {
    sessionId: '651f0e422ed69abd580b3761',
    agentName: 'Atendente Maria',
    interactive: {
        type: 'button',
        body: {
            text: 'Deseja continuar com o atendimento?'
        },
        action: {
            buttons: [
                {
                    type: 'reply',
                    reply: {
                        id: 'sim',
                        title: 'Sim'
                    }
                },
                {
                    type: 'reply',
                    reply: {
                        id: 'nao',
                        title: 'Não'
                    }
                }
            ]
        }
    }
}

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, 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)

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:

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)

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:

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

constructor(private readonly messageApi: MessageApi) {}

/**
 * @param {string} sessionId - Identificador da sessão.
 * @param {string} agentName - Nome do agente que está enviando a mensagem.
 * @param {object} interactive - Objeto da mensagem interativa.
 * @param {string} interactive.type - Tipo da mensagem interativa (list).
 * @param {object} interactive.body - Corpo da mensagem.
 * @param {string} interactive.body.text - Texto principal da mensagem.
 * @param {object} interactive.action - Ações disponíveis.
 * @param {string} interactive.action.button - Texto do botão principal.
 * @param {array} interactive.action.sections - Seções com opções.
 */
const payload: SendMessageDto = {
    sessionId: '651f0e422ed69abd580b3761',
    agentName: 'Atendente Maria',
    interactive: {
        type: 'list',
        body: {
            text: 'Escolha uma das opções abaixo:'
        },
        action: {
            button: 'Ver Opções',
            sections: [
                {
                    rows: [
                        {
                            id: 'opcao_1',
                            title: 'Suporte Técnico',
                            description: 'Problemas com produtos ou serviços'
                        },
                        {
                            id: 'opcao_2',
                            title: 'Vendas',
                            description: 'Informações sobre produtos'
                        },
                        {
                            id: 'opcao_3',
                            title: 'Financeiro',
                            description: 'Dúvidas sobre pagamentos'
                        }
                    ]
                }
            ]
        }
    }
}

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} sessionId - Identificador da sessão.
 * @param {string} agentName - Nome do agente que está enviando a mensagem.
 * @param {object} interactive - Objeto da mensagem interativa.
 * @param {string} interactive.type - Tipo da mensagem interativa (button).
 * @param {object} interactive.body - Corpo da mensagem.
 * @param {string} interactive.body.text - Texto principal da mensagem.
 * @param {object} interactive.action - Ações disponíveis.
 * @param {array} interactive.action.buttons - Array de botões.
 */
const payload: SendMessageDto = {
    sessionId: '651f0e422ed69abd580b3761',
    agentName: 'Atendente Maria',
    interactive: {
        type: 'button',
        body: {
            text: 'Deseja continuar com o atendimento?'
        },
        action: {
            buttons: [
                {
                    type: 'reply',
                    reply: {
                        id: 'sim',
                        title: 'Sim'
                    }
                },
                {
                    type: 'reply',
                    reply: {
                        id: 'nao',
                        title: 'Não'
                    }
                }
            ]
        }
    }
}

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

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

Método não suportado pela plataforma.

7. Templates

7.1 Criar Template

Cria um novo template de mensagem para o canal D360.

Exemplo:

import { SetupApi, CreateTemplateDto, TemplateCategoriesEnum } from '@cirrus/omnichannel_api'

constructor(private readonly setupApi: SetupApi) {}

/**
 * @param {string} name - Nome do template.
 * @param {TemplateCategoriesEnum} category - Categoria do template (UTILITY ou MARKETING).
 * @param {string} language - Código do idioma (ex: 'pt_BR').
 * @param {array} components - Componentes do template.
 */
const templateDto: CreateTemplateDto = {
    name: 'welcome_message',
    category: TemplateCategoriesEnum.UTILITY,
    language: 'pt_BR',
    components: [
        {
            type: 'BODY',
            text: 'Olá {{1}}, bem-vindo à nossa empresa! Seu código de verificação é {{2}}.',
            example: {
                body_text: [['João', '123456']]
            }
        }
    ]
}

const template = await this.setupApi.createTemplate('64ef5c84f9deb1326965919e', templateDto)

7.2 Listar Templates

Obtém a lista de templates disponíveis para um canal D360. Esta funcionalidade é específica do D360.

Exemplo:

import { SetupApi, TemplatesInterface } from '@cirrus/omnichannel_api'

constructor(private readonly setupApi: SetupApi) {}

/**
 * @param {string} channelId - Identificador do canal D360.
 */
const templates: TemplatesInterface[] = await this.setupApi.getTemplates('64ef5c84f9deb1326965919e')

// Resposta:
// [
//   {
//     "name": "hello_world",
//     "category": "UTILITY",
//     "status": "APPROVED",
//     "full": { /* objeto completo do template */ }
//   }
// ]

WhatsApp (Web)

WhatsApp (Meta)

WhatsApp (D360)

Telegram

Facebook

Instagram

Erro de "BSP Permission Removed" no Dialog360

WhatsApp (D360)

Visão Geral

1. Configuração e Setup

1.1 Setup do Provedor D360

1.2 Onboarding D360

2. Contatos

3. Tags

4. Conversa

4.1 Iniciar Conversa

5. Mensagens individuais

5.1 Enviar Mensagem de Texto

5.2 Enviar Mensagem de Mídia

5.3 Envio de Mídias com Legenda

5.4 Enviar Sticker

5.5 Enviar Contatos

5.6 Enviar Reação em Mensagens Individuais

5.7 Enviar Mensagem Interativa

5.8 Enviar Localização

5.9 Enviar Endereço

5.10 Solicitação de Localização

5.11 Encaminhar mensagem

5.12 Deletar Mensagem Individual

6. Mensagens de Grupo

6.1 Enviar Mensagem de Texto para Grupo

6.2 Enviar Mensagem de Mídia para Grupo

6.3 Envio de Mídias com Legenda para Grupos

6.4 Enviar Sticker para Grupos

6.5 Enviar Contatos para Grupos

6.6 Enviar Reação em Mensagens de Grupos

6.7 Enviar Mensagem Interativa em Grupos

6.8 Enviar Localização em Grupos

6.9 Enviar Endereço

6.10 Solicitação de Localização

6.11 Encaminhar Mensagem

6.12 Deletar Mensagem de Grupo

7. Templates

7.1 Criar Template

7.2 Listar Templates