Plantillas de utilidad de WhatsApp
Una plantilla de utilidad da seguimiento a algo que el destinatario ya hizo: un pedido, un pago, una reserva, un inicio de sesión. El catálogo de Bird incluye ocho, entre ellas bird_signin_alert y bird_delivery_update. Toma la categoría de un slug de la lista de plantillas, no de su nombre: bird_signin_alert parece una plantilla de autenticación, pero no lo es; es de utilidad.
Antes de enviar
Elige una plantilla del catálogo gestionado o crea una en tu cuenta de negocio conectada.
Enviar las plantillas del catálogo de Bird no requiere verificación de tu parte, igual que con autenticación. Crear una plantilla de utilidad propia tampoco la necesita: a diferencia de autenticación, la verificación de negocio de Meta nunca aplica a utilidad, así que puedes crear y editar plantillas de utilidad en un espacio de trabajo no verificado. Consulta Verificación de negocio de WhatsApp para saber qué desbloquea la verificación en otros casos.
to puede ser un número de teléfono E.164 o un ID de usuario con alcance de negocio. Una plantilla de utilidad no lleva botón OTP, por lo que no exige el destinatario exclusivamente por número de teléfono que sí requiere autenticación.
Cada plantilla de utilidad del catálogo gestionado está registrada solo en en, con on_missing_language: fail. Solicitar un idioma que el catálogo no tiene hace fallar el envío en lugar de recurrir al inglés o a cualquier otro idioma.
Enviar una plantilla de utilidad
POST /v1/whatsapp/messages con un objeto template que nombra un slug del catálogo:
const msg = await bird.whatsapp.send({
to: "+16505551234",
template: {
slug: "bird_order_confirmation",
language: "en",
components: [
{
type: "body",
parameters: [
{ type: "text", name: "ref", text: "A1B2C3D4" },
{ type: "text", name: "amount", text: "USD 49.99" },
],
},
],
},
});
console.log(msg.id, msg.status);msg = client.whatsapp.send(
to="+16505551234",
template="bird_order_confirmation",
language="en",
components=[
{
"type": "body",
"parameters": [
{"type": "text", "name": "ref", "text": "A1B2C3D4"},
{"type": "text", "name": "amount", "text": "USD 49.99"},
],
}
],
)
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)
}
ref := "A1B2C3D4"
amount := "USD 49.99"
refName := "ref"
amountName := "amount"
components := []bird.WhatsAppMessageTemplateComponent{{
Type: "body",
Parameters: &[]bird.WhatsAppMessageTemplateComponentParameter{
{Type: "text", Name: &refName, Text: &ref},
{Type: "text", Name: &amountName, Text: &amount},
},
}}
msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
To: "+16505551234",
Template: "bird_order_confirmation",
Language: "en",
Components: components,
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)
}$components = [
(new WhatsAppMessageTemplateComponent())
->setType('body')
->setParameters([
(new WhatsAppMessageTemplateComponentParameter())->setType('text')->setName('ref')->setText('A1B2C3D4'),
(new WhatsAppMessageTemplateComponentParameter())->setType('text')->setName('amount')->setText('USD 49.99'),
]),
];
$message = $bird->whatsapp->send(
to: '+16505551234',
template: 'bird_order_confirmation',
language: 'en',
components: $components,
);
echo $message->getId(), ' ', $message->getStatus();bird whatsapp send \
--components '[{"parameters":[{"name":"ref","text":"A1B2C3D4","type":"text"},{"name":"amount","text":"USD 49.99","type":"text"}],"type":"body"}]' \
--language en \
--template bird_order_confirmation \
--to +16505551234{
"name": "whatsapp_send",
"arguments": {
"template": {
"components": [
{
"parameters": [
{
"name": "ref",
"text": "A1B2C3D4",
"type": "text"
},
{
"name": "amount",
"text": "USD 49.99",
"type": "text"
}
],
"type": "body"
}
],
"language": "en",
"slug": "bird_order_confirmation"
},
"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",
"template": {
"slug": "bird_order_confirmation",
"language": "en",
"components": [
{
"type": "body",
"parameters": [
{
"type": "text",
"name": "ref",
"text": "A1B2C3D4"
},
{
"type": "text",
"name": "amount",
"text": "USD 49.99"
}
]
}
]
}
}'Como con cualquier plantilla gestionada, omite from: Bird elige el número de envío según la categoría y la región, y establecerlo devuelve 422 E15018 WhatsAppSenderNotAllowed. Crear tu propia plantilla de utilidad y enviarla funciona igual que cualquier envío con plantilla propia; consulta Enviar con una plantilla para el contrato general.
Completar las variables
Los parámetros de utilidad son nombrados, al revés del código posicional único de autenticación. Cada parámetro lleva un name, y el orden de un parámetro nombrado en el arreglo no tiene significado. Envía una entrada components por cada bloque que realmente tenga un marcador de posición; un cuerpo sin variables no lleva entrada components en absoluto.
Un botón de URL es la única excepción: su variable siempre es posicional {{1}}, y el envío lleva solo el valor en lugar de una dirección completa:
Ejemplo de código
{ "type": "button", "parameters": [{ "type": "text", "text": "A-4192" }] }Para las reglas compartidas sobre componentes, sub_type, y cómo los components de un envío se alinean con los marcadores de posición declarados en una plantilla, consulta Enviar con una plantilla y Componentes y parámetros.
Costo
Una plantilla de utilidad entregada dentro de una ventana abierta de servicio al cliente puede calificar para la tarifa gratuita de Meta. La tarifa de envío de Bird se cobra durante el procesamiento del mensaje, antes del envío. Un callback posterior de entrega o lectura determina si se aplica una tarifa de Meta. Revisa ambos componentes al estimar el total.
Consulta Costo y facturación para saber cuándo se cobra un envío, y Precios de WhatsApp para las tarifas.
Puntos a tener en cuenta
- Meta puede recategorizar una plantilla de utilidad como marketing por iniciativa propia, y el mensaje sigue enviándose al nuevo precio, más alto. Un negocio al que Meta ya advirtió por categorización incorrecta no recibe aviso previo alguno desde abril de 2025; el cambio se aplica de inmediato. Mantén el lenguaje promocional, las ofertas y las propuestas de compra de una opción de mayor valor fuera del texto de una plantilla de utilidad, ya que eso es lo que provoca el cambio. Consulta Directrices de plantillas para saber qué se considera promocional.
- Un encabezado gif o un botón copy_code se rechaza fuera de marketing. Ambos son componentes exclusivos de marketing; declarar cualquiera de los dos en una plantilla de utilidad falla.
- Un envío con plantilla propia no se valida por cantidad de parámetros antes de cobrarse. Envía la cantidad incorrecta de parámetros en una plantilla propia y el mensaje se acepta y se cobra, pero luego Meta lo rechaza. Los envíos del catálogo gestionado no tienen este problema.
- Un remitente en la cuenta de negocio WhatsApp incorrecta se rechaza antes de cualquier cobro. from debe estar en la misma cuenta que la plantilla; de lo contrario, 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 autenticación: códigos de verificación de un solo uso y la verificación necesaria para crear una
- Plantillas de marketing: envíos promocionales y la cuenta que necesitas para crear una
Recursos relacionados
Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.
Ver la guíaConnecting WhatsApp to Bird: from buying a number to a live channelComprender el conceptoWhat is the 24-hour customer service window on WhatsApp?Usar la herramientaWhatsApp message builderExplorar la funcionalidadWhatsApp
Prueba el ejercicio y obtén un resumen de implementación