From 1d5fb5894a71b2a2871a5863a761c2c14123cba7 Mon Sep 17 00:00:00 2001 From: Martin Caetano Date: Fri, 7 Aug 2026 14:22:40 -0300 Subject: [PATCH 1/2] Add Templates API guide --- _config.yml | 1 + _developers/templates-with-api.md | 19 ++ _i18n/en/developers/developers-overview.md | 1 + _i18n/en/developers/send-sms-with-api.md | 2 + _i18n/en/developers/templates-with-api.md | 241 +++++++++++++++++++++ _i18n/es/developers/developers-overview.md | 1 + _i18n/es/developers/send-sms-with-api.md | 2 + _i18n/es/developers/templates-with-api.md | 241 +++++++++++++++++++++ 8 files changed, 508 insertions(+) create mode 100644 _developers/templates-with-api.md create mode 100644 _i18n/en/developers/templates-with-api.md create mode 100644 _i18n/es/developers/templates-with-api.md diff --git a/_config.yml b/_config.yml index 36d96ee9..6c7bd64b 100644 --- a/_config.yml +++ b/_config.yml @@ -218,6 +218,7 @@ collections: - developers-overview.md - custom-store-integration.md - api.md + - templates-with-api.md - products-and-inventory-with-api.md - orders-with-api.md - coupons-with-api.md diff --git a/_developers/templates-with-api.md b/_developers/templates-with-api.md new file mode 100644 index 00000000..903e364e --- /dev/null +++ b/_developers/templates-with-api.md @@ -0,0 +1,19 @@ +--- +languages: ["en", "es"] + +en: + title: Create and send templates with the API + description: Create reusable SMS and WhatsApp content, personalize it with customer data, and send it safely through the Messages API. +es: + title: Crea y envía plantillas con la API + description: Crea contenido reutilizable para SMS y WhatsApp, personalízalo con datos del cliente y envíalo de forma segura mediante la API de mensajes. + +permalink: templates-with-api +permalink_es: plantillas-con-api + +layout: guide +topic: developers +popular: true +--- + +{% translate_file developers/templates-with-api.md %} diff --git a/_i18n/en/developers/developers-overview.md b/_i18n/en/developers/developers-overview.md index 36bf5fbc..869b444b 100644 --- a/_i18n/en/developers/developers-overview.md +++ b/_i18n/en/developers/developers-overview.md @@ -27,6 +27,7 @@ Open the [Hellotext API reference](https://www.hellotext.com/api). Use the practical API guides when you need to move from the endpoint contract to a complete integration flow: +- [Create and send templates with the API]({% link _developers/templates-with-api.md %}) - [Sync products and understand inventory availability]({% link _developers/products-and-inventory-with-api.md %}) - [Create and track orders with the API]({% link _developers/orders-with-api.md %}) - [Create and track coupons with the API]({% link _developers/coupons-with-api.md %}) diff --git a/_i18n/en/developers/send-sms-with-api.md b/_i18n/en/developers/send-sms-with-api.md index be654021..120d8658 100644 --- a/_i18n/en/developers/send-sms-with-api.md +++ b/_i18n/en/developers/send-sms-with-api.md @@ -117,6 +117,8 @@ For reusable content, property-based personalization, or named dynamic links, yo Templates with dynamic links require you to send their URLs under `template.shortlinks`. The [message sending reference](https://www.hellotext.com/api#create_a_message) contains the complete structure. +See [Create and send templates with the API]({% link _developers/templates-with-api.md %}) for template creation, property tags, dynamic short links, channel targeting, and WhatsApp approval. + ## Length, encoding, and cost The character capacity of one SMS segment depends on its encoding: diff --git a/_i18n/en/developers/templates-with-api.md b/_i18n/en/developers/templates-with-api.md new file mode 100644 index 00000000..0ac7e00d --- /dev/null +++ b/_i18n/en/developers/templates-with-api.md @@ -0,0 +1,241 @@ +A template stores reusable message content in Hellotext. Create it once through the Templates API, keep its Hellotext ID, and use that ID when your backend sends an individual message through the Messages API. + +Creating a template does not send a message, create a campaign, or enable a playbook. Delivery still depends on the selected channel, the customer profile, consent, channel availability, and, for WhatsApp, Meta approval and the customer service window. + +Use the [Templates API reference](https://www.hellotext.com/api#templates) for the complete contract. This guide covers the recommended implementation flow. + +## Before you start + +Prepare: + +- A private API authorization token stored only on your backend. +- An active Hellotext business with the channels you intend to use. +- A connected WhatsApp Business account if the template targets WhatsApp. +- A stable, unique template name. +- A clear decision between `sms`, `whatsapp`, or `any` technology. +- A `marketing` or `utility` category that matches the real purpose of a WhatsApp message. +- The Hellotext customer profile ID and, when needed, the specific destination for the send. +- Definitions and values for every customer property used for personalization. + +Create custom customer properties before using their names as tags. See [Custom properties and events]({% link _audience/custom-properties-and-events.md %}). + +## 1. Choose the template technology + +The `technology` value determines where the template can be used and which components it accepts. + +### SMS + +An `sms` template supports the message body only. Do not send a header, footer, or buttons with an SMS-only template. + +SMS length and encoding determine how many billable segments the final message uses. Keep the rendered message concise and test it with real customer data. See [Send SMS with the API]({% link _developers/send-sms-with-api.md %}). + +### WhatsApp + +A `whatsapp` template can include: + +- A required body. +- An optional text, attachment, or address header. +- An optional footer. +- Optional quick-reply, URL, phone, or copy buttons. + +WhatsApp templates are submitted to Meta and initially return a pending state. Do not depend on the template for a production send until its state is approved. + +### Any compatible technology + +Use `any` when the same reusable content should be available to compatible connected channels. If the business has WhatsApp connected, Hellotext also submits the WhatsApp version to Meta. When the template is sent through SMS, only its body is used. + +Use a channel-specific template when its wording or components only make sense on one channel. + +## 2. Create an SMS template + +Create an SMS-only template with a name and body: + +```bash +curl --request POST \ + --url https://api.hellotext.com/v1/templates \ + --header "Authorization: Bearer $HELLOTEXT_API_TOKEN" \ + --header "Content-Type: application/json" \ + --data '{ + "name": "Order ready SMS", + "technology": "sms", + "body": "Hi {name}, your order is ready. View it here: {shortlink:order}" + }' +``` + +Save the returned template `id`. SMS-only templates are represented as approved because they do not require Meta review. + +The example uses a dynamic short link. Your backend must provide the `order` destination URL every time it sends this template. + +## 3. Create a WhatsApp template + +For WhatsApp, explicitly set the category and include only the components the message needs: + +```bash +curl --request POST \ + --url https://api.hellotext.com/v1/templates \ + --header "Authorization: Bearer $HELLOTEXT_API_TOKEN" \ + --header "Content-Type: application/json" \ + --data '{ + "name": "Order ready WhatsApp", + "technology": "whatsapp", + "category": "utility", + "header": { + "type": "text", + "text": "Your order is ready" + }, + "body": "Hi {name}, your order is ready. View the details here: {shortlink:order}.", + "footer": "Reply if you need help", + "buttons": [ + { + "type": "quick_reply", + "text": "I need help" + } + ] + }' +``` + +Use `utility` for an expected transactional update and `marketing` for a promotion, offer, or re-engagement message. Set the real purpose instead of choosing the category based on price. Meta can reject or reclassify content that does not match its category. + +Important component rules include: + +- The WhatsApp body supports up to the limit documented by the API and cannot begin or end with a standalone parameter. +- Text headers are limited to 60 characters. +- An attachment header requires a publicly accessible `attachment_url`; Hellotext downloads and stores the file. +- A template supports up to 10 buttons in total. +- Button text is limited to 25 characters. +- A template can contain at most two URL buttons, one phone button, and one copy button. + +See [Create a template](https://www.hellotext.com/api#create_a_template) and the [component reference](https://www.hellotext.com/api#header_a_template) for current field and file limits. + +## 4. Personalize the body safely + +Template bodies support customer property tags inside braces. Common examples include: + +- `{name}` +- `{full_name}` +- `{last_name}` +- `{email}` +- `{phone}` +- `{birthday}` +- A custom customer property such as `{membership_level}` + +Property tags are resolved from the customer profile used for the send. Before launch, test profiles with values present, missing, and unusually long so the rendered message still reads naturally. + +WhatsApp does not accept a body that starts or ends with a parameter standing by itself. For example: + +- Valid: `Hi {name}, your order is ready.` +- Invalid: `{name}, your order is ready.` + +See [Template body and property tags](https://www.hellotext.com/api#body_a_template). + +## 5. Use static and dynamic short links + +Use a static short link when every recipient should reach the same destination: + +```text +View the collection: {shortlink:https://shop.example.com/collections/new} +``` + +Use a named dynamic short link when your backend supplies a different URL for each send: + +```text +View your order: {shortlink:order} +``` + +Every named dynamic short link in the template requires a value under `template.shortlinks` when the message is sent. Hellotext shortens the supplied URL and associates click activity with the message context. + +## 6. Wait for WhatsApp approval + +Retrieve the template and inspect its `state`: + +```bash +curl --request GET \ + --url https://api.hellotext.com/v1/templates/TEMPLATE_ID \ + --header "Authorization: Bearer $HELLOTEXT_API_TOKEN" +``` + +Treat the main states as follows: + +- `pending`: Meta is still reviewing the WhatsApp template. +- `approved`: the template can be used for compatible WhatsApp sends. +- `rejected`: revise the content or category before depending on it. + +SMS-only templates do not go through Meta approval. An `any` template can still be pending when it includes a WhatsApp version. + +Do not interpret a successful `POST /v1/templates` response as WhatsApp approval. It confirms that Hellotext created the template and started the applicable synchronization flow. + +## 7. Send an approved template + +Send the template through the Messages API. Specify the technology explicitly when the channel matters: + +```bash +curl --request POST \ + --url https://api.hellotext.com/v1/messages \ + --header "Authorization: Bearer $HELLOTEXT_API_TOKEN" \ + --header "Content-Type: application/json" \ + --data '{ + "profile": "PROFILE_ID", + "technology": "whatsapp", + "template": { + "id": "TEMPLATE_ID", + "shortlinks": { + "order": "https://shop.example.com/account/orders/1001" + } + } + }' +``` + +When `template` is present, Hellotext uses the template body and ignores a separate message `body`. You can pass the template ID as a string when the template has no dynamic short links. + +A valid request returns: + +```json +{ + "status": "received" +} +``` + +This means the message was accepted for processing. It does not confirm delivery by WhatsApp or the mobile carrier. Retrieve the message or review the conversation and delivery state separately. + +For WhatsApp, a free-form message can only be sent while the customer service window is open. An approved WhatsApp template is required to initiate a conversation or send outside that window. + +See [Template messages](https://www.hellotext.com/api#templates_a_message) and [Send a message](https://www.hellotext.com/api#create_a_message). + +## 8. Update or retire a template safely + +Use `PATCH /v1/templates/:id` to change supported content such as the body, header, footer, buttons, or target technology. + +For WhatsApp templates: + +- Content changes may require another Meta review. +- Do not assume the changed content is live while its state is pending. +- Do not use an update to rename a WhatsApp template; create a new template when the reusable identity must change. +- Changing the target technology can make the template unavailable on its previous channel. + +Use `DELETE /v1/templates/:id` only when the reusable standard template should no longer be available. Do not delete a template merely to change copy, and verify that campaigns, routes, playbooks, or backend jobs no longer depend on its ID. + +See [Update a template](https://www.hellotext.com/api#update_a_template) and [Delete a template](https://www.hellotext.com/api#delete_a_template). + +## 9. Troubleshoot common errors + +Check these causes before retrying: + +- **`401`:** the API token is missing, invalid, or revoked. +- **`403`:** the business cannot perform the requested API operation. +- **`422` on `technology`:** WhatsApp is not connected or the value is not `sms`, `whatsapp`, or `any`. +- **`422` on components:** an SMS-only template includes a header, footer, or buttons, or a component exceeds its limit. +- **`422` on `body`:** the body is blank, too long, or contains a dangling WhatsApp parameter. +- **`422` on buttons:** a button is missing its matching URL, phone, copy value, or text, or the allowed count was exceeded. +- **Message request fails:** the template does not belong to the business, a dynamic short link is missing, the customer profile cannot be reached, or the selected channel is unavailable. +- **WhatsApp message does not send:** the template or latest change is still pending, rejected, paused, or otherwise unavailable in Meta. + +Do not retry an unchanged validation error. Correct the named parameter first. Use [Troubleshoot a custom integration]({% link _developers/troubleshoot-custom-integration.md %}) for authentication, logging, retries, and end-to-end diagnostics. + +## Related guides + +- [Developers and API overview]({% link _developers/developers-overview.md %}) +- [Send SMS with the API]({% link _developers/send-sms-with-api.md %}) +- [WhatsApp channel fundamentals]({% link _numbers/whatsapp-channel-fundamentals.md %}) +- [Message editor overview]({% link _numbers/message-editor-overview.md %}) +- [Personalization tags]({% link _audience/personalization-tags.md %}) +- [Troubleshoot WhatsApp templates]({% link _troubleshooting-deliverability/troubleshoot-whatsapp-templates.md %}) diff --git a/_i18n/es/developers/developers-overview.md b/_i18n/es/developers/developers-overview.md index 17873173..e706ee5e 100644 --- a/_i18n/es/developers/developers-overview.md +++ b/_i18n/es/developers/developers-overview.md @@ -27,6 +27,7 @@ Abre la [referencia de la API de Hellotext](https://www.hellotext.com/api). Usa las guías prácticas de la API cuando necesites pasar del contrato de un endpoint a un flujo de integración completo: +- [Crea y envía plantillas con la API]({% link _developers/templates-with-api.md %}) - [Sincroniza productos y entiende la disponibilidad de inventario]({% link _developers/products-and-inventory-with-api.md %}) - [Crea y registra pedidos con la API]({% link _developers/orders-with-api.md %}) - [Crea y registra cupones con la API]({% link _developers/coupons-with-api.md %}) diff --git a/_i18n/es/developers/send-sms-with-api.md b/_i18n/es/developers/send-sms-with-api.md index 9af7ff47..c9d2b897 100644 --- a/_i18n/es/developers/send-sms-with-api.md +++ b/_i18n/es/developers/send-sms-with-api.md @@ -117,6 +117,8 @@ Para contenido reutilizable, personalización mediante propiedades o links diná Las plantillas con links dinámicos requieren que envíes sus URLs dentro de `template.shortlinks`. La [referencia para enviar mensajes](https://www.hellotext.com/api#create_a_message) contiene la estructura completa. +Consulta [Crea y envía plantillas con la API]({% link _developers/templates-with-api.md %}) para conocer la creación de plantillas, etiquetas de propiedades, links cortos dinámicos, selección de canales y aprobación de WhatsApp. + ## Longitud, codificación y costo La cantidad de caracteres de un segmento SMS depende de su codificación: diff --git a/_i18n/es/developers/templates-with-api.md b/_i18n/es/developers/templates-with-api.md new file mode 100644 index 00000000..0a90f84e --- /dev/null +++ b/_i18n/es/developers/templates-with-api.md @@ -0,0 +1,241 @@ +Una plantilla guarda contenido reutilizable para mensajes en Hellotext. Créala una vez mediante la API de plantillas, conserva su ID de Hellotext y usa ese ID cuando tu backend envíe un mensaje individual mediante la API de mensajes. + +Crear una plantilla no envía un mensaje, no crea una campaña ni habilita un playbook. La entrega sigue dependiendo del canal elegido, el perfil del cliente, el consentimiento, la disponibilidad del canal y, para WhatsApp, la aprobación de Meta y la ventana de atención. + +Usa la [referencia de la API de plantillas](https://www.hellotext.com/api#templates) para consultar el contrato completo. Esta guía explica el flujo de implementación recomendado. + +## Antes de comenzar + +Prepara: + +- Un token privado de autorización para la API guardado únicamente en tu backend. +- Un negocio activo en Hellotext con los canales que piensas utilizar. +- Una cuenta de WhatsApp Business conectada si la plantilla apunta a WhatsApp. +- Un nombre estable y único para la plantilla. +- Una decisión clara entre las tecnologías `sms`, `whatsapp` o `any`. +- Una categoría `marketing` o `utility` que coincida con el propósito real de un mensaje de WhatsApp. +- El ID del perfil del cliente en Hellotext y, cuando sea necesario, el destino específico para el envío. +- Las definiciones y los valores de todas las propiedades del cliente utilizadas para personalizar. + +Crea las propiedades personalizadas del cliente antes de utilizar sus nombres como etiquetas. Consulta [Propiedades y eventos personalizados]({% link _audience/custom-properties-and-events.md %}). + +## 1. Elige la tecnología de la plantilla + +El valor de `technology` determina dónde puede usarse la plantilla y qué componentes acepta. + +### SMS + +Una plantilla `sms` admite únicamente el cuerpo del mensaje. No envíes header, footer ni botones en una plantilla exclusiva para SMS. + +La longitud y codificación del SMS determinan cuántos segmentos facturables utiliza el mensaje final. Mantén breve el mensaje renderizado y pruébalo con datos reales de clientes. Consulta [Enviar SMS con la API]({% link _developers/send-sms-with-api.md %}). + +### WhatsApp + +Una plantilla `whatsapp` puede incluir: + +- Un cuerpo obligatorio. +- Un header opcional de texto, archivo o dirección. +- Un footer opcional. +- Botones opcionales de respuesta rápida, URL, teléfono o copia. + +Las plantillas de WhatsApp se envían a Meta y al principio devuelven un estado pendiente. No dependas de la plantilla para un envío en producción hasta que su estado sea aprobado. + +### Cualquier tecnología compatible + +Usa `any` cuando el mismo contenido reutilizable deba quedar disponible para canales conectados compatibles. Si el negocio tiene WhatsApp conectado, Hellotext también envía la versión de WhatsApp a Meta. Cuando la plantilla se envía por SMS, se utiliza solamente su cuerpo. + +Usa una plantilla específica para un canal cuando el texto o los componentes solo tengan sentido en ese canal. + +## 2. Crea una plantilla para SMS + +Crea una plantilla exclusiva para SMS con nombre y cuerpo: + +```bash +curl --request POST \ + --url https://api.hellotext.com/v1/templates \ + --header "Authorization: Bearer $HELLOTEXT_API_TOKEN" \ + --header "Content-Type: application/json" \ + --data '{ + "name": "Pedido listo SMS", + "technology": "sms", + "body": "Hola {name}, tu pedido está listo. Revísalo aquí: {shortlink:order}" + }' +``` + +Guarda el `id` devuelto para la plantilla. Las plantillas exclusivas para SMS se representan como aprobadas porque no requieren revisión de Meta. + +El ejemplo utiliza un link corto dinámico. Tu backend debe proporcionar la URL de destino de `order` cada vez que envía esta plantilla. + +## 3. Crea una plantilla para WhatsApp + +Para WhatsApp, establece explícitamente la categoría e incluye únicamente los componentes que necesita el mensaje: + +```bash +curl --request POST \ + --url https://api.hellotext.com/v1/templates \ + --header "Authorization: Bearer $HELLOTEXT_API_TOKEN" \ + --header "Content-Type: application/json" \ + --data '{ + "name": "Pedido listo WhatsApp", + "technology": "whatsapp", + "category": "utility", + "header": { + "type": "text", + "text": "Tu pedido está listo" + }, + "body": "Hola {name}, tu pedido está listo. Revisa los detalles aquí: {shortlink:order}.", + "footer": "Responde si necesitas ayuda", + "buttons": [ + { + "type": "quick_reply", + "text": "Necesito ayuda" + } + ] + }' +``` + +Usa `utility` para una actualización transaccional esperada y `marketing` para una promoción, oferta o reactivación. Elige el propósito real en lugar de decidir la categoría según el precio. Meta puede rechazar o reclasificar contenido que no coincida con su categoría. + +Algunas reglas importantes para los componentes son: + +- El cuerpo de WhatsApp admite hasta el límite documentado por la API y no puede comenzar ni terminar con un parámetro aislado. +- Los headers de texto están limitados a 60 caracteres. +- Un header con archivo requiere una `attachment_url` accesible públicamente; Hellotext descarga y guarda el archivo. +- Una plantilla admite hasta 10 botones en total. +- El texto de cada botón está limitado a 25 caracteres. +- Una plantilla puede contener como máximo dos botones de URL, uno de teléfono y uno de copia. + +Consulta [Crear una plantilla](https://www.hellotext.com/api#create_a_template) y la [referencia de componentes](https://www.hellotext.com/api#header_a_template) para conocer los límites actuales de campos y archivos. + +## 4. Personaliza el cuerpo de forma segura + +Los cuerpos de las plantillas admiten etiquetas de propiedades del cliente entre llaves. Algunos ejemplos frecuentes son: + +- `{name}` +- `{full_name}` +- `{last_name}` +- `{email}` +- `{phone}` +- `{birthday}` +- Una propiedad personalizada del cliente como `{membership_level}` + +Las etiquetas se resuelven a partir del perfil del cliente utilizado para el envío. Antes de lanzar, prueba perfiles con valores presentes, faltantes y especialmente largos para que el mensaje renderizado siga siendo natural. + +WhatsApp no acepta un cuerpo que comience o termine con un parámetro aislado. Por ejemplo: + +- Válido: `Hola {name}, tu pedido está listo.` +- Inválido: `{name}, tu pedido está listo.` + +Consulta [Cuerpo de plantillas y etiquetas de propiedades](https://www.hellotext.com/api#body_a_template). + +## 5. Usa links cortos estáticos y dinámicos + +Usa un link corto estático cuando todos los clientes deban llegar al mismo destino: + +```text +Mira la colección: {shortlink:https://shop.example.com/collections/new} +``` + +Usa un link corto dinámico con nombre cuando tu backend proporcione una URL diferente en cada envío: + +```text +Revisa tu pedido: {shortlink:order} +``` + +Cada link corto dinámico con nombre en la plantilla requiere un valor dentro de `template.shortlinks` al enviar el mensaje. Hellotext acorta la URL proporcionada y asocia la actividad de clicks con el contexto del mensaje. + +## 6. Espera la aprobación de WhatsApp + +Recupera la plantilla y revisa su `state`: + +```bash +curl --request GET \ + --url https://api.hellotext.com/v1/templates/TEMPLATE_ID \ + --header "Authorization: Bearer $HELLOTEXT_API_TOKEN" +``` + +Interpreta los estados principales de esta forma: + +- `pending`: Meta todavía está revisando la plantilla de WhatsApp. +- `approved`: la plantilla puede utilizarse para envíos compatibles por WhatsApp. +- `rejected`: revisa el contenido o la categoría antes de depender de ella. + +Las plantillas exclusivas para SMS no pasan por la aprobación de Meta. Una plantilla `any` puede seguir pendiente cuando incluye una versión para WhatsApp. + +Una respuesta exitosa de `POST /v1/templates` solo confirma que Hellotext creó la plantilla e inició el flujo de sincronización correspondiente. No confirma que WhatsApp la haya aprobado. + +## 7. Envía una plantilla aprobada + +Envía la plantilla mediante la API de mensajes. Especifica la tecnología cuando el canal sea importante: + +```bash +curl --request POST \ + --url https://api.hellotext.com/v1/messages \ + --header "Authorization: Bearer $HELLOTEXT_API_TOKEN" \ + --header "Content-Type: application/json" \ + --data '{ + "profile": "PROFILE_ID", + "technology": "whatsapp", + "template": { + "id": "TEMPLATE_ID", + "shortlinks": { + "order": "https://shop.example.com/account/orders/1001" + } + } + }' +``` + +Cuando envías `template`, Hellotext utiliza el cuerpo de la plantilla e ignora un `body` separado en el mensaje. Puedes enviar el ID de la plantilla como string cuando no tenga links cortos dinámicos. + +Una solicitud válida responde con: + +```json +{ + "status": "received" +} +``` + +Esto significa que el mensaje fue aceptado para su procesamiento. No confirma la entrega por parte de WhatsApp o del operador móvil. Recupera el mensaje o revisa por separado la conversación y su estado de entrega. + +En WhatsApp, un mensaje libre solo puede enviarse mientras la ventana de atención del cliente está abierta. Se requiere una plantilla aprobada de WhatsApp para iniciar una conversación o enviar fuera de esa ventana. + +Consulta [Mensajes con plantillas](https://www.hellotext.com/api#templates_a_message) y [Enviar un mensaje](https://www.hellotext.com/api#create_a_message). + +## 8. Actualiza o retira una plantilla de forma segura + +Usa `PATCH /v1/templates/:id` para modificar contenido compatible, como el cuerpo, header, footer, botones o tecnología de destino. + +Para plantillas de WhatsApp: + +- Los cambios de contenido pueden requerir otra revisión de Meta. +- No asumas que el contenido modificado está activo mientras su estado siga pendiente. +- No uses una actualización para renombrar una plantilla de WhatsApp; crea una plantilla nueva cuando deba cambiar su identidad reutilizable. +- Cambiar la tecnología de destino puede hacer que la plantilla deje de estar disponible en el canal anterior. + +Usa `DELETE /v1/templates/:id` únicamente cuando la plantilla estándar reutilizable ya no deba estar disponible. No elimines una plantilla solamente para cambiar su texto y verifica que ninguna campaña, ruta, playbook o proceso del backend siga dependiendo de su ID. + +Consulta [Actualizar una plantilla](https://www.hellotext.com/api#update_a_template) y [Eliminar una plantilla](https://www.hellotext.com/api#delete_a_template). + +## 9. Soluciona errores frecuentes + +Revisa estas causas antes de reintentar: + +- **`401`:** el token de la API falta, es inválido o fue revocado. +- **`403`:** el negocio no puede realizar la operación solicitada de la API. +- **`422` en `technology`:** WhatsApp no está conectado o el valor no es `sms`, `whatsapp` o `any`. +- **`422` en componentes:** una plantilla exclusiva para SMS contiene header, footer o botones, o algún componente supera su límite. +- **`422` en `body`:** el cuerpo está vacío, es demasiado largo o contiene un parámetro aislado para WhatsApp. +- **`422` en botones:** falta la URL, teléfono, valor para copiar o texto correspondiente, o se superó la cantidad permitida. +- **Falla la solicitud del mensaje:** la plantilla no pertenece al negocio, falta un link corto dinámico, no se puede contactar al perfil del cliente o el canal elegido no está disponible. +- **El mensaje de WhatsApp no se envía:** la plantilla o su último cambio todavía está pendiente, fue rechazado, está pausado o no está disponible en Meta. + +No reintentes sin cambios un error de validación. Corrige primero el parámetro indicado. Usa [Soluciona una integración propia]({% link _developers/troubleshoot-custom-integration.md %}) para revisar autenticación, logs, reintentos y diagnósticos completos. + +## Guías relacionadas + +- [Resumen para desarrolladores y API]({% link _developers/developers-overview.md %}) +- [Enviar SMS con la API]({% link _developers/send-sms-with-api.md %}) +- [Fundamentos del canal de WhatsApp]({% link _numbers/whatsapp-channel-fundamentals.md %}) +- [Resumen del editor de mensajes]({% link _numbers/message-editor-overview.md %}) +- [Etiquetas de personalización]({% link _audience/personalization-tags.md %}) +- [Soluciona plantillas de WhatsApp]({% link _troubleshooting-deliverability/troubleshoot-whatsapp-templates.md %}) From ef17a46d29f56e12d66b169a2a10a50102aa68f3 Mon Sep 17 00:00:00 2001 From: Martin Caetano Date: Fri, 7 Aug 2026 14:32:46 -0300 Subject: [PATCH 2/2] Clarify pending WhatsApp template edits --- _i18n/en/developers/templates-with-api.md | 4 +++- _i18n/es/developers/templates-with-api.md | 4 +++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/_i18n/en/developers/templates-with-api.md b/_i18n/en/developers/templates-with-api.md index 0ac7e00d..41b7cf64 100644 --- a/_i18n/en/developers/templates-with-api.md +++ b/_i18n/en/developers/templates-with-api.md @@ -162,6 +162,8 @@ Treat the main states as follows: SMS-only templates do not go through Meta approval. An `any` template can still be pending when it includes a WhatsApp version. +If a pending edit belongs to a template that already has an approved version, messages can continue using that active approved version. A new template without an approved version must wait for approval before it can be used. + Do not interpret a successful `POST /v1/templates` response as WhatsApp approval. It confirms that Hellotext created the template and started the applicable synchronization flow. ## 7. Send an approved template @@ -227,7 +229,7 @@ Check these causes before retrying: - **`422` on `body`:** the body is blank, too long, or contains a dangling WhatsApp parameter. - **`422` on buttons:** a button is missing its matching URL, phone, copy value, or text, or the allowed count was exceeded. - **Message request fails:** the template does not belong to the business, a dynamic short link is missing, the customer profile cannot be reached, or the selected channel is unavailable. -- **WhatsApp message does not send:** the template or latest change is still pending, rejected, paused, or otherwise unavailable in Meta. +- **WhatsApp message does not send:** no approved version exists because the template is new and pending or was rejected, or the approved version is paused, disabled, or otherwise unavailable in Meta. A pending edit does not block a previously approved version. Do not retry an unchanged validation error. Correct the named parameter first. Use [Troubleshoot a custom integration]({% link _developers/troubleshoot-custom-integration.md %}) for authentication, logging, retries, and end-to-end diagnostics. diff --git a/_i18n/es/developers/templates-with-api.md b/_i18n/es/developers/templates-with-api.md index 0a90f84e..a3498076 100644 --- a/_i18n/es/developers/templates-with-api.md +++ b/_i18n/es/developers/templates-with-api.md @@ -162,6 +162,8 @@ Interpreta los estados principales de esta forma: Las plantillas exclusivas para SMS no pasan por la aprobación de Meta. Una plantilla `any` puede seguir pendiente cuando incluye una versión para WhatsApp. +Si una edición pendiente pertenece a una plantilla que ya tiene una versión aprobada, los mensajes pueden seguir utilizando esa versión aprobada activa. Una plantilla nueva sin versión aprobada debe esperar la aprobación antes de poder utilizarse. + Una respuesta exitosa de `POST /v1/templates` solo confirma que Hellotext creó la plantilla e inició el flujo de sincronización correspondiente. No confirma que WhatsApp la haya aprobado. ## 7. Envía una plantilla aprobada @@ -227,7 +229,7 @@ Revisa estas causas antes de reintentar: - **`422` en `body`:** el cuerpo está vacío, es demasiado largo o contiene un parámetro aislado para WhatsApp. - **`422` en botones:** falta la URL, teléfono, valor para copiar o texto correspondiente, o se superó la cantidad permitida. - **Falla la solicitud del mensaje:** la plantilla no pertenece al negocio, falta un link corto dinámico, no se puede contactar al perfil del cliente o el canal elegido no está disponible. -- **El mensaje de WhatsApp no se envía:** la plantilla o su último cambio todavía está pendiente, fue rechazado, está pausado o no está disponible en Meta. +- **El mensaje de WhatsApp no se envía:** no existe una versión aprobada porque la plantilla es nueva y sigue pendiente o fue rechazada, o la versión aprobada está pausada, deshabilitada o no está disponible en Meta. Una edición pendiente no bloquea una versión aprobada previamente. No reintentes sin cambios un error de validación. Corrige primero el parámetro indicado. Usa [Soluciona una integración propia]({% link _developers/troubleshoot-custom-integration.md %}) para revisar autenticación, logs, reintentos y diagnósticos completos.