Pular para o conteúdo principal

​
Informações Gerais

Versão da API: /v1
Nome da API: Direct Message API
Canais suportados: Envio de mensagens sem campanha — E-mail, SMS e WhatsApp

​
Visão Geral

A Direct Message API permite o disparo de mensagens unitárias (fora do ciclo de campanhas) utilizando os mesmos recursos do Maestro, incluindo:
  • Motor de regras de validação de mensagem
  • Serviços e brokers configurados no Maestro
Este serviço é ideal para integrações automatizadas, como envio de confirmações, alertas, autenticações e notificações em tempo real.

​
Integração

​
Autenticação

O token de autenticação é obtido pela tela de configurações da Empresa no Maestro. Vá em Configurações > Empresa > Integração Gere um novo token ou renove o existente.
⚠️ Atenção: Ao clicar em “Renovar token”, o token anterior será invalidado.
Este token deve ser passado como HEADER nas chamadas de API como Bearer {token}

​
Endpoints

URL Produção:
Base: https://api.common.maestro.robbu.global/

​
Envio de E-mail

POST /v1/directmessage/email
Request Body: 
{
  "recipient_email": "[email protected]",
  "variable_values": {
    "Var1": "valor1",
    "Var2": "valor2"
  },
  "document_number": "12345678900",
  "contract_code": "CT-98765",
  "template_code": "TEMPLATE_EMAIL_001",
  "segment": "Cartao Credito"
}

​
Envio de WhatsApp

POST /v1/directmessage/whatsapp
Request Body: 
{
  "recipient_number": "5511999998888",
  "whatsapp_sender_number": "5500000000000",
  "variables": {
    "header_key": "Var3",
    "header_value": "João Silva",
    "body": {
      "Var1": "CDI-00987",
      "Var2": "R. Padre Anchieta, 115. Centro."
    }
  },
  "document_number": "12345678900",
  "contract_code": "CT-000123",
  "template_code": "TEMPLATE_WPP_003",
  "segment": "Cartao Credito"
}

​
Envio de SMS

POST /v1/directmessage/sms
Request Body: 
{
  "recipient_number": "5511999998888",
  "variable_values": {
    "Var1": "123456",
    "Var2": "João"
  },
  "document_number": "12345678900",
  "contract_code": "CT-00987",
  "template_code": "TEMPLATE_SMS_002",
  "segment": "Cartao Credito"
}

​
Variáveis de Template

E-mail e SMS
Utilize o campo variable_values para informar variáveis dinâmicas conforme o template configurado no Maestro: 
"variable_values": {
  "Var1": "João Silva",
  "Var2": "CDI-00987"
}

​
Respostas

CódigoDescrição
200 - OKMensagem validada, mas não enviada — Não há serviço/broker configurado para o canal
202 - AcceptedMensagem em processamento — Passou pelas validações e foi enfileirada para envio.
401 - UnauthorizedFalha na autenticação.
422 - UnprocessableEntityErros de validação — Campos obrigatórios não preenchidos ou dados inválidos.
409 - ConflictErros de validação do Motor de Regras — Lista os motivos de bloqueio.
  • 200 - OK:
{
  "result": "Mensagem validada, mas não enviada. Não há serviço de envio de mensagens configurado para esse canal."
}
  • 202 - Accepted: Indica que a mensagem passou pelas validações do motor de regras e foi enfileirada para ser enviada.
{
  "result": "Mensagem em processamento."
}
  • 401 - Unauthorized: Falha na autenticação Não há response
  • 422 - UnprocessableEntity: Indica que campos da request são obrigatórios e não foram preenchidos, ou contém dados inválidos. 
 {
      "message": "Não foi possível enviar a mensagem.",
      "errors": {
        "contract_code": [
          "O código do contrato é obrigatório."
        ]
      },
      "record_errors": [],
      "conflicts": [],
      "requestId": "00-6b732c3ed78165728d77ccd4487fc564-07c6e0cee7e9335d-00"
    }
  • 409 - Conflict: Alista todos os erros de validação caso a mensagem seja bloqueada pelo Motor de Regras. Nesse exemplo, o destinatário de email foi barrado por duas regras do motor.
{
      "message": "Erro na validação do Motor de Regras.",
      "errors": {},
      "record_errors": [],
      "conflicts": [
        "Domínio de e-mail bloqueado na Lista de Restrição",
        "E-mail bloqueado na Lista de Restrição"
      ],
      "requestId": "00-80016a94505f232820c73054f2ee1fa2-12c5228b9f317e12-00"
    }

​
Callback

Você pode adicionar uma URL de Callback e também campos customizados para que sejam enviados nessa URL de Callback a partir do disparo da API Direct Message. Para isso, você deve adicionar o objeto callback_details, conforme exemplo abaixo: 
{
  "recipient_number": "5511999998888",
  "variable_values": {
    "Var1": "123456",
    "Var2": "João"
  },
  "document_number": "12345678900",
  "contract_code": "CT-00987",
  "template_code": "TEMPLATE_SMS_002",
  "segment": "Cartao Credito"
  "callback_details": {
    "url": "https://minhaurl.com.br/meu_endpoint_de_callback",
    "custom_fields": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string",
      //...
    }
  }
}

​
Boas Práticas

Valide previamente os templates e variáveis definidos no Maestro. Sempre trate erros 401 e 403 com lógica de fallback ou renovação de token. Implemente monitoramento e logs para mensurar falhas por canal e acionar novas tentativas ou alertas.

​
FAQ

Não. É obrigatório vincular um template previamente configurado.
A API retornará 200 - OK, mas informando que não há serviço de envio para aquele canal.
Acesse Configurações > Empresa e gere um novo token.
⚠️ Atenção: o token anterior será revogado.
O envio é feito em tempo real, dependendo da disponibilidade do canal.