[Open Beta] How to Use Direct Send for Utility Messages via the Growth API

1. Context
2. What is Direct Send and what are its benefits?
3. How to activate Direct Send
4. Content Rules, Limits, and Validations
5. How to send messages via API
6. Responses and Error Diagnosis

Context

The Direct Send feature is a Beta functionality of the WhatsApp Cloud API integrated with Blip. It allows active messages in the Utility category to be sent without the need to create and approve message templates (Message Templates / HSM) in advance in Meta Business Manager.

This article explains how to request activation of the feature, the content rules and limits required by Meta, and how to structure your requests via the Blip API using sending models.
 

What is Direct Send and what are its benefits?

Direct Send simplifies the integration of transactional and operational messages, eliminating the wait time for manual template approval.

• Automatic Approval: Templates are automatically generated and validated by Meta at the time of first use.

• Intelligent Reuse: The system identifies messages with the same structure and automatically reuses templates that have already been generated.

• Immediate Sending: Significant reduction in the time-to-market for new active communications.

• Category Assurance: Prevents transactional messages from being improperly reclassified as Marketing.
   

How to activate Direct Send

Activation involves two distinct and sequential processes. First, you ensure eligibility with Meta; then, you request the feature to be enabled in the Blip Portal.

Step 1: Enable it in Meta Manager

• Access WhatsApp Manager and check whether Direct Send is available for your account. A banner will indicate whether your account is eligible.

• If your account is not yet eligible, you can express your interest through the form provided by Meta.

• Eligibility may require submitting samples of utility messages for review by Meta, ensuring alignment with the category guidelines. Once approved, your account will be eligible on Meta’s side.

Step 2: Request enablement in Blip

• Because the feature is in Beta at Blip, after obtaining eligibility from Meta, you must contact your Blip point of contact (CSM or KAM) and request access to be enabled.

• The Blip team will enable the feature for your account, and you will then be able to start using Direct Send in the Portal.

  Summary: Eligibility with Meta → Request to your Blip CSM/KAM → Access enabled → Use of the feature.

Content Rules, Limits, and Validations

All requests sent undergo rigorous technical validation. Requests that do not meet the standards will be rejected with a 400 Bad Request error.
 

1. Allowed Category

Only the utility category is accepted in the Direct Send API. You must declare "category": "utility" in the message parameter.

2. Character Limits by Component

3. TTL (Time To Live) Configuration

The ttl_seconds parameter defines the maximum time WhatsApp will attempt to deliver the message if the recipient’s phone is without network coverage:

• Minimum Value: 30 seconds

• Maximum Value: 43,200 seconds (12 hours)

• Default Value (if omitted): 2,592,000 seconds (30 days)

Quick Conversion:

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

Recommendation: For high-urgency notifications (e.g., access codes or immediate alerts), use a TTL between 300 and 600 seconds (5 to 10 minutes).

How to send messages via API

• HTTP Method: POST

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

• Standard Headers:

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

• Authorization: Key {YOUR_BOT_API_KEY}

Recipient Rule (campaignType):

• For Individual sending ("campaignType": "Individual"), use the audience field (singular object).

• For Batch sending ("campaignType": "Batch"), use the audiences field (plural array).

For sending using a Router structure, the masterState field must be used; otherwise, it must be removed.
Example: "masterState": "identifier@msging.net"
 

Approach 1: Sending via (/campaign/full)

Recommended for integrations where campaign creation and sending occur in a single call.

Example 1.1:  Simple Text (Individual)

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

Example 1.2: Interactive CTA URL Button (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':'Update'},'body':{'text':'Hello {{1}}, check the details of your bill available for download.'},'footer':{'text':'Click the button below'},'action':{'name':'cta_url','parameters':{'display_text':'Download Bill','url':'https://yourcompany.com/bill'}}},'category':'utility','ttl_seconds':3600}",
      "channelType": "WhatsApp",
      "messageTemplateLanguage": "pt_BR"
    }
  }
}

Example 1.3: Quick Reply Buttons (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':'Confirmation'},'body':{'text':'Hello {{1}}, do you confirm your appointment for tomorrow?'},'footer':{'text':'Reply by selecting one of the options below'},'action':{'buttons':[{'type':'reply','reply':{'id':'btn_sim','title':'Confirm'}},{'type':'reply','reply':{'id':'btn_nao','title':'Cancel'}},{'type':'reply','reply':{'id':'btn_remarcar','title':'Reschedule'}}]}},'category':'utility','ttl_seconds':600}",
      "channelType": "WhatsApp",
      "messageTemplateLanguage": "pt_BR"
    }
  }
}

Example 1.4: V2 — Request Example (/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':'Message via Direct Send using Atomic v2.'},'category':'utility'}"
    },
    "dispatch": true
  }
}

Approach 2: Phased Sending V2 

The Phased V2 approach is recommended for architectures where campaign creation, contact association, and final sending execution occur in deferred stages or in separate microservices.

Step 1: Create the Campaign (POST /campaign/v2)

In this step, you define the name, flow, and message content.

{
  "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':'Hello! Your service request has been registered.'},'category':'utility'}",
      "channelType": "WhatsApp",
      "messageTemplateLanguage": "pt_BR"
    }
  }
}

Save the campaign ID returned in the response to this request to use in steps 2 and 3.

Step 2: Link the Audience (POST /audiences/{CAMPAIGN_ID})

Link the recipient to the campaign created earlier by replacing {CAMPAIGN_ID} with the ID obtained in Step 1.

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

Step 3: Send (POST /dispatch/v2)

Once the campaign and audience are registered, initiate the sending process.

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

Responses and Error Diagnosis

Successful Response (200 OK)

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

Main Errors and Solutions (400 Bad Request)

Need more help? Explore our content on Blip Academy or Blip Community, watch tutorials on our YouTube channel, or ask questions through our support channel 😃