Enviar Templates de Whatsapp V2

Aquí encontrarás información de cómo realizar envíos de mensajes de tipo plantilla de WhatsApp Business a usuarios específicos utilizando la API de B2Chat en su versión 2, esta version soporta el envío de dos botones de tipo URL dinamicas.

Endpoint de envio de templates

https://api.b2chat.io/v2/broadcast

Envio de templates

POST https://api.b2chat.io/v2/broadcast

Este servicio te permitirá enviar una notificación de WhatsApp a un contacto.

Headers

Name	Type	Description
Content-Type*	application/json
Authorization*	Bearer {{token}}

Request Body

Name	Type	Description
from *	Numero movil	Número valido y operativo de una cuenta de WhatsApp Business, el formato debe ser +<codigo del país><movil del usuario> Por ejemplo [phone].
to *	Numero movil	Número valido y operativo de una WhatsApp account
template_name*	String	Nombre del template configurado previamente en B2Chat.
contact_name	String	Nombre del contacto al que se le enviará el template
campaign_name	String	Se utiliza para agrupar el envío de plantillas.
header_url	URL jpg/png/ pdf	URL de una imagen (jpg, png) , o pdf dependiendo de la configuración de la plantilla que vayas a enviar. Asegúrate de enviar la url correcta con el tipo de contenido esperado.
button_url_suffixes	Array	Cuando la plantilla configurada contiene unos botones dentro de una url, un fragmento de esta puede ser variable por ejemplo: https://www.merriam-webster.com/dictionary/${button_url_suffix} El fragmento será sustituido por el valor enviado. Si envía la palabra template como valor para button_url_suffixes la url se enviará como https://www.merriam-webster.com/dictionary/template
values	Array	Array de valores de plantilla en el mismo orden registrado en las variables de template registrado en B2Chat.
broadcast_target	JSON	Este campo permite direccionar la respuesta al template por parte del contacto a un departamento configurado en B2Chat o un agente en específico, debe tener dos campos: *target: puede tener dos valores, AGENT o DEPARTAMENT *target_id: debe incluir el ID del departamento o agente a donde deseas redirigir la respuesta del contacto. Para conocer estos IDs, ya sean de departamentos o agentes solicitalos directamente al equipo de soporte.

Ejemplo 1: Enviar template de solo texto plano

curl --location --request POST 'https://api.b2chat.io/broadcast' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
	"from":"+57300xxxxxxx",
	"to":"+57300xxxxxxx",
	"template_name":"christmas_evening",
	"contact_name":"Mark",	
	"campaign_name":"christmas campaign",
	"values": []
}'

Ejemplo 2: Enviar template con texto que incluye variables

curl --location --request POST 'https://api.b2chat.io/broadcast' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
	"from":"+57300xxxxxxx",
	"to":"+57300xxxxxxx",
	"template_name":"christmas_evening",
	"contact_name":"Mark",	
	"campaign_name":"christmas campaign",
	"values": ["Agent John","Contact Mark"]
}'

Ejemplo 3: Enviar template con texto con variables e imagen en el encabezado.

curl --location --request POST 'https://api.b2chat.io/broadcast' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
	"from":"+57300xxxxxxx",
	"to":"+57300xxxxxxx",
	"template_name":"christmas_evening",
	"contact_name":"Mark",	
	"campaign_name":"christmas campaign",
  	"header_url": "http://www.africau.edu/images/default/sample.pdf",
	"values": ["Agent John","Contact Mark"]
}'

Ejemplo 4: Enviar template con texto con variables, imagen en el encabezado y boton de tipo URL con sufijo.

curl --location --request POST 'https://api.b2chat.io/broadcast' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
	"from":"+57300xxxxxxx",
	"to":"+57300xxxxxxx",
	"template_name":"christmas_evening",
	"contact_name":"Mark",	
	"campaign_name":"christmas campaign",
  	"header_url": "http://www.africau.edu/images/default/sample.pdf",
  	"button_url_suffix": "template",
	"values": ["Agent John","Contact Mark"]
}'

Ejemplo 5: Enviar template de solo texto plano con redirección en la respuesta a un agente.

curl --location --request POST 'https://api.b2chat.io/broadcast' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
    "from": "+5730XXXXXXX",
    "to": "[phone]",
    "contact_name": "",
    "template_name": "notificacion_template_v5",
    "campaign_name": null,
    "header_url": "http://www.africau.edu/images/default/sample.pdf",
    "button_url_suffix": "url_suffix",
    "values": ["https://kshk.co/juancho-te-presta/B80mJB4qz"],
    "broadcast_target": {"target": "AGENT", "target_id": 476}
}'

Respuestas de API Broadcast

Template enviado

200 OK

{
    "message": "Broadcast request received",
    "trace_id": "74a9bbc7-0644-4b23-9c2b-f830557acb8a"
}

No existe el template

400

{
    "timestamp": "2025-04-08T20:29:56.308+00:00",
    "trace": "2d8f6d68-5a9b-447d-8963-72b046b435be",
    "message": "Account by filters was not found",
    "code": "INVALID_ACCOUNT_CREDENTIALS",
    "errors": null
}

Template inactivo

400

{
    "timestamp": "2025-04-08T20:33:10.653+00:00",
    "trace": "4c6c976d-24e1-4b2e-8189-0a77cebc4332",
    "message": "Template is not in ACTIVE state. Current status: INACTIVE",
    "code": "CONFLICT",
    "errors": null
}

No se están enviando la cantidad de variables esperadas (se envían menos de los que tiene el template)

400

{
    "timestamp": "2025-04-08T20:34:01.230+00:00",
    "trace": "d5f43140-be88-4b8c-b925-a20d31a1ab1c",
    "message": "Values don't match the expected number of parameters",
    "code": "BAD_REQUEST_PAYLOAD",
    "errors": null
}

Error en formato de móvil de envío “From”

400

{
    "timestamp": "2025-04-08T20:39:01.705+00:00",
    "trace": "a1116099-a320-4a32-8ed5-e6818f2afc46",
    "message": "Found validation errors in request",
    "code": "FOUND_VALIDATION_ERRORS",
    "errors": [
        "Required valid mobile number (from:[phone]) (e.g.+573001234567) and cannot be empty"
    ]
}

Error en formato de móvil de recepción “To”

400

{
    "timestamp": "2025-04-08T20:40:30.320+00:00",
    "trace": "834f720e-2840-4431-a816-6c5aa7f451b4",
    "message": "Invalid parameter: The MessageGroupId parameter can only include alphanumeric and punctuation characters. 1 to 128 in length (Service: Sns, Status Code: 400, Request ID: 058dddc9-87c4-5500-a8f1-bda60c3a9591, Extended Request ID: null)",
    "code": "SYSTEM_EXCEPTION",
    "errors": null
}

Error por límite de mensajes (rate limits)

400

{
    "timestamp": "2025-04-08T20:40:30.320+00:00",
    "trace": "834f720e-2840-4431-a816-6c5aa7f451b4",
    "message": "Requests per second reached limit",
    "code": "REACHED_REQUESTS_PER_SECOND_RATE_LIMIT",
    "errors": null
}