WhatsApp Notification

Envía notificaciones transaccionales desde tu servidor con un número de WhatsApp exclusivo de tu empresa y plantillas de utilidad aprobadas. El destinatario debe ser un celular de Colombia y haber autorizado estas comunicaciones. No necesitas un agente de IA.

1. Prepara tu cuenta

En Canales, configura y verifica tu remitente de WhatsApp. Su cuenta de Meta o Twilio debe estar asignada exclusivamente a tu cliente en talkHero. En Plantillas WhatsApp, crea o importa las plantillas de utilidad y confirma su aprobación. Las variables deben coincidir exactamente con la plantilla.

Con Meta, el remitente puede usar formato internacional, incluido un número virtual asignado por Meta, si está habilitado y verificado en tu cuenta. Los destinatarios de este producto siguen siendo celulares de Colombia. talkHero no asigna ni garantiza la disponibilidad de números virtuales.

El administrador de talkHero asigna el contrato: mensajes incluidos, paquetes prepagados, límite de consumo y precio por mensaje adicional. Los excedentes, si están habilitados, necesitan saldo. Los paquetes se definen en COP y pueden tener vigencia o no vencer.

2. Crea una clave de API

En Configuración → API keys, escribe el nombre de tu integración y pulsa Usar WhatsApp Notification. El acceso directo selecciona Producción, reemplaza los permisos seleccionados por los cuatro indicados abajo y abre el detalle para que los revises. Luego pulsa Crear API key.

WhatsApp Notification utiliza permisos compartidos con otros servicios. Si los seleccionas manualmente, marca estas casillas:

Los permisos conservan los límites del contrato y del cliente; el acceso directo no crea un permiso exclusivo del endpoint de notificaciones.

Guarda la clave en el servidor de tu aplicación. No la incluyas en JavaScript público, aplicaciones de kiosco accesibles al usuario ni repositorios. Las claves de pruebas no admiten este endpoint: las plantillas pertenecen a una cuenta real de WhatsApp. El entorno de pruebas de Mensajes sigue disponible para simulaciones generales.

3. Solicita una notificación

Base publicada configurada de la aplicación: https://my.talkhero.app/api. Usa POST /v1/whatsapp/notifications con estas cabeceras:

Authorization: Bearer TU_CLAVE_DE_PRODUCCION
Content-Type: application/json
Idempotency-Key: identificador-estable-del-evento

Cuerpo de ejemplo; reemplaza los marcadores por datos propios:

{
  "channel_account_id": "UUID_DEL_CANAL",
  "to": "+573XXXXXXXXX",
  "recipient_name": "Nombre del destinatario",
  "template": {
    "id": "UUID_DE_LA_PLANTILLA_EN_TALKHERO",
    "variables": {
      "1": "Valor que espera la plantilla"
    }
  },
  "client_reference": "referencia-del-evento-en-tu-sistema"
}

recipient_name es opcional; no cambia el nombre de un contacto existente. El cliente es responsable de obtener y conservar la autorización del destinatario según su contrato. Puedes enviar directamente, incluso al primer destinatario, sin registrar esa autorización en talkHero. El envío no crea un registro de consentimiento.

Las bajas registradas se comprueban al recibir la solicitud y nuevamente antes de despacharla. Un envío nunca reactiva a quien retiró su autorización: una nueva autorización comprobada debe registrarse por separado en /v1/consents.

Por compatibilidad, la API sigue admitiendo el campo opcional consent con evidence, policy_version y observed_at. Solo si lo utilizas necesitas agregar Consentimientos → Escritura (consents:write). La evidencia y la fecha deben corresponder a una autorización real; no se admite una fecha futura.

Si la plantilla exige un encabezado multimedia, admite template.header_media con url HTTPS pública y filename opcional para documentos. También admite template.file_id para un archivo privado gestionado en talkHero, con los permisos de archivos correspondientes. No mezcles ambas opciones.

La respuesta HTTP 202 devuelve la operación con id, state, settlement, quote, client_reference y replayed. Significa que la solicitud quedó registrada; no confirma que WhatsApp la haya entregado.

4. Reintenta sin duplicar

Genera una clave de idempotencia por notificación, de 8 a 120 caracteres, usando letras, números, punto, guion, guion bajo o dos puntos. Guarda la clave y el cuerpo en tu sistema antes del primer intento. Si la conexión se interrumpe, repite exactamente la misma solicitud con la misma clave. talkHero devuelve la operación existente sin otro envío ni otro consumo.

client_reference sirve para correlacionar eventos, pero no sustituye Idempotency-Key. Un evento nuevo necesita otra clave. Cambiar los datos conservando una clave usada devuelve HTTP 409. No generes una clave nueva para resolver un timeout ni un estado uncertain.

5. Confirma entrega y consumo

Consulta GET /v1/messages/ID_DE_OPERACION con messages:read. Los estados son:

settlement indica held (reserva), captured (consumo confirmado) o released (reserva liberada). Un fallo sin confirmación de costo puede conservar la reserva. prepaid_consumed_units muestra las unidades consumidas del paquete; charged_amount muestra el cargo adicional al saldo. No sumes las unidades del paquete como un segundo cobro.

Consulta paquetes con GET /v1/commerce/packages?environment=live, contrato con GET /v1/commerce/contract?environment=live y saldo con GET /v1/commerce/balances. Cada paquete conserva el precio y la vigencia con que se acreditó. La tarifa al cliente es distinta del costo del proveedor.

6. Recibe resultados por webhook

Configura un endpoint HTTPS de tu servidor en /v1/webhooks, entorno live, evento communication.updated. Administrarlo por API requiere webhooks:write; consultar su historial requiere webhooks:read. Estos permisos no son necesarios en la clave que solo envía notificaciones.

Verifica la firma HMAC sobre los bytes originales del cuerpo, valida el timestamp y deduplica event_id antes de procesar efectos. Los eventos pueden repetirse o llegar fuera de orden. El campo data.client_reference corresponde a la referencia de tu sistema y data.operation_id a la operación en talkHero. Conserva los estados finales al recibir un evento anterior.

Errores que debes resolver

La aprobación almacenada de una plantilla dura 24 horas; la sincronización la actualiza y puedes solicitar la consulta desde el panel. El transporte vuelve a revisar la plantilla antes del envío. Una aprobación de plantilla no constituye autorización del destinatario.