Direct Message API - Robbu Docs

Informações Gerais

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

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": "usuario@dominio.com",
  "variable_values": {
    "Var1": "valor1",
    "Var2": "valor2"
  },
  "document_number": "12345678900",
  "contract_code": "CT-98765",
  "template_code": "E001",
  "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": "W001",
  "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": "S001",
  "segment": "Cartao Credito",
  "flash_sms": false,
  "broker": "Pontal"
}

⚠️ Atenção: O recurso de SMS Flash também deve ser contratado/habilitado no provedor da Pontal, não apenas habilitado no Maestro.

Envio de RCS

POST /v1/directmessage/rcs

Request Body:

{
  "recipient_number": "5511999998888",
  "variable_values": {
    "Var1": "123456",
    "Var2": "João"
  },
  "document_number": "12345678900",
  "contract_code": "CT-00987",
  "template_code": "R001",
  "segment": "Cartao Credito",
  "broker": "Pontal"
}

Campo `broker` (opcional — apenas SMS e RCS)

O campo broker define qual provedor fará o disparo, informando o nome do provedor exatamente como cadastrado no Maestro (ex.: Pontal, Classe A). O valor é sensível a maiúsculas/minúsculas e a espaços.

Omitido ou vazio → mantém o roteamento por segmento atual, conforme configurado na Integração com Provedores.
Preenchido e válido → dispara pelo provedor indicado.
Nome inválido → 400 - Bad Request.
Demais canais (E-mail, WhatsApp) ignoram o campo.

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ódigo	Descrição
200 - OK	Mensagem validada, mas não enviada — Não há serviço/broker configurado para o canal
202 - Accepted	Mensagem em processamento — Passou pelas validações e foi enfileirada para envio.
400 - Bad Request	Nome de `broker` inválido — não corresponde a um provedor cadastrado.
401 - Unauthorized	Falha na autenticação.
422 - UnprocessableEntity	Erros de validação — Campos obrigatórios não preenchidos ou dados inválidos.
409 - Conflict	Erros 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."
}

400 - Bad Request: O nome informado em broker não corresponde a um provedor cadastrado.

{
  "result": "Broker informado é inválido."
}

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

Posso enviar mensagens sem configurar um template no Maestro?

Não. É obrigatório vincular um template previamente configurado.

E se o canal não estiver configurado?

A API retornará 200 - OK, mas informando que não há serviço de envio para aquele canal.

Como renovar o token?

Acesse Configurações > Empresa e gere um novo token.
⚠️ Atenção: o token anterior será revogado.

Qual o tempo de processamento da mensagem?

O envio é feito em tempo real, dependendo da disponibilidade do canal.

​Informações Gerais

​Visão Geral

​Integração

​Autenticação

​Endpoints

​Envio de E-mail

​Envio de WhatsApp

​Envio de SMS

​Envio de RCS

​Campo broker (opcional — apenas SMS e RCS)

​Variáveis de Template

​Respostas

​Callback

​Boas Práticas

​FAQ

Informações Gerais

Visão Geral

Integração

Autenticação

Endpoints

Envio de E-mail

Envio de WhatsApp

Envio de SMS

Envio de RCS

Campo `broker` (opcional — apenas SMS e RCS)

Variáveis de Template

Respostas

Callback

Boas Práticas

FAQ