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
- 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 Localização
- Não implementado.
5.10 Enviar BotõesEndereço
- Não implementado.
5.11 Solicitação de Localização
- Não implementado.
5.12 Encaminhar mensagem
- Não implementado.
5. Mensagens de Grupo
5.1 Enviar Mensagem de Texto para Grupo
- Envia
mensagensumacommensagembotõesdeinterativostexto para umcontato individual.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 {object}string} interactivetext - ObjetoTexto comda configuração dos botões interativos.mensagem.
*/
const payload: SendMessageDto = {
agentName: 'Atendente João',
sessionId: '64ef5c85f9deb132696591a0',
interactive: {
type: 'button',
body: {
text: 'Olá! 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)5.82 Enviar ListasMensagem Interativasde Mídia para Grupo
- Envia mensagens com
listasanexosinterativasde mídia para umcontatogrupoindividual.(imagens, vídeos, documentos, áudios).
Exemplo:
import { MessageApi, SendMessageDto } from '@cirrus/omnichannel_api'
constructor(private readonly messageApi: MessageApi) {}
/**
* @param {string} agentName - Nome do agente.agente que está enviando a mensagem.
* @param {string} sessionId - Identificador da sessão.
* @param {object}string} interactivemediaUri - Objeto com configuraçãoURL da listamídia interativa.a ser enviada.
*/
const payload: SendMessageDto = {
agentName: 'Atendente João'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
- 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: '1'opcao_1',
title: 'Suporte Técnico',
description: 'AjudaProblemas com problemasprodutos técnicos'ou serviços'
},
{
id: '2'opcao_2',
title: 'Vendas',
description: 'Informações sobre produtos'
},
{
id: '3'opcao_3',
title: 'Financeiro',
description: 'QuestõesDú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 Localização
- Não implementado.
5.10 Enviar Localização
Não implementado.
5.11 Enviar Endereço
- Não implementado.
5.1211 Solicitação de Localização
- Não implementado.
5.1312 Encaminhar mensagem
- Não implementado.