Introdução

A API de integração do sistema Nexus é um web service REST para envio de mensagens SMS e WhatsApp em escala.

WhatsApp - Arquitetura de Disparo

O sistema de disparo de WhatsApp do Nexus utiliza uma arquitetura distribuída baseada em Business Managers (BMs) e Tipos de Template.

Business Manager (BM)

O Business Manager é a entidade raiz que agrupa:

• WABAs (WhatsApp Business Accounts)
• Números de telefone para envio
• Templates aprovados pela Meta

Cada número possui um limite de vazão (messaging limit) que determina quantas mensagens podem ser enviadas em 24 horas.

Tipo de Template

O Tipo de Template é um agrupador lógico que permite vincular diferentes templates dentro de uma mesma BM em uma única categoria funcional. Ao realizar um disparo para um "Tipo", o sistema distribuirá as mensagens entre todos os templates daquela categoria que estiverem associados ao BM escolhido

Na interface web do Nexus, você pode criar um Tipo de Template e associar templates de múltiplos BMs. Por exemplo:

[BM Selecionado: "BM1"]
└── Tipo de Template: "Cobrança"
		├── Template "cobranca_v1" (BM1,BM2)
		├── Template "cobranca_v2" (BM1,BM3)
		└── Template "cobranca_v3" (BM1,BM3)

Ao efetuar o disparo com a BM1 selecionada, serão usados os templates associados a ela.

Vantagens:

Fluxo Recomendado de Integração

1. Verificar vazão disponível

Antes de enviar mensagens, consulte a vazão disponível:

GET /whatsapp/businesses/

Retorna os BMs disponíveis com a vazão (output) calculada por tipo de template.

Resposta:

[
  {
    "id": 1,
    "name": "Nome do BM",
    "template_types": [
      {
        "id": 1,
        "name": "Pedido Aprovado",
        "output": 800,
        "data (Em  implementação)": "Olá {{1}}! Seu pedido {{2}} foi aprovado e a previsão de entrega é para o dia {{3}}.",
        "example (Em  implementação)": "Olá João! Seu pedido 123456 foi aprovado e a previsão de entrega é para o dia 01/01/2022.",
        "variables(Em  implementação)": [
          [
            {
              "name": "nome",
              "index": 0
            },
            {
              "name": "pedido",
              "index": 1
            },
            {
              "name": "data",
              "index": 2
            }
          ]
        ]
      }
    ]
  }
]

O campo output indica quantas mensagens podem ser enviadas naquele momento para aquele tipo de template.

2. Enviar mensagens

POST /whatsapp/messages/

Informe o template_type_id para que o sistema distribua automaticamente entre os templates e números disponíveis.

Request:

{
  "business_id": 2836,
  "template_type_id": 3,
  "campaign_id": 1930,
  "queue_id": 8,
  "bot_id": 3,
  "max_retries": 3,
  "retry_interval": 90,
  "contacts": [
    {
      "phone_number": "5511999999999",
      "document": "12345678900",
      "contract": "001234/2024",
      "template_variables": [
        "João",
        "12345678900"
      ],
      "data": {
        "referencia": "123456",
        "nome": "João",
        "idade": "30"
      }
    }
  ]
}

Distribuição Automática

Quando você envia mensagens usando template_type_id, o sistema:

1. Identifica todos os templates ativos daquele tipo em todos os BMs
2. Verifica a vazão disponível de cada número
3. Distribui as mensagens em round-robin entre os números
4. Failover: Se um template for pausado, as próximas mensagens usam os templates restantes

Exemplo Prático

Cenário: Você tem uma BM que possui 3 números ativos, alocado em templates do tipo "Cobrança":

Vazão total: 3.000 msg/hora

Se algum número numero da BM for pausado pela Meta:

Vazão total: 2.000 msg/hora (sem interrupção do serviço)

SMS

Para envio de SMS, utilize o endpoint:

POST /sms/messages/

[
  {
    "message": "Olá, tudo bem?",
    "phone": "5511999999999",
    "url_callback_dlr": "https://url-de-callback.com",
    "url_callback_mo": "https://url-de-resposta.com",
    "reference": "123456",
    "campaign_id": 433,
    "name": "João",
    "cpf": "12345678900"
  }
]

Os callbacks de status (DLR) e resposta (MO) devem ser configurados no corpo da requisição:

Autenticação

Todas as requisições devem incluir o header de autenticação:

x-api-key-id: seu_token_aqui

O token é obtido no painel administrativo do Nexus.