[Open Beta] Como utilizar o Envio Direto (Direct Send) para Mensagens de Utilidade via API Growth

1. Contexto
2. O que é o Direct Send e quais os benefícios?
3. Como ativar o Direct send
4. Regras de Conteúdo, Limites e Validações
5. Como realizar os disparos via API
6. Respostas e Diagnóstico de Erros

Contexto

O recurso de Envio Direto (Direct Send) é uma funcionalidade em versão Beta do WhatsApp Cloud API integrada ao Blip. Ele permite o disparo de mensagens ativas da categoria Utilidade (Utility) sem a necessidade de criar e aprovar modelos de mensagens (Message Templates / HSM) previamente no Gerenciador de Negócios da Meta.

Este artigo orienta como solicitar a ativação do recurso, às regras e limites de conteúdo exigidos pela Meta e como estruturar suas requisições via API do Blip utilizando os modelos de disparo.
 

O que é o Direct Send e quais os benefícios?

O Direct Send simplifica a integração de mensagens transacionais e operacionais, eliminando o tempo de espera para aprovação manual de templates.

• Aprovação Automática: Os modelos são gerados e validados automaticamente pela Meta no momento da primeira utilização.

• Reutilização Inteligente: O sistema identifica mensagens com a mesma estrutura e reaproveita automaticamente os modelos já gerados.

• Envio Imediato: Redução drástica do time-to-market para novas comunicações ativas.

• Garantia de Categoria: Evita a reclassificação indevida de mensagens transacionais para a categoria de Marketing.
   

Como ativar o Direct send

A ativação envolve dois processos distintos e sequenciais. Primeiro você garante a elegibilidade na Meta; depois, solicita a liberação da funcionalidade dentro do Portal Blip.

Passo 1: Habilitar no Gerenciador da Meta

• Acesse o WhatsApp Manager e verifique a disponibilidade do Direct send para a sua conta. Um banner indicará se a sua conta está elegível.

• Se a sua conta ainda não estiver elegível, você poderá manifestar interesse através do formulário disponibilizado pela Meta.

• A elegibilidade pode exigir a submissão de amostras de mensagens de utilidade para revisão da Meta, garantindo o alinhamento com as diretrizes da categoria. Assim que aprovado, sua conta ficará elegível no lado da Meta.

Passo 2: Solicitar a liberação na Blip

• Como a funcionalidade está em Beta na Blip, após conseguir a elegibilidade na Meta você deve acionar o seu ponto focal na Blip (CSM ou KAM) e solicitar a liberação do acesso.

• O time da Blip fará a habilitação da funcionalidade na sua conta, e então você poderá começar a utilizar o Direct send no Portal.

  Resumo: Elegibilidade na Meta → Solicitação ao seu CSM/KAM na Blip → Liberação do acesso → Uso da funcionalidade.

Regras de Conteúdo, Limites e Validações

Todas as requisições enviadas passam por validações técnicas rigorosas. Requisições fora dos padrões serão rejeitadas com erro 400 Bad Request.
 

1. Categoria Permitida

Apenas a categoria utility é aceita no Direct Send API. É obrigatório declarar "category": "utility" no parâmetro da mensagem.

2. Limites de Caracteres por Componente

3. Configuração de TTL (Time To Live)

O parâmetro ttl_seconds define o tempo máximo que o WhatsApp tentará entregar a mensagem caso o celular do destinatário esteja sem rede:

• Valor Mínimo: 30 segundos

• Valor Máximo: 43200 segundos (12 horas)

• Valor Padrão (se omitido): 2592000 segundos (30 dias)

Conversão Rapida:

30s = 30     │ 5min = 300    │ 10min = 600   │ 30min = 1800
1h = 3600    │ 6h = 21600    │ 12h = 43200

Recomendação: Para notificações de alta urgência (ex: códigos de acesso ou alertas imediatos), utilize um TTL entre 300 e 600 segundos (5 a 10 minutos).

Como realizar os disparos via API

• Método HTTP: POST

• URL Base: https://{contract_id}.http.msging.net/commands

• Headers Padrão:

• Content-Type: application/json ou application/vnd.iris.activecampaign.full-campaign+json

• Authorization: Key {SUA_CHAVE_API_DO_BOT}

Regra de Destinatário (campaignType):

• Para envio Individual ("campaignType": "Individual"), utilize o campo audience (objeto no singular).

• Para envio em Lote ("campaignType": "Batch"), utilize o campo audiences (array no plural).

Para envios usando estrutura de Router, o campo masterState deve ser usado, caso contrário deve ser removido.
Exemplo: "masterState": "identificador@msging.net"
 

Abordagem 1: Disparo via (/campaign/full)

Recomendado para integrações onde a criação da campanha e o disparo acontecem em uma única chamada.

Exemplo 1.1:  Texto Simples (Individual)

{
  "id": "{{$guid}}",
  "to": "postmaster@activecampaign.msging.net",
  "method": "set",
  "uri": "/campaign/full",
  "resource": {
    "audience": {
      "recipient": "+5511999999999",
      "messageParams": {"1": "luiz"}
    },
    "campaign": {
      "name": "nome-da-campanha",
      "campaignType": "Individual",
      "flowId": "flow-id",
      "stateId": "state-id",
    "masterState": "identificador@msging.net",
      "masterState": "",
      "channelType": "WhatsApp"
    },
    "message": {
      "messageContent": "{'type':'text','text':{'body':'Mensagem {{1}}'},'category':'utility','ttl_seconds':600,'category':'utility'}",
      "messageParams": ["1"],
      "channelType": "WhatsApp",
      "messageTemplateLanguage": "pt_BR"
    }
  },
  "type": "application/vnd.iris.activecampaign.full-campaign+json"
}

Exemplo 1.2: Botão Interativo CTA URL (Em Lote / Batch)

{
  "id": "{{$guid}}",
  "to": "postmaster@activecampaign.msging.net",
  "method": "set",
  "uri": "/campaign/full",
  "type": "application/vnd.iris.activecampaign.full-campaign+json",
  "resource": {
    "audiences": [
      {
        "recipient": "+5511999999999",
        "messageParams": { "1": "Maria" }
      },
      {
        "recipient": "+5511988888888",
        "messageParams": { "1": "Carlos" }
      }
    ],
    "campaign": {
      "name": "direct-send-cta-batch",
      "campaignType": "Batch",
      "flowId": "{{FLOW_ID}}",
      "stateId": "{{STATE_ID}}",
      "channelType": "WhatsApp"
    },
    "message": {
      "messageParams": ["1"],
      "messageContent": "{'type':'interactive','interactive':{'type':'cta_url','header':{'type':'text','text':'Atualização'},'body':{'text':'Olá {{1}}, confira os detalhes do seu boleto disponível para download.'},'footer':{'text':'Clique no botão abaixo'},'action':{'name':'cta_url','parameters':{'display_text':'Baixar Boleto','url':'https://suaempresa.com.br/boleto'}}},'category':'utility','ttl_seconds':3600}",
      "channelType": "WhatsApp",
      "messageTemplateLanguage": "pt_BR"
    }
  }
}

Exemplo 1.3: Botões de Resposta Rápida (Em Lote / Batch)

{
  "id": "{{$guid}}",
  "to": "postmaster@activecampaign.msging.net",
  "method": "set",
  "uri": "/campaign/full",
  "type": "application/vnd.iris.activecampaign.full-campaign+json",
  "resource": {
    "audiences": [
      {
        "recipient": "+5511999999999",
        "messageParams": { "1": "Lucas" }
      }
    ],
    "campaign": {
      "name": "direct-send-reply-buttons",
      "campaignType": "Batch",
      "flowId": "{{FLOW_ID}}",
      "stateId": "{{STATE_ID}}",
      "channelType": "WhatsApp"
    },
    "message": {
      "messageParams": ["1"],
      "messageContent": "{'type':'interactive','interactive':{'type':'button','header':{'type':'text','text':'Confirmação'},'body':{'text':'Olá {{1}}, você confirma seu agendamento para amanhã?'},'footer':{'text':'Responda selecionando uma das opções abaixo'},'action':{'buttons':[{'type':'reply','reply':{'id':'btn_sim','title':'Confirmar'}},{'type':'reply','reply':{'id':'btn_nao','title':'Cancelar'}},{'type':'reply','reply':{'id':'btn_remarcar','title':'Remarcar'}}]}},'category':'utility','ttl_seconds':600}",
      "channelType": "WhatsApp",
      "messageTemplateLanguage": "pt_BR"
    }
  }
}

Exemplo 1.4: V2 — Exemplo de Requisição (/campaign/full/v2)

{
  "id": "{{$guid}}",
  "to": "postmaster@activecampaign.msging.net",
  "method": "set",
  "uri": "/campaign/full/v2",
  "type": "application/vnd.iris.activecampaign.full-campaign+json",
  "resource": {
    "campaign": {
      "name": "direct-send-atomic-v2",
      "campaignType": "Batch",
      "flowId": "{{FLOW_ID}}",
      "stateId": "{{STATE_ID}}",
      "channelType": "WhatsApp"
    },
    "audiences": [
      {
        "recipient": "+5511999999999",
        "recipientType": "PhoneNumber"
      }
    ],
    "message": {
      "messageTemplateLanguage": "pt_BR",
      "channelType": "WhatsApp",
      "messageContent": "{'type':'text','text':{'body':'Mensagem via Direct Send utilizando a versão Atomic v2.'},'category':'utility'}"
    },
    "dispatch": true
  }
}

Abordagem 2: Disparo Faseado V2 

A abordagem Faseada V2 é recomendada para arquiteturas onde a criação da campanha, a vinculação de contatos e a ordem final de disparo ocorrem em etapas diferidas ou microsserviços distintos.

Passo 1: Criar a Campanha (POST /campaign/v2)

Nesta etapa, você define o nome, o fluxo e o conteúdo da mensagem.

{
  "id": "{{$guid}}",
  "to": "postmaster@activecampaign.msging.net",
  "method": "set",
  "uri": "/campaign/v2",
  "type": "application/vnd.iris.activecampaign.campaign-dynamic+json",
  "resource": {
    "campaign": {
      "name": "direct-send-phased-v2-campaign",
      "campaignType": "Individual",
      "flowId": "{{FLOW_ID}}",
      "stateId": "{{STATE_ID}}",
      "channelType": "WhatsApp"
    },
    "message": {
      "messageContent": "{'type':'text','text':{'body':'Olá! Sua solicitação de atendimento foi registrada.'},'category':'utility'}",
      "channelType": "WhatsApp",
      "messageTemplateLanguage": "pt_BR"
    }
  }
}

Guarde o ID da campanha retornado na resposta desta requisição para utilizar nas etapas 2 e 3.

Passo 2: Vincular o Público (POST /audiences/{CAMPAIGN_ID})

Vincule o destinatário à campanha criada anteriormente substituindo {CAMPAIGN_ID} pelo ID obtido no Passo 1.

{
  "id": "{{$guid}}",
  "to": "postmaster@activecampaign.msging.net",
  "method": "set",
  "uri": "/audiences/{{CAMPAIGN_ID}}",
  "type": "application/vnd.iris.activecampaign.audience+json",
  "resource": {
    "recipient": "+5511999999999"
  }
}

Passo 3: Ordem de Disparo (POST /dispatch/v2)

Com a campanha e o público cadastrados, ordene a execução do envio.

{
  "id": "{{$guid}}",
  "to": "postmaster@activecampaign.msging.net",
  "method": "set",
  "uri": "/dispatch/v2",
  "type": "application/vnd.iris.activecampaign.campaign+json",
  "resource": {
    "id": "{{CAMPAIGN_ID}}"
  }
}

Respostas e Diagnóstico de Erros

Resposta de Sucesso (200 OK)

{
  "type": "application/vnd.iris.activecampaign.campaign+json",
  "status": "success",
  "resource": {
    "id": "cffa9ba4-afe8-4402-ad25-fd9d2827890a"
  }
}

Principais Erros e Soluções (400 Bad Request)

Precisa de mais ajuda? Explore nossos conteúdos na Blip Academy ou Blip Community, assista a tutoriais no nosso canal do YouTube ou tire suas dúvidas em nosso canal de atendimento 😃