> ## Documentation Index > Fetch the complete documentation index at: https://docs.robbu.global/llms.txt > Use this file to discover all available pages before exploring further. # Direct Message API > Envio de mensagens transacionais via E-mail, SMS, WhatsApp e RCS usando a infraestrutura do Maestro. ## 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/](https://api.common.maestro.robbu.global/) #### Envio de E-mail ```http theme={null} POST /v1/directmessage/email ``` Request Body: ```json theme={null} { "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 ```http theme={null} POST /v1/directmessage/whatsapp ``` Request Body: ```json theme={null} { "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 ```http theme={null} POST /v1/directmessage/sms ``` Request Body: ```json theme={null} { "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 ```http theme={null} POST /v1/directmessage/rcs ``` Request Body: ```json theme={null} { "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: ```json theme={null} "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: ```json theme={null} { "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. ```json theme={null} { "result": "Mensagem em processamento." } ``` * 400 - Bad Request: O nome informado em `broker` não corresponde a um provedor cadastrado. ```json theme={null} { "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. ```json theme={null} { "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. ```json theme={null} { "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: ```json theme={null} { "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.