Plantillas de marketing de WhatsApp

Una plantilla de marketing lleva contenido promocional, como una oferta, un anuncio de producto o un cupón. Antes de enviar, prepara el contenido aprobado, el permiso del destinatario y una forma clara de gestionar respuestas y cancelaciones de suscripción.

Antes de enviar

El catálogo gestionado de Bird no incluye ninguna plantilla de marketing, así que un envío de marketing siempre usa una plantilla creada en tu espacio de trabajo, en una WhatsApp Business Account propia:

Conecta una WhatsApp Business Account y un número propio. Consulta Configuración del número de teléfono.
Crea una plantilla con categoría marketing y envíala a revisión. Consulta Directrices de plantillas para saber qué se aprueba.
Envía desde un número en la misma WhatsApp Business Account que la plantilla. from es obligatorio en un envío de marketing, y un remitente en una cuenta diferente se rechaza 422 E15023 WhatsAppSenderWABAMismatch antes de que se cobre nada.

Enviar una plantilla de marketing

POST /v1/whatsapp/messages con from configurado y un objeto template que indique tu propio slug:

const msg = await bird.whatsapp.send({
  to: "+16505551234",
  from: "+13125550101",
  template: {
    slug: "summer_sale",
    language: "en",
    components: [
      {
        type: "header",
        parameters: [{ type: "image", url: "https://cdn.example.com/banners/summer.png" }],
      },
      { type: "body", parameters: [{ type: "text", name: "first_name", text: "Pablo" }] },
      { type: "button", parameters: [{ type: "text", text: "SUMMER25" }] },
    ],
  },
});
console.log(msg.id, msg.status);

msg = client.whatsapp.send(
    to="+16505551234",
    from_="+13125550101",
    template="summer_sale",
    language="en",
    components=[
        {
            "type": "header",
            "parameters": [{"type": "image", "url": "https://cdn.example.com/banners/summer.png"}],
        },
        {"type": "body", "parameters": [{"type": "text", "name": "first_name", "text": "Pablo"}]},
        {"type": "button", "parameters": [{"type": "text", "text": "SUMMER25"}]},
    ],
)
print(msg.id, msg.status)

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	bird "github.com/messagebird/bird-sdk-go"
	"github.com/messagebird/bird-sdk-go/option"
)

func main() {
	client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}
	name := "Pablo"
	nameKey := "first_name"
	banner := "https://cdn.example.com/banners/summer.png"
	coupon := "SUMMER25"
	components := []bird.WhatsAppMessageTemplateComponent{
		{Type: "header", Parameters: &[]bird.WhatsAppMessageTemplateComponentParameter{{Type: "image", Url: &banner}}},
		{Type: "body", Parameters: &[]bird.WhatsAppMessageTemplateComponentParameter{{Type: "text", Name: &nameKey, Text: &name}}},
		{Type: "button", Parameters: &[]bird.WhatsAppMessageTemplateComponentParameter{{Type: "text", Text: &coupon}}},
	}
	msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
		To:       "+16505551234",
		From:     "+13125550101",
		Template: "summer_sale",
		Language: "en",
		Components: components,
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

$components = [
    (new WhatsAppMessageTemplateComponent())
        ->setType('header')
        ->setParameters([
            (new WhatsAppMessageTemplateComponentParameter())->setType('image')->setUrl('https://cdn.example.com/banners/summer.png'),
        ]),
    (new WhatsAppMessageTemplateComponent())
        ->setType('body')
        ->setParameters([
            (new WhatsAppMessageTemplateComponentParameter())->setType('text')->setName('first_name')->setText('Pablo'),
        ]),
    (new WhatsAppMessageTemplateComponent())
        ->setType('button')
        ->setParameters([
            (new WhatsAppMessageTemplateComponentParameter())->setType('text')->setText('SUMMER25'),
        ]),
];
$message = $bird->whatsapp->send(
    to: '+16505551234',
    from: '+13125550101',
    template: 'summer_sale',
    language: 'en',
    components: $components,
);
echo $message->getId(), ' ', $message->getStatus();

bird whatsapp send \
  --from +13125550101 \
  --components '[{"parameters":[{"type":"image","url":"https://cdn.example.com/banners/summer.png"}],"type":"header"},{"parameters":[{"name":"first_name","text":"Pablo","type":"text"}],"type":"body"},{"parameters":[{"text":"SUMMER25","type":"text"}],"type":"button"}]' \
  --language en \
  --template summer_sale \
  --to +16505551234

curl -X POST "https://us1.platform.bird.com/v1/whatsapp/messages" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "to": "+16505551234",
      "from": "+13125550101",
      "template": {
        "slug": "summer_sale",
        "language": "en",
        "components": [
          {
            "type": "header",
            "parameters": [
              {
                "type": "image",
                "url": "https://cdn.example.com/banners/summer.png"
              }
            ]
          },
          {
            "type": "body",
            "parameters": [
              {
                "type": "text",
                "name": "first_name",
                "text": "Pablo"
              }
            ]
          },
          {
            "type": "button",
            "parameters": [
              {
                "type": "text",
                "text": "SUMMER25"
              }
            ]
          }
        ]
      }
    }'

Los parámetros del cuerpo son nombrados, igual que en utilidad. Cada parámetro lleva un name, y el orden en el array no tiene significado.
El código de un botón de cupón es un parámetro text ordinario, como el del botón de arriba. No existe un tipo de parámetro separado para códigos de cupón.
Un encabezado gif recibe un parámetro gif, no video ni image. Marketing es la única categoría que acepta un encabezado de GIF animado.
Los valores de un carrusel van en cards, no en parameters, y el envío debe incluir exactamente la cantidad de tarjetas con las que se aprobó la plantilla.

Bird enruta cada envío de marketing a la API de Marketing Messages de Meta automáticamente; no tienes que activarlo y no hay un interruptor por envío. El estado de onboarding de la cuenta de negocio con esa API condiciona las optimizaciones de Meta, no la entrega en sí, con una excepción: un encabezado gif necesita una cuenta con onboarding completado o el envío falla en WhatsApp. Consulta Plantillas de marketing para el estado de la cuenta, lo que desbloquea el onboarding y dónde el marketing está limitado por país.

Cancelaciones de suscripción

Cuando Bird recibe un evento válido de detención de marketing de Meta, registra una preferencia de destinatario para esa cuenta empresarial. Esta preferencia es independiente de una supresión de todos los mensajes. Comprueba ambos registros antes de enviar. Un fallo de entrega puede llegar antes del evento de preferencia correspondiente; respeta la decisión del destinatario e investiga ese historial en lugar de reintentar. Consulta Preferencias para registrar y consultar estos registros.

Costo

Usa la tarifa de marketing publicada para el destino y la moneda. Bird cobra su tarifa de salida antes del envío; un resultado facturable de entrega o lectura puede añadir la tarifa de Meta. Consulta Coste y facturación y Precios de WhatsApp.

Aspectos a vigilar

Meta recategoriza a marketing, nunca fuera de marketing, y eso es un cambio de precio. Una plantilla que Meta considere promocional en su contenido pasa a ser marketing sin importar la categoría que enviaste, y el envío sigue saliendo al nuevo precio más alto. No hay opción de exclusión ni forma de editar la categoría de vuelta; la solución es una plantilla nueva.
131049 es una pausa de entrega, no un límite de frecuencia que hayas configurado, y reintentar lo empeora. Meta reporta 131049 tanto para su pausa general en EE. UU. como para un tope de marketing por usuario, y su propia recomendación es esperar aproximadamente un día antes de reenviar. Reenviar antes puede hacer que la cuenta no esté disponible para ese destinatario por más tiempo y distorsiona tu propia tasa de entrega. Bird reporta el fallo como rate_limited.
131050 significa que el destinatario desactivó "Offers and announcements", y nunca debe reintentarse. Meta acepta el envío y luego rechaza entregarlo. La respuesta correcta es la ruta de preferencias de mensajería, no un reenvío: suprime al destinatario tú mismo, o espera a que reactive la entrega, algo que Bird detecta a través del mismo mecanismo de preferencias que reportó la detención. Consulta Preferencias.
132015 y 132016 son una pausa de plantilla, no un problema del destinatario. 132015 es una pausa por baja calidad; 132016 es una desactivación permanente tras pausas repetidas, y su único remedio es una plantilla nueva con contenido diferente. Revisa el estado del idioma en lugar del de la plantilla, ya que un idioma pausado deja de enviar de inmediato.
Un remitente en la WhatsApp Business Account incorrecta se rechaza antes de cualquier cobro. from debe estar en la misma cuenta que la plantilla, o el envío falla 422 E15023 WhatsAppSenderWABAMismatch.

Próximos pasos

Plantillas de WhatsApp: explorar el catálogo y el contrato compartido de envío por plantilla
Plantillas de marketing: la API de Marketing Messages, estado de onboarding y dónde el marketing está limitado
Preferencias: registro y consulta de declaraciones de destinatarios
Plantillas de utilidad: actualizaciones de pedidos, recordatorios de citas y avisos de cuenta

Continúa con la documentación, guías y ejemplos de este tema.

Prueba el ejercicio y obtén un resumen de implementación