[Open Beta] Cómo utilizar el Envío Directo (Direct Send) para Mensajes de Utilidad mediante la API Growth

1. Contexto
2. ¿Qué es Direct Send y cuáles son sus beneficios?
3. Cómo activar Direct Send
4. Reglas de contenido, límites y validaciones
5. Cómo realizar los envíos mediante la API
6. Respuestas y diagnóstico de errores

Contexto

La función de Envío Directo (Direct Send) es una funcionalidad en versión Beta de WhatsApp Cloud API integrada a Blip. Permite enviar mensajes activos de la categoría Utilidad (Utility) sin necesidad de crear y aprobar previamente plantillas de mensajes (Message Templates / HSM) en el Administrador Comercial de Meta.

Este artículo explica cómo solicitar la activación de la función, las reglas y los límites de contenido exigidos por Meta y cómo estructurar tus solicitudes mediante la API de Blip utilizando las plantillas de envío.
 

¿Qué es Direct Send y cuáles son sus beneficios?

Direct Send simplifica la integración de mensajes transaccionales y operativos, eliminando el tiempo de espera para la aprobación manual de plantillas.

• Aprobación automática: Meta genera y valida las plantillas automáticamente en el momento del primer uso.

• Reutilización inteligente: El sistema identifica mensajes con la misma estructura y reutiliza automáticamente las plantillas que ya se generaron.

• Envío inmediato: Reducción drástica del time-to-market para nuevas comunicaciones activas.

• Garantía de categoría: Evita la reclasificación incorrecta de mensajes transaccionales a la categoría Marketing.
   

Cómo activar Direct Send

La activación implica dos procesos distintos y secuenciales. Primero debes garantizar la elegibilidad en Meta; después, solicitar la habilitación de la funcionalidad dentro del Portal Blip.

Paso 1: Habilitarlo en el Administrador de Meta

• Accede a WhatsApp Manager y verifica la disponibilidad de Direct Send para tu cuenta. Un banner indicará si tu cuenta es elegible.

• Si tu cuenta aún no es elegible, puedes manifestar tu interés mediante el formulario proporcionado por Meta.

• La elegibilidad puede requerir el envío de muestras de mensajes de utilidad para que Meta las revise, con el fin de garantizar que cumplan con las pautas de la categoría. Una vez aprobada, tu cuenta será elegible del lado de Meta.

Paso 2: Solicitar la habilitación en Blip

• Como la funcionalidad está en Beta en Blip, después de obtener la elegibilidad en Meta debes contactar a tu punto de contacto en Blip (CSM o KAM) y solicitar la habilitación del acceso.

• El equipo de Blip habilitará la funcionalidad en tu cuenta y entonces podrás comenzar a utilizar Direct Send en el Portal.

  Resumen: Elegibilidad en Meta → Solicitud a tu CSM/KAM en Blip → Habilitación del acceso → Uso de la funcionalidad.

Reglas de contenido, límites y validaciones

Todas las solicitudes enviadas pasan por validaciones técnicas rigurosas. Las solicitudes que no cumplan con los estándares serán rechazadas con el error 400 Bad Request.
 

1. Categoría permitida

En Direct Send API solo se acepta la categoría utility. Es obligatorio declarar "category": "utility" en el parámetro del mensaje.

2. Límites de caracteres por componente

3. Configuración de TTL (Time To Live)

El parámetro ttl_seconds define el tiempo máximo durante el que WhatsApp intentará entregar el mensaje si el celular del destinatario no tiene conexión:

• Valor mínimo: 30 segundos

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

• Valor predeterminado (si se omite): 2592000 segundos (30 días)

Conversión rápida:

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

Recomendación: Para notificaciones de alta urgencia (por ejemplo, códigos de acceso o alertas inmediatas), utiliza un TTL de entre 300 y 600 segundos (5 a 10 minutos).

Cómo realizar los envíos mediante la API

• Método HTTP: POST

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

• Encabezados estándar:

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

• Authorization: Key {TU_CLAVE_DE_API_DEL_BOT}

Regla del destinatario (campaignType):

• Para envíos individuales ("campaignType": "Individual"), utiliza el campo audience (objeto en singular).

• Para envíos en lote ("campaignType": "Batch"), utiliza el campo audiences (arreglo en plural).

Para envíos utilizando la estructura de Router, debe utilizarse el campo masterState; de lo contrario, debe eliminarse.
Ejemplo: "masterState": "identificador@msging.net"
 

Enfoque 1: Envío mediante (/campaign/full)

Recomendado para integraciones en las que la creación de la campaña y el envío se realizan en una sola llamada.

Ejemplo 1.1:  Texto simple (individual)

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

Ejemplo 1.2: Botón interactivo CTA URL (en 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':'Actualización'},'body':{'text':'Hola {{1}}, consulta los detalles de tu recibo disponible para descargar.'},'footer':{'text':'Haz clic en el botón de abajo'},'action':{'name':'cta_url','parameters':{'display_text':'Descargar recibo','url':'https://suaempresa.com.br/boleto'}}},'category':'utility','ttl_seconds':3600}",
      "channelType": "WhatsApp",
      "messageTemplateLanguage": "es_MX"
    }
  }
}

Ejemplo 1.3: Botones de respuesta rápida (en 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':'Confirmación'},'body':{'text':'Hola {{1}}, ¿confirmas tu cita para mañana?'},'footer':{'text':'Responde seleccionando una de las siguientes opciones'},'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':'Reprogramar'}}]}},'category':'utility','ttl_seconds':600}",
      "channelType": "WhatsApp",
      "messageTemplateLanguage": "es_MX"
    }
  }
}

Ejemplo 1.4: V2 — Ejemplo de solicitud (/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": "es_MX",
      "channelType": "WhatsApp",
      "messageContent": "{'type':'text','text':{'body':'Mensaje mediante Direct Send utilizando la versión Atomic v2.'},'category':'utility'}"
    },
    "dispatch": true
  }
}

Enfoque 2: Envío por fases V2 

El enfoque de Envío por fases V2 se recomienda para arquitecturas en las que la creación de la campaña, la vinculación de contactos y el orden final del envío se realizan en etapas diferidas o en microservicios distintos.

Paso 1: Crear la campaña (POST /campaign/v2)

En esta etapa defines el nombre, el flujo y el contenido del mensaje.

{
  "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':'¡Hola! Registramos tu solicitud de atención.'},'category':'utility'}",
      "channelType": "WhatsApp",
      "messageTemplateLanguage": "es_MX"
    }
  }
}

Guarda el ID de la campaña que se devuelve en la respuesta de esta solicitud para utilizarlo en los pasos 2 y 3.

Paso 2: Vincular la audiencia (POST /audiences/{CAMPAIGN_ID})

Vincula el destinatario a la campaña creada anteriormente reemplazando {CAMPAIGN_ID} por el ID obtenido en el Paso 1.

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

Paso 3: Orden del envío (POST /dispatch/v2)

Con la campaña y la audiencia registradas, ordena la ejecución del envío.

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

Respuestas y diagnóstico de errores

Respuesta exitosa (200 OK)

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

Principales errores y soluciones (400 Bad Request)

¿Necesitas más ayuda? Explora nuestros contenidos en Blip Academy o Blip Community, mira tutoriales en nuestro canal de YouTube o resuelve tus dudas en nuestro canal de atención 😃