diff --git a/_config.yml b/_config.yml index 6c7bd64b..871371fb 100644 --- a/_config.yml +++ b/_config.yml @@ -218,6 +218,7 @@ collections: - developers-overview.md - custom-store-integration.md - api.md + - send-messages-with-api.md - templates-with-api.md - products-and-inventory-with-api.md - orders-with-api.md diff --git a/_developers/send-messages-with-api.md b/_developers/send-messages-with-api.md new file mode 100644 index 00000000..869bebd1 --- /dev/null +++ b/_developers/send-messages-with-api.md @@ -0,0 +1,19 @@ +--- +languages: ["en", "es"] + +en: + title: Send messages with the API + description: Send individual free-form or template messages, choose the channel and recipient, and verify the final delivery state. +es: + title: Envía mensajes con la API + description: Envía mensajes individuales libres o con plantilla, elige el canal y el destinatario, y verifica el estado final de entrega. + +permalink: send-messages-with-api +permalink_es: enviar-mensajes-con-api + +layout: guide +topic: developers +popular: true +--- + +{% translate_file developers/send-messages-with-api.md %} diff --git a/_i18n/en/developers/developers-overview.md b/_i18n/en/developers/developers-overview.md index 869b444b..107ba516 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: +- [Send messages with the API]({% link _developers/send-messages-with-api.md %}) - [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 %}) @@ -45,11 +46,11 @@ Authorization: Bearer YOUR_TOKEN Never expose private tokens in browser code, public repositories, or client-side scripts. -## Send SMS from your system +## Send messages from your system -Use the messages API when your own system needs to send reminders, confirmations, or notifications by SMS. +Use the Messages API when your own system needs to send an individual free-form or template message through a compatible channel. -Keep reading: [Send SMS with the API]({% link _developers/send-sms-with-api.md %}). +Start with [Send messages with the API]({% link _developers/send-messages-with-api.md %}). For SMS-specific length, encoding, costs, and limits, read [Send SMS with the API]({% link _developers/send-sms-with-api.md %}). ## Track customer activity diff --git a/_i18n/en/developers/send-messages-with-api.md b/_i18n/en/developers/send-messages-with-api.md new file mode 100644 index 00000000..cdbb5cfb --- /dev/null +++ b/_i18n/en/developers/send-messages-with-api.md @@ -0,0 +1,210 @@ +Use the Messages API when your backend needs to send one message to one customer profile, for example a confirmation, support follow-up, or transactional notification. + +For a one-time message to an audience, create a campaign instead. For autonomous messages based on signals and customer behavior, use a playbook. Sending through the API does not bypass consent, channel availability, messaging windows, account limits, or provider rules. + +Use the [Send a Message reference](https://www.hellotext.com/api#create_a_message) for the complete endpoint contract. This guide explains how to make the main implementation decisions and verify the result. + +## Before you start + +Prepare: + +- A private API authorization token stored only on your backend. +- An active Hellotext business and the channel integrations you intend to use. +- A valid customer profile ID or, for a phone-based send, a destination number. +- Either a free-form message body or an existing compatible template. +- Valid consent and contactability for the message purpose and channel. +- Publicly accessible URLs for any attachments. + +Create a token under **Settings → Authorizations** and send it as a bearer token: + +```text +Authorization: Bearer YOUR_TOKEN +``` + +Never expose this token in Hellotext.js, browser code, a mobile application, or a public repository. + +## 1. Choose a free-form message or a template + +### Free-form message + +Send `body` without `template` when the selected channel allows your business to write the message directly. + +This is appropriate for SMS and for supported conversational channels while their provider rules allow a free-form reply. On WhatsApp, a free-form message can only be sent while the customer service window is open. The 24-hour window starts or refreshes when the customer messages the business. + +### Template message + +Send `template` when you want reusable content, customer-property personalization, or dynamic short links. An approved WhatsApp template is required to initiate a WhatsApp conversation or send outside the customer service window. + +When `template` is present, Hellotext uses the template content and ignores a separate `body`. Do not create a new template for each send; create and approve reusable templates first. + +See [Create and send templates with the API]({% link _developers/templates-with-api.md %}) for template creation, Meta approval, property tags, and dynamic short links. + +## 2. Select the technology and channel + +Set `technology` explicitly so routing and provider requirements are predictable. The current Messages endpoint supports: + +- `sms` +- `whatsapp` +- `instagram` +- `mercadolibre` + +The corresponding integration must be active for the business. The customer profile must also be reachable through the selected technology. + +`technology` and `origin` solve different problems: + +- **`technology`:** selects the messaging technology. +- **`origin`:** optionally selects one exact configured channel or sender within that technology. + +Omit `origin` when Hellotext can choose a compatible configured channel. Include it when the business has multiple senders or connected accounts and your integration must use a specific one. The origin must belong to the business and match `technology`. + +## 3. Identify the customer profile and destination + +Prefer `profile` when your system already knows the Hellotext customer profile ID. Hellotext uses the selected technology and origin to resolve a compatible destination on that profile. + +For phone-based sends, you can use `destination` without `profile`. Send the number in international E.164 format, for example `+14155552671`. Hellotext looks for a customer profile with that phone number and creates one if none exists. + +When a customer profile has more than one phone number and you need a particular one, send both `profile` and `destination`. For Instagram or Mercado Libre, use a reachable customer profile and let Hellotext resolve the channel-specific identity. + +Finding or creating a customer profile does not subscribe it to marketing. Identity, verification, and consent remain separate. + +## 4. Send a free-form message + +This example sends a WhatsApp reply to a known customer profile. Use it only while that customer has an open service window: + +```bash +curl --request POST \ + --url https://api.hellotext.com/v1/messages \ + --header "Authorization: Bearer $HELLOTEXT_API_TOKEN" \ + --header "Content-Type: application/json" \ + --data '{ + "technology": "whatsapp", + "profile": "PROFILE_ID", + "body": "Thanks for contacting us. Your return request is ready for review." + }' +``` + +Hellotext chooses an active WhatsApp origin when you omit `origin`. To force a specific configured WhatsApp sender, add its channel identifier: + +```json +{ + "technology": "whatsapp", + "origin": "+14155552671", + "profile": "PROFILE_ID", + "body": "Thanks for contacting us. Your return request is ready for review." +} +``` + +For an SMS-specific implementation, including length, encoding, links, cost, and new-business limits, see [Send SMS with the API]({% link _developers/send-sms-with-api.md %}). + +## 5. Send a template message + +This example sends an approved WhatsApp template and supplies the destination for its named dynamic short link: + +```bash +curl --request POST \ + --url https://api.hellotext.com/v1/messages \ + --header "Authorization: Bearer $HELLOTEXT_API_TOKEN" \ + --header "Content-Type: application/json" \ + --data '{ + "technology": "whatsapp", + "profile": "PROFILE_ID", + "template": { + "id": "TEMPLATE_ID", + "shortlinks": { + "order": "https://shop.example.com/account/orders/1001" + } + } + }' +``` + +You can send `template` as the template ID string when it has no dynamic short links. When it does, use the object form and provide every required name under `template.shortlinks`. + +The template must belong to the business, support the selected technology, and have an active approved version when WhatsApp approval is required. A pending edit does not block an older approved version, but a new pending template cannot be used yet. + +## 6. Add attachments when the channel supports them + +Send attachment URLs in the top-level `attachments` array: + +```json +{ + "technology": "whatsapp", + "profile": "PROFILE_ID", + "body": "Here is the document you requested.", + "attachments": [ + "https://files.example.com/return-instructions.pdf" + ] +} +``` + +Each URL must be publicly accessible so Hellotext can download and store the file. Supported formats and size limits differ by channel. SMS does not support attachments and ignores this parameter. + +Check the current [attachment requirements](https://www.hellotext.com/api#create_a_message_attachments) before sending files in production. + +## 7. Interpret the accepted response + +A valid request returns: + +```json +{ + "status": "received" +} +``` + +This means Hellotext accepted the request and queued it for asynchronous processing. It does not mean that the provider accepted the message or delivered it to the customer. + +Outbound message states include: + +- `pending`: the message exists and is waiting for processing. +- `routed`: Hellotext sent it to the external provider. +- `delivered`: the provider confirmed delivery. +- `failed`: the provider or delivery flow could not complete the send. + +The `received` state on a message object describes an inbound message sent by the customer to the business. It is different from the `{ "status": "received" }` API acknowledgement. + +Use [List all Messages](https://www.hellotext.com/api#list_all_messages) to find recent messages, then [Retrieve a Message](https://www.hellotext.com/api#retrieve_a_message) to inspect its final state and timestamps. You can also review the customer conversation in Inbox. + +## 8. Retry without creating duplicates + +The endpoint does not accept an idempotency key. Your integration must prevent duplicate sends. + +- Do not retry a `422` response without correcting the invalid parameter. +- If the connection fails before you receive a response, treat the result as uncertain instead of immediately sending the same message again. +- Record the business, customer profile, technology, template or body fingerprint, request time, and response. +- Check recent messages or the Inbox conversation before retrying an uncertain request. +- Retry a provider failure only after correcting or waiting out the reported condition. + +Even after the request is accepted, asynchronous processing can stop because of account limits, an unavailable channel, an invalid origin, a closed WhatsApp service window, template state, or a provider failure. + +## 9. Troubleshoot common problems + +- **`401 Unauthorized`:** the token is missing, invalid, revoked, or belongs to another business. +- **`422` on `technology`:** the value is unsupported or the matching integration is not active. +- **`422` on `destination`:** the phone number is missing or invalid when no customer profile is supplied. +- **`422` on `body`:** neither a usable body nor a valid template was provided. +- **Accepted but no outbound message appears:** verify the customer profile ID, origin, account limits, and channel availability. +- **WhatsApp message fails:** confirm the service window is open for free-form content or use an active approved template. +- **Template request fails:** confirm the template belongs to the business and supply every required dynamic short link. +- **Message reaches `failed`:** inspect the conversation and provider reason before deciding whether another attempt is appropriate. + +See [Why a message did not send]({% link _troubleshooting-deliverability/why-a-message-did-not-send.md %}) for channel and delivery diagnosis. Use [Troubleshoot a custom integration]({% link _developers/troubleshoot-custom-integration.md %}) for authentication, logging, and retry problems. + +## Go-live checklist + +Before enabling the integration in production: + +1. Send to a customer profile or number controlled by your team. +2. Confirm the request returns `status: received`. +3. Verify the message appears in the expected Inbox conversation. +4. Confirm the intended technology, origin, destination, and rendered content. +5. Wait for the final `delivered` or `failed` state. +6. Test a corrected validation error and an uncertain-response path without producing duplicates. +7. Confirm consent and channel-window rules for each production use case. + +## Related guides + +- [Developers and API overview]({% link _developers/developers-overview.md %}) +- [Create and send templates with the API]({% link _developers/templates-with-api.md %}) +- [Send SMS with the API]({% link _developers/send-sms-with-api.md %}) +- [Who can you message?]({% link _audience/consent-and-subscriber-status.md %}) +- [WhatsApp channel fundamentals]({% link _numbers/whatsapp-channel-fundamentals.md %}) +- [Hellotext API reference](https://www.hellotext.com/api) diff --git a/_i18n/en/developers/send-sms-with-api.md b/_i18n/en/developers/send-sms-with-api.md index 120d8658..175fa3c8 100644 --- a/_i18n/en/developers/send-sms-with-api.md +++ b/_i18n/en/developers/send-sms-with-api.md @@ -153,6 +153,7 @@ The [API errors section](https://www.hellotext.com/api#errors) explains the resp ## Related guides +- [Send messages with the API]({% link _developers/send-messages-with-api.md %}) - [Integrate a custom store]({% link _developers/custom-store-integration.md %}) - [Hellotext API reference](https://www.hellotext.com/api) - [Tracking events]({% link _developers/tracking-events.md %}) diff --git a/_i18n/en/developers/templates-with-api.md b/_i18n/en/developers/templates-with-api.md index 41b7cf64..728b3ce8 100644 --- a/_i18n/en/developers/templates-with-api.md +++ b/_i18n/en/developers/templates-with-api.md @@ -236,6 +236,7 @@ Do not retry an unchanged validation error. Correct the named parameter first. U ## Related guides - [Developers and API overview]({% link _developers/developers-overview.md %}) +- [Send messages with the API]({% link _developers/send-messages-with-api.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 %}) diff --git a/_i18n/es/developers/developers-overview.md b/_i18n/es/developers/developers-overview.md index e706ee5e..aecd90ea 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: +- [Envía mensajes con la API]({% link _developers/send-messages-with-api.md %}) - [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 %}) @@ -45,11 +46,11 @@ Authorization: Bearer TU_TOKEN Nunca expongas tokens privados en código del navegador, repositorios públicos o scripts del lado del cliente. -## Envía SMS desde tu sistema +## Envía mensajes desde tu sistema -Usa la API de mensajes cuando tu propio sistema necesite enviar recordatorios, confirmaciones o notificaciones por SMS. +Usa la API de mensajes cuando tu propio sistema necesite enviar un mensaje individual libre o con plantilla mediante un canal compatible. -Sigue leyendo: [Enviar SMS con la API]({% link _developers/send-sms-with-api.md %}). +Comienza con [Envía mensajes con la API]({% link _developers/send-messages-with-api.md %}). Para conocer longitud, codificación, costos y límites específicos de SMS, consulta [Enviar SMS con la API]({% link _developers/send-sms-with-api.md %}). ## Registra actividad de clientes diff --git a/_i18n/es/developers/send-messages-with-api.md b/_i18n/es/developers/send-messages-with-api.md new file mode 100644 index 00000000..939187e6 --- /dev/null +++ b/_i18n/es/developers/send-messages-with-api.md @@ -0,0 +1,210 @@ +Usa la API de mensajes cuando tu backend necesite enviar un mensaje a un perfil del cliente, por ejemplo una confirmación, un seguimiento de soporte o una notificación transaccional. + +Para enviar un mensaje puntual a una audiencia, crea una campaña. Para mensajes autónomos basados en señales y comportamiento del cliente, usa un playbook. Enviar mediante la API no evita el consentimiento, la disponibilidad del canal, las ventanas de mensajería, los límites de la cuenta ni las reglas del proveedor. + +Usa la [referencia para enviar un mensaje](https://www.hellotext.com/api#create_a_message) para consultar el contrato completo del endpoint. Esta guía explica cómo tomar las principales decisiones de implementación y verificar el resultado. + +## Antes de comenzar + +Prepara: + +- Un token privado de autorización para la API guardado únicamente en tu backend. +- Un negocio activo en Hellotext y las integraciones de canales que piensas utilizar. +- Un ID válido del perfil del cliente o, para un envío telefónico, un número de destino. +- Un cuerpo de mensaje libre o una plantilla compatible existente. +- Consentimiento y contactabilidad válidos para el propósito y el canal del mensaje. +- URLs accesibles públicamente para los archivos adjuntos. + +Crea un token en **Configuración → Autorizaciones** y envíalo como bearer token: + +```text +Authorization: Bearer YOUR_TOKEN +``` + +Nunca expongas este token en Hellotext.js, código del navegador, una aplicación móvil ni un repositorio público. + +## 1. Elige un mensaje libre o una plantilla + +### Mensaje libre + +Envía `body` sin `template` cuando el canal seleccionado permita que el negocio escriba el mensaje directamente. + +Esto es apropiado para SMS y para canales conversacionales compatibles mientras las reglas de su proveedor permitan una respuesta libre. En WhatsApp, un mensaje libre solo puede enviarse mientras la ventana de atención esté abierta. La ventana de 24 horas comienza o se renueva cuando el cliente escribe al negocio. + +### Mensaje con plantilla + +Envía `template` cuando necesites contenido reutilizable, personalización con propiedades del cliente o links cortos dinámicos. Se requiere una plantilla de WhatsApp aprobada para iniciar una conversación por WhatsApp o enviar fuera de la ventana de atención. + +Cuando envías `template`, Hellotext utiliza el contenido de la plantilla e ignora un `body` separado. No crees una plantilla nueva para cada envío; crea y aprueba primero plantillas reutilizables. + +Consulta [Crea y envía plantillas con la API]({% link _developers/templates-with-api.md %}) para conocer la creación, la aprobación de Meta, las etiquetas de propiedades y los links cortos dinámicos. + +## 2. Selecciona la tecnología y el canal + +Establece `technology` explícitamente para que el enrutamiento y los requisitos del proveedor sean predecibles. El endpoint actual de mensajes admite: + +- `sms` +- `whatsapp` +- `instagram` +- `mercadolibre` + +La integración correspondiente debe estar activa en el negocio. El perfil del cliente también debe ser contactable mediante la tecnología elegida. + +`technology` y `origin` resuelven problemas diferentes: + +- **`technology`:** selecciona la tecnología de mensajería. +- **`origin`:** selecciona opcionalmente un canal o remitente configurado específico dentro de esa tecnología. + +Omite `origin` cuando Hellotext pueda elegir un canal configurado compatible. Inclúyelo cuando el negocio tenga varios remitentes o cuentas conectadas y tu integración deba utilizar uno específico. El origen debe pertenecer al negocio y coincidir con `technology`. + +## 3. Identifica el perfil del cliente y el destino + +Prefiere `profile` cuando tu sistema ya conozca el ID del perfil del cliente en Hellotext. Hellotext usa la tecnología y el origen elegidos para resolver un destino compatible en ese perfil. + +Para envíos telefónicos, puedes usar `destination` sin `profile`. Envía el número en formato internacional E.164, por ejemplo `+14155552671`. Hellotext busca un perfil del cliente con ese teléfono y crea uno si no existe. + +Cuando un perfil del cliente tenga más de un teléfono y necesites uno en particular, envía tanto `profile` como `destination`. Para Instagram o Mercado Libre, usa un perfil del cliente contactable y deja que Hellotext resuelva la identidad específica del canal. + +Encontrar o crear un perfil del cliente no lo suscribe a comunicaciones de marketing. La identidad, la verificación y el consentimiento permanecen separados. + +## 4. Envía un mensaje libre + +Este ejemplo envía una respuesta por WhatsApp a un perfil del cliente conocido. Úsalo únicamente mientras ese cliente tenga una ventana de atención abierta: + +```bash +curl --request POST \ + --url https://api.hellotext.com/v1/messages \ + --header "Authorization: Bearer $HELLOTEXT_API_TOKEN" \ + --header "Content-Type: application/json" \ + --data '{ + "technology": "whatsapp", + "profile": "PROFILE_ID", + "body": "Gracias por contactarnos. Tu solicitud de devolución está lista para revisar." + }' +``` + +Hellotext elige un origen de WhatsApp activo cuando omites `origin`. Para usar un remitente de WhatsApp configurado específico, agrega el identificador de su canal: + +```json +{ + "technology": "whatsapp", + "origin": "+14155552671", + "profile": "PROFILE_ID", + "body": "Gracias por contactarnos. Tu solicitud de devolución está lista para revisar." +} +``` + +Para una implementación específica de SMS, incluida la longitud, codificación, links, costo y límites para negocios nuevos, consulta [Enviar SMS con la API]({% link _developers/send-sms-with-api.md %}). + +## 5. Envía un mensaje con plantilla + +Este ejemplo envía una plantilla aprobada de WhatsApp y proporciona el destino de su link corto dinámico con nombre: + +```bash +curl --request POST \ + --url https://api.hellotext.com/v1/messages \ + --header "Authorization: Bearer $HELLOTEXT_API_TOKEN" \ + --header "Content-Type: application/json" \ + --data '{ + "technology": "whatsapp", + "profile": "PROFILE_ID", + "template": { + "id": "TEMPLATE_ID", + "shortlinks": { + "order": "https://shop.example.com/account/orders/1001" + } + } + }' +``` + +Puedes enviar `template` como string con el ID de la plantilla cuando no tenga links cortos dinámicos. Cuando los tenga, usa la forma de objeto y proporciona cada nombre requerido dentro de `template.shortlinks`. + +La plantilla debe pertenecer al negocio, admitir la tecnología elegida y tener una versión aprobada activa cuando se requiera la aprobación de WhatsApp. Una edición pendiente no bloquea una versión aprobada anterior, pero una plantilla nueva pendiente todavía no puede utilizarse. + +## 6. Agrega archivos adjuntos cuando el canal los admita + +Envía las URLs de los archivos en el array `attachments` de nivel superior: + +```json +{ + "technology": "whatsapp", + "profile": "PROFILE_ID", + "body": "Aquí está el documento que solicitaste.", + "attachments": [ + "https://files.example.com/return-instructions.pdf" + ] +} +``` + +Cada URL debe ser accesible públicamente para que Hellotext pueda descargar y guardar el archivo. Los formatos admitidos y los límites de tamaño cambian según el canal. SMS no admite archivos adjuntos e ignora este parámetro. + +Revisa los [requisitos actuales para archivos adjuntos](https://www.hellotext.com/api#create_a_message_attachments) antes de enviar archivos en producción. + +## 7. Interpreta la respuesta de aceptación + +Una solicitud válida responde con: + +```json +{ + "status": "received" +} +``` + +Esto significa que Hellotext aceptó la solicitud y la encoló para procesarla de manera asíncrona. No significa que el proveedor haya aceptado el mensaje ni que lo haya entregado al cliente. + +Los estados de mensajes salientes incluyen: + +- `pending`: el mensaje existe y espera ser procesado. +- `routed`: Hellotext lo envió al proveedor externo. +- `delivered`: el proveedor confirmó la entrega. +- `failed`: el proveedor o el flujo de entrega no pudo completar el envío. + +El estado `received` en un objeto de mensaje describe un mensaje entrante enviado por el cliente al negocio. Es diferente de la confirmación `{ "status": "received" }` de la API. + +Usa [Listar todos los mensajes](https://www.hellotext.com/api#list_all_messages) para encontrar mensajes recientes y luego [Recuperar un mensaje](https://www.hellotext.com/api#retrieve_a_message) para revisar su estado final y sus marcas de tiempo. También puedes revisar la conversación del cliente en el Inbox. + +## 8. Reintenta sin crear duplicados + +El endpoint no acepta una clave de idempotencia. Tu integración debe evitar envíos duplicados. + +- No reintentes una respuesta `422` sin corregir el parámetro inválido. +- Si la conexión falla antes de recibir una respuesta, trata el resultado como incierto en lugar de volver a enviar inmediatamente el mismo mensaje. +- Registra el negocio, perfil del cliente, tecnología, plantilla o huella del cuerpo, hora de la solicitud y respuesta. +- Revisa los mensajes recientes o la conversación en el Inbox antes de reintentar una solicitud incierta. +- Reintenta una falla del proveedor solamente después de corregir la condición indicada o esperar a que finalice. + +Incluso después de aceptar la solicitud, el procesamiento asíncrono puede detenerse por límites de la cuenta, un canal no disponible, un origen inválido, una ventana de atención de WhatsApp cerrada, el estado de la plantilla o una falla del proveedor. + +## 9. Soluciona problemas frecuentes + +- **`401 Unauthorized`:** el token falta, es inválido, fue revocado o pertenece a otro negocio. +- **`422` en `technology`:** el valor no es compatible o la integración correspondiente no está activa. +- **`422` en `destination`:** el teléfono falta o es inválido cuando no se proporciona un perfil del cliente. +- **`422` en `body`:** no se proporcionó un cuerpo utilizable ni una plantilla válida. +- **La solicitud fue aceptada pero no aparece un mensaje saliente:** revisa el ID del perfil del cliente, el origen, los límites de la cuenta y la disponibilidad del canal. +- **El mensaje de WhatsApp falla:** confirma que la ventana de atención esté abierta para contenido libre o utiliza una plantilla aprobada activa. +- **La solicitud con plantilla falla:** confirma que la plantilla pertenezca al negocio y proporciona todos los links cortos dinámicos requeridos. +- **El mensaje llega a `failed`:** revisa la conversación y la causa del proveedor antes de decidir si corresponde otro intento. + +Consulta [Por qué no se envió un mensaje]({% link _troubleshooting-deliverability/why-a-message-did-not-send.md %}) para diagnosticar el canal y la entrega. Usa [Soluciona una integración propia]({% link _developers/troubleshoot-custom-integration.md %}) para problemas de autenticación, logs y reintentos. + +## Checklist antes de producción + +Antes de habilitar la integración en producción: + +1. Envía a un perfil del cliente o número controlado por tu equipo. +2. Confirma que la solicitud responda con `status: received`. +3. Verifica que el mensaje aparezca en la conversación esperada del Inbox. +4. Confirma la tecnología, origen, destino y contenido renderizado esperados. +5. Espera el estado final `delivered` o `failed`. +6. Prueba un error de validación corregido y una respuesta incierta sin producir duplicados. +7. Confirma las reglas de consentimiento y ventanas del canal para cada caso de producción. + +## Guías relacionadas + +- [Resumen para desarrolladores y API]({% link _developers/developers-overview.md %}) +- [Crea y envía plantillas con la API]({% link _developers/templates-with-api.md %}) +- [Enviar SMS con la API]({% link _developers/send-sms-with-api.md %}) +- [¿A quién puedes escribirle?]({% link _audience/consent-and-subscriber-status.md %}) +- [Fundamentos del canal de WhatsApp]({% link _numbers/whatsapp-channel-fundamentals.md %}) +- [Referencia de la API de Hellotext](https://www.hellotext.com/api) diff --git a/_i18n/es/developers/send-sms-with-api.md b/_i18n/es/developers/send-sms-with-api.md index c9d2b897..d3ad2f4b 100644 --- a/_i18n/es/developers/send-sms-with-api.md +++ b/_i18n/es/developers/send-sms-with-api.md @@ -153,6 +153,7 @@ La sección de [errores de la API](https://www.hellotext.com/api#errors) explica ## Guías relacionadas +- [Envía mensajes con la API]({% link _developers/send-messages-with-api.md %}) - [Integrar una tienda personalizada]({% link _developers/custom-store-integration.md %}) - [Referencia de la API de Hellotext](https://www.hellotext.com/api) - [Seguimiento de eventos]({% link _developers/tracking-events.md %}) diff --git a/_i18n/es/developers/templates-with-api.md b/_i18n/es/developers/templates-with-api.md index a3498076..cf26db78 100644 --- a/_i18n/es/developers/templates-with-api.md +++ b/_i18n/es/developers/templates-with-api.md @@ -236,6 +236,7 @@ No reintentes sin cambios un error de validación. Corrige primero el parámetro ## Guías relacionadas - [Resumen para desarrolladores y API]({% link _developers/developers-overview.md %}) +- [Envía mensajes con la API]({% link _developers/send-messages-with-api.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 %})