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 de 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 automáticamente cada envío de marketing a la API de Marketing Messages de Meta; 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í, salvo en los encabezados gif y las plantillas con precio máximo, que necesitan una cuenta con onboarding completado. Consulta Plantillas de marketing para conocer el estado de la cuenta, lo que desbloquea el onboarding y en qué países está limitado el marketing.

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 de negocio. 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, o establece un precio máximo para pagar un cargo de entrega variable de Meta hasta tu límite. 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 Costo y facturación y Precios de WhatsApp.

Aspectos a vigilar

La categoría de Meta determina el precio. Meta puede reclasificar como marketing un contenido promocional después de aprobarlo. Revisa la categoría actual de cada idioma antes de enviar; un envío con precio máximo requiere la categoría marketing. Consulta el proceso de revisión de categorías de Meta si no estás de acuerdo con la clasificación.
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