Mensajes transaccionales y envíos en cascada

Los mensajes transaccionales son confirmaciones de pedido, códigos de acceso y avisos de entrega. El cliente los espera, por eso se envían de inmediato y por una cola aparte: una campaña grande no los retrasa. El envío en cascada manda un mismo mensaje por varios canales, uno tras otro. Por ejemplo, primero WhatsApp y, si no se entrega en 2 minutos, SMS.

Puede enviar un mensaje así desde un recorrido o desde su servidor mediante la API.

Plantilla transaccional

Para que un mensaje se considere transaccional, marque Mensaje transaccional en su plantilla. Este mensaje se envía sin comprobar la suscripción, los límites de frecuencia ni el horario de silencio. Los correos del servicio de correo de OneTrace.ru se envían sin calentamiento y por un flujo aparte, sin enlace de baja en los encabezados.

No marque así la publicidad: vulnera los derechos de los destinatarios y perjudica la reputación del remitente.

Ni siquiera un mensaje transaccional se envía si el canal está cerrado para el destinatario:

Este mensaje recibe el estado «Omitido» con el motivo «canal bloqueado para el destinatario». El canal se vuelve a abrir cuando el cliente se suscribe de nuevo, por ejemplo, al pulsar «Start» en el bot. Una queja de spam no cierra el canal: los correos sobre pedidos siguen llegando a esa dirección.

Envío mediante la API

Su servidor envía el mensaje con la solicitud POST /api/v1/messages. Necesita una clave secreta con el permiso «Envío de mensajes individuales»; consulte Claves de API.

curl -X POST https://cdp.onetrace.ru/api/v1/messages \
  -H "Authorization: Bearer $CDP_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-A-1001" \
  -d '{
    "identity": {"type": "email", "value": "anna@example.com"},
    "template_id": 12,
    "traits": {"first_name": "Ana"},
    "data": {"order_id": "A-1001", "amount": 4990}
  }'

La respuesta 202 contiene el id del mensaje y su estado. GET /api/v1/messages/{id} devuelve el estado actual: queued, sent, delivered, failed, skipped y otros, con el motivo de la omisión o del error.

• Repetir es seguro. Una solicitud con el mismo encabezado Idempotency-Key devuelve el mensaje ya creado y no se envía un segundo. Use el número de pedido o el id de la operación.
• Límite por destinatario: 20 mensajes por hora mediante la API. Si se supera, llega 429 con el encabezado Retry-After.
• Una plantilla normal sin la marca «Transaccional» también se puede enviar mediante la API. En ese caso se comprueban todas las reglas de mensajería.

En la biblioteca para PHP lista para usar es $onetrace->messages()->send(Identity::email('anna@example.com'), 12, ['data' => [...]], 'order-A-1001'), y en el paquete para Laravel, messages()->send(...).

Envío en cascada en un recorrido

Añada al recorrido el nodo Envío en cascada del grupo «Acciones». En el campo Canales por orden, defina de 2 a 5 pasos. Para cada paso indique:

• La Integración y la Plantilla del canal.
• Esperar a: qué se considera un éxito, «enviado», «entregado» o «leído».
• Tiempo de espera: para «entregado» y «leído», 15 minutos de forma predeterminada.

La cascada pasa al siguiente paso si:

• el perfil no tiene dirección o número para el canal, o el canal está cerrado para él: el paso se omite de inmediato y no se crea ningún mensaje;
• el mensaje no salió: error de envío u omisión por las reglas de mensajería;
• el proveedor informó de que no se entregó;
• no llegó la confirmación de entrega o de lectura dentro del tiempo de espera.

No en todos los canales se puede esperar la entrega y la lectura:

El nodo tiene dos salidas: llegó, el mensaje de uno de los pasos alcanzó su objetivo; error, ningún canal funcionó. Mientras la cascada está en curso, el participante espera en el nodo.

El envío en cascada entrega un mismo mensaje. Las plantillas de recorrido como «Carrito: push → correo → SMS» funcionan de otro modo: en ellas se envían mensajes distintos con pausas hasta que el cliente hace el pedido.

Envío en cascada mediante la API

En lugar de template_id, envíe steps, los mismos pasos que en el nodo del recorrido:

{
  "identity": {"type": "phone", "value": "+79991234567"},
  "steps": [
    {"integration_id": 3, "template_id": 21, "wait_for": "delivered", "timeout": {"amount": 2, "unit": "minute"}},
    {"integration_id": 4, "template_id": 22, "wait_for": "sent"}
  ],
  "data": {"code": "482913"}
}

wait_for admite sent, delivered u opened; las unidades de timeout son minute, hour, day y week. La respuesta 202 contiene el id de la cascada, y GET /api/v1/messages/cascades/{id} devuelve su estado:

• status: running, reached o failed;
• el paso actual, step;
• el canal que funcionó, reached_channel;
• los mensajes de los pasos, messages.

Plan

Los mensajes transaccionales y el envío mediante la API están disponibles en todos los planes. El envío en cascada, a partir del plan «Crecimiento»; consulte Plan y facturación. En «Inicio», el nodo aparece con un candado en la paleta del editor y la API responde 402. Si se baja de plan, en los recorridos que ya están en marcha solo se envía el primer paso de la cascada.