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 

--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

• Listagem de contatos

import { ContactApi } from '@cirrus/omnichannel_api'

/**
 * @param {string} clientIdentifier - Identificador único da conta.
 * @param {number} page - Página em que a busca se iniciará.
 * @param {number} limit - Limite de itens por página.
 * @param {'asc' | 'desc'} order - Ordem em que os itens serão buscados (crescente ou decrescente).
 * @param {'individual' | 'group'} type - Tipo de contato.
 * @param {'whatsapp' | 'facebook' | 'instagram' | 'telegram'} channelType - Tipo de canal.
 * @param {string} name - Nome do contato a ser buscado.
 * @param {string} contactIdentifier - Contato que identifica um usuário (Número de telefone, token (Telegram), etc).
 * @param {string[]} tagIds - Tags vinculadas ao contato.
 */
export interface GetContactsDto {
    clientIdentifier: string;
    page: number;
    limit: number;
    order?: 'asc' | 'desc';
    type?: 'individual' | 'group';
    channelType?: 'whatsapp' | 'facebook' | 'instagram' | 'telegram';
    name?: string;
    contactIdentifier?: string;
    tagIds?: string[];
}

constructor(private readonly contactApi: ContactApi) {}

const payload: GetContactsDto

await this.contactApi.get(payload)

Endpoint: POST /api/accounts/{clientIdentifier}/contacts

Exemplo de Payload:

{
  "contactIdentifier": "5521988887777",
  "name": "João Silva",
  "channelId": "64cbbd9596429dbccd7841e2",
  "channelType": "whatsapp",
  "type": "individual",
  "platform": "whatsappweb"
}

Resposta:

{
  "_id": "64cbbd9596429dbccd7841e4",
  "contactIdentifier": "5521988887777",
  "name": "João Silva",
  "channelId": "64cbbd9596429dbccd7841e2",
  "channelType": "whatsapp",
  "type": "individual",
  "platform": "whatsappweb",
  "createdAt": "2023-08-03T10:30:00.000Z"
}

1.2 Importação de Grupos

Quando ocorre:

• Quando uma mensagem é recebida em um grupo do WhatsApp
• Durante sincronização de grupos ativos

Webhook WhatsApp Web: POST /api/webhook/whatsappweb/{platformConfigId}/{channelId}

Exemplo de Payload (Grupo):

{
  "type": "GROUP_MESSAGE",
  "from": "5521988887777",
  "fromUserName": "João Silva",
  "to": "5521977776666-group",
  "body": {
    "content": "Olá pessoal!",
    "type": "text"
  },
  "groupInfo": {
    "id": "5521977776666-group",
    "name": "Grupo de Vendas",
    "participants": ["5521988887777", "5521955554444"]
  }
}

---

2. Mensagens Individuais

2.1 Envio de Mensagem de Texto

Endpoint: POST /api/message/send

WhatsApp Web:

{
  "sessionId": "64cbbd9596429dbccd7841e5",
  "text": "Olá! Como posso ajudá-lo?",
  "agentName": "Atendente Maria"
}

D360:

{
  "sessionId": "64cbbd9596429dbccd7841e5",
  "text": "Olá! Como posso ajudá-lo?",
  "agentName": "Atendente Maria"
}

Resposta:

{
  "sessionId": "64cbbd9596429dbccd7841e5",
  "messageId": "wamid.HBgNNTUyMTk4ODg4Nzc3NxUCABIYFjNBMDJCMEE2RkY4QzRBOUNCNzAyRjAA"
}

2.2 Envio de Mensagem de Áudio

Endpoint: POST /api/message/send

WhatsApp Web:

{
  "sessionId": "64cbbd9596429dbccd7841e5",
  "mediaUri": "https://s3.amazonaws.com/bucket/audio.mp3",
  "agentName": "Atendente Maria"
}

D360:

{
  "sessionId": "64cbbd9596429dbccd7841e5",
  "mediaUri": "https://s3.amazonaws.com/bucket/audio.ogg",
  "agentName": "Atendente Maria"
}

2.3 Envio de Mensagem de Imagem

Endpoint: POST /api/message/send

WhatsApp Web:

{
  "sessionId": "64cbbd9596429dbccd7841e5",
  "mediaUri": "https://s3.amazonaws.com/bucket/imagem.jpg",
  "text": "Confira esta imagem!",
  "agentName": "Atendente Maria"
}

D360:

{
  "sessionId": "64cbbd9596429dbccd7841e5",
  "mediaUri": "https://s3.amazonaws.com/bucket/imagem.png",
  "text": "Confira esta imagem!",
  "agentName": "Atendente Maria"
}

2.4 Envio de Mensagem de Vídeo

Endpoint: POST /api/message/send

WhatsApp Web:

{
  "sessionId": "64cbbd9596429dbccd7841e5",
  "mediaUri": "https://s3.amazonaws.com/bucket/video.mp4",
  "text": "Vídeo explicativo",
  "agentName": "Atendente Maria"
}

D360:

{
  "sessionId": "64cbbd9596429dbccd7841e5",
  "mediaUri": "https://s3.amazonaws.com/bucket/video.mp4",
  "text": "Vídeo explicativo",
  "agentName": "Atendente Maria"
}

2.5 Envio de Mensagem de Documento

Endpoint: POST /api/message/send

WhatsApp Web:

{
  "sessionId": "64cbbd9596429dbccd7841e5",
  "mediaUri": "https://s3.amazonaws.com/bucket/documento.pdf",
  "agentName": "Atendente Maria"
}

D360:

{
  "sessionId": "64cbbd9596429dbccd7841e5",
  "mediaUri": "https://s3.amazonaws.com/bucket/documento.pdf",
  "agentName": "Atendente Maria"
}

2.6 Envio de Mensagem com Sticker

Endpoint: POST /api/message/send

WhatsApp Web:

{
  "sessionId": "64cbbd9596429dbccd7841e5",
  "mediaUri": "https://s3.amazonaws.com/bucket/sticker.webp",
  "agentName": "Atendente Maria"
}

D360:

{
  "sessionId": "64cbbd9596429dbccd7841e5",
  "mediaUri": "https://s3.amazonaws.com/bucket/sticker.webp",
  "agentName": "Atendente Maria"
}

2.7 Envio de Mensagem de Contatos

Endpoint: POST /api/message/send

D360 (Suporte nativo):

{
  "sessionId": "64cbbd9596429dbccd7841e5",
  "interactive": {
    "type": "contacts",
    "contacts": [
      {
        "name": {
          "first_name": "João",
          "last_name": "Silva",
          "formatted_name": "João Silva"
        },
        "phones": [
          {
            "phone": "5521988887777",
            "type": "WORK",
            "wa_id": "5521988887777"
          }
        ]
      }
    ]
  },
  "agentName": "Atendente Maria"
}

WhatsApp Web (Texto formatado):

{
  "sessionId": "64cbbd9596429dbccd7841e5",
  "text": "Contato:\n👤 João Silva\n📱 (21) 98888-7777",
  "agentName": "Atendente Maria"
}

---

3. Mensagens de Grupo

3.1 Envio de Mensagem de Texto em Grupo

Endpoint: POST /api/message

WhatsApp Web:

{
  "recipientNumber": "5521977776666-group",
  "text": "Olá pessoal do grupo!",
  "isGroupMesssage": true
}

3.2 Envio de Mensagem de Áudio em Grupo

Endpoint: POST /api/message

WhatsApp Web:

{
  "recipientNumber": "5521977776666-group",
  "mediaUri": "https://s3.amazonaws.com/bucket/audio.mp3",
  "isGroupMesssage": true
}

3.3 Envio de Mensagem de Imagem em Grupo

Endpoint: POST /api/message

WhatsApp Web:

{
  "recipientNumber": "5521977776666-group",
  "mediaUri": "https://s3.amazonaws.com/bucket/imagem.jpg",
  "text": "Imagem para o grupo",
  "isGroupMesssage": true
}

3.4 Envio de Mensagem de Vídeo em Grupo

Endpoint: POST /api/message

WhatsApp Web:

{
  "recipientNumber": "5521977776666-group",
  "mediaUri": "https://s3.amazonaws.com/bucket/video.mp4",
  "text": "Vídeo para o grupo",
  "isGroupMesssage": true
}

3.5 Envio de Mensagem de Documento em Grupo

Endpoint: POST /api/message

WhatsApp Web:

{
  "recipientNumber": "5521977776666-group",
  "mediaUri": "https://s3.amazonaws.com/bucket/documento.pdf",
  "isGroupMesssage": true
}

3.6 Envio de Mensagem com Sticker em Grupo

Endpoint: POST /api/message

WhatsApp Web:

{
  "recipientNumber": "5521977776666-group",
  "mediaUri": "https://s3.amazonaws.com/bucket/sticker.webp",
  "isGroupMesssage": true
}

3.7 Envio de Mensagem de Contatos em Grupo

Endpoint: POST /api/message

WhatsApp Web:

{
  "recipientNumber": "5521977776666-group",
  "text": "Contato do suporte:\n👤 Maria Atendente\n📱 (21) 99999-8888",
  "isGroupMesssage": true
}

---

4. Recursos Adicionais de Mensagem

4.1 Indicador de "Digitando"

WhatsApp Web:

• Funcionalidade automática do WhatsApp Web
• Não requer chamada específica da API

D360:

• Não suportado nativamente
• Pode ser simulado com delay entre mensagens

4.2 Marcar Mensagem como Lida

Funcionalidade automática:

• WhatsApp Web: Marca automaticamente como lida quando a mensagem é processada
• D360: Status de leitura é enviado via webhook

Webhook de Status (D360):

{
  "statuses": [
    {
      "id": "wamid.HBgNNTUyMTk4ODg4Nzc3NxUCABIYFjNBMDJCMEE2RkY4QzRBOUNCNzAyRjAA",
      "status": "read",
      "timestamp": "1659518400",
      "recipient_id": "5521988887777"
    }
  ]
}

4.3 Responder Mensagem (Quote)

Endpoint: POST /api/message/send

WhatsApp Web:

{
  "sessionId": "64cbbd9596429dbccd7841e5",
  "text": "Respondendo à sua pergunta...",
  "quotedMessage": {
    "id": "message_id_original",
    "message": "Qual o horário de funcionamento?"
  },
  "agentName": "Atendente Maria"
}

D360:

{
  "sessionId": "64cbbd9596429dbccd7841e5",
  "text": "Respondendo à sua pergunta...",
  "quotedMessage": {
    "id": "wamid.HBgNNTUyMTk4ODg4Nzc3NxUCABIYFjNBMDJCMEE2RkY4QzRBOUNCNzAyRjAA"
  },
  "agentName": "Atendente Maria"
}

4.4 Mensagens Interativas (D360)

Botões:

{
  "sessionId": "64cbbd9596429dbccd7841e5",
  "interactive": {
    "type": "button",
    "body": {
      "text": "Escolha uma opção:"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "opcao_1",
            "title": "Opção 1"
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "opcao_2",
            "title": "Opção 2"
          }
        }
      ]
    }
  },
  "agentName": "Atendente Maria"
}

Lista:

{
  "sessionId": "64cbbd9596429dbccd7841e5",
  "interactive": {
    "type": "list",
    "body": {
      "text": "Selecione um departamento:"
    },
    "action": {
      "button": "Ver opções",
      "sections": [
        {
          "title": "Departamentos",
          "rows": [
            {
              "id": "vendas",
              "title": "Vendas",
              "description": "Equipe de vendas"
            },
            {
              "id": "suporte",
              "title": "Suporte",
              "description": "Suporte técnico"
            }
          ]
        }
      ]
    }
  },
  "agentName": "Atendente Maria"
}

4.5 Templates (D360)

Iniciar Conversa com Template:

Endpoint: POST /api/message/start/d360

{
  "to": "5521988887777",
  "userName": "João Silva",
  "companyName": "Alterdata",
  "template": "contato_cliente",
  "templateVariables": ["João Silva", "Alterdata"]
}

4.6 Deletar Mensagem

Endpoint: DELETE /api/message/{messageId}?senderId={senderId}&channelSlug={channelSlug}

WhatsApp Web:

DELETE /api/message/message_id_123?senderId=5521977776666&channelSlug=whatsappweb

D360:

DELETE /api/message/wamid.HBgNNTUyMTk4ODg4Nzc3NxUCABIYFjNBMDJCMEE2RkY4QzRBOUNCNzAyRjAA?senderId=5521977776666&channelSlug=d360

---

5. Webhooks de Recebimento

5.1 Webhook WhatsApp Web

URL: POST /api/webhook/whatsappweb/{platformConfigId}/{channelId}

Exemplo de Mensagem Recebida:

{
  "type": "MESSAGE",
  "from": "5521988887777",
  "fromUserName": "João Silva",
  "to": "web5521977776666",
  "body": {
    "content": "Olá, preciso de ajuda",
    "type": "text"
  },
  "timestamp": 1659518400
}

5.2 Webhook D360

URL: POST /api/webhook/360dialog/{platformConfigId}/{channelId}

Exemplo de Mensagem Recebida:

{
  "messages": [
    {
      "id": "wamid.HBgNNTUyMTk4ODg4Nzc3NxUCABIYFjNBMDJCMEE2RkY4QzRBOUNCNzAyRjAA",
      "from": "5521988887777",
      "type": "text",
      "timestamp": "1659518400",
      "text": {
        "body": "Olá, preciso de ajuda"
      }
    }
  ],
  "contacts": [
    {
      "profile": {
        "name": "João Silva"
      },
      "wa_id": "5521988887777"
    }
  ]
}

---

6. Gestão de Sessões

6.1 Obter Sessão

Endpoint: GET /api/session/{sessionId}

Resposta:

{
  "_id": "64cbbd9596429dbccd7841e5",
  "client": {
    "name": "João Silva",
    "providerId": "5521988887777"
  },
  "type": "whatsappweb",
  "status": "active",
  "createdAt": "2023-08-03T10:30:00.000Z"
}

6.2 Transferir Sessão

Endpoint: POST /api/session/transfer/{sessionId}

{
  "params": {
    "platformSlug": "crm",
    "agentId": "agent_123"
  },
  "transferMessage": "Transferindo para o especialista..."
}

6.3 Finalizar Sessão

Endpoint: DELETE /api/session/finish/{sessionId}

Resposta:

{
  "message": "Session finished successfully",
  "sessionId": "64cbbd9596429dbccd7841e5"
}

---

7. Diferenças entre WhatsApp Web e D360

Funcionalidade	WhatsApp Web	D360
Mensagens de Texto	✅	✅
Mídia (Imagem/Vídeo/Áudio)	✅	✅
Documentos	✅	✅
Stickers	✅	✅
Mensagens de Grupo	✅	❌
Templates	❌	✅
Botões Interativos	❌	✅
Listas Interativas	❌	✅
Contatos Estruturados	❌	✅
Indicador de Digitando	✅	❌
Deletar Mensagens	✅	❌
Validação de Números	✅	❌
Foto de Perfil	✅	❌

---

8. Códigos de Erro Comuns

8.1 WhatsApp Web

• 404: Número não encontrado no WhatsApp Web
• 400: Conexão com WhatsApp Web fechada
• 400: Número inválido

8.2 D360

• 401: Token de API inválido
• 400: Formato de mensagem inválido
• 429: Limite de taxa excedido
• 500: Erro interno do D360

---

9. Configuração de Webhooks

9.1 WhatsApp Web

GET /{clientNumber}/setWebhook?url={webhookUrl}

9.2 D360

POST /configs/webhook
{
  "url": "https://seu-dominio.com/api/webhook/360dialog/{platformConfigId}/{channelId}"
}

---

10. Monitoramento e Logs

10.1 Status de Conexão

WhatsApp Web:

GET /{clientNumber}/status

Resposta:

{
  "status": "open",
  "qr": null,
  "battery": 85,
  "plugged": true
}

10.2 Validação de Número

WhatsApp Web:

GET /{providerId}/validate/{contact}

Resposta:

{
  "input": "5521988887777",
  "isValid": true,
  "jid": "5521988887777@c.us",
  "lid": "5521988887777@lid",
  "phone": "5521988887777"
}

---

Esta documentação cobre todas as funcionalidades principais das integrações WhatsApp Web e D360 disponíveis no sistema Omnichannel. Para implementações específicas ou dúvidas técnicas, consulte o código-fonte ou entre em contato com a equipe de desenvolvimento.