Mensagens transacionais e cascatas

Mensagens transacionais são confirmações de pedido, códigos de acesso e avisos de entrega. O cliente está esperando por elas, por isso saem imediatamente e por uma fila separada: uma campanha grande não as atrasa. A cascata envia uma mesma mensagem por vários canais, um após o outro. Por exemplo, primeiro WhatsApp e, se não for entregue em 2 minutos, SMS.

Você pode enviar essa mensagem a partir de uma jornada ou do seu servidor pela API.

Modelo transacional

Para que uma mensagem seja considerada transacional, marque Mensagem transacional no modelo dela. Essa mensagem é enviada sem verificar a inscrição, os limites de frequência e o horário silencioso. Os e-mails pelo serviço de e-mail do OneTrace.ru são enviados sem aquecimento e em um fluxo separado, sem link de cancelamento de inscrição nos cabeçalhos.

Não marque publicidade dessa forma: isso viola os direitos dos destinatários e prejudica a reputação do remetente.

Mesmo uma mensagem transacional não é enviada se o canal do destinatário estiver fechado:

Essa mensagem recebe o status “Ignorada” com o motivo “canal bloqueado para o destinatário”. O canal é reaberto quando o cliente se inscreve de novo, por exemplo, toca em “Start” no bot. Uma reclamação de spam não fecha o canal: os e-mails sobre pedidos para esse endereço continuam chegando.

Envio pela API

Seu servidor envia a mensagem com a requisição POST /api/v1/messages. É necessária uma chave secreta com a permissão “Envio de mensagens avulsas”; veja Chaves 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}
  }'

A resposta 202 contém o id da mensagem e o status dela. O status atual é retornado por GET /api/v1/messages/{id}: queued, sent, delivered, failed, skipped e outros, com o motivo da omissão ou do erro.

• Repetir é seguro. Uma requisição com o mesmo cabeçalho Idempotency-Key retorna a mensagem já criada, e a segunda não é enviada. Use o número do pedido ou o id da operação.
• Limite por destinatário: 20 mensagens por hora pela API. Se for excedido, chega 429 com o cabeçalho Retry-After.
• Um modelo comum sem a marcação “Transacional” também pode ser enviado pela API. Nesse caso, todas as regras de mensagens são verificadas.

Na biblioteca PHP pronta, isso é $onetrace->messages()->send(Identity::email('anna@example.com'), 12, ['data' => [...]], 'order-A-1001'); no pacote para Laravel, messages()->send(...).

Cascata na jornada

Adicione à jornada o nó Envio em cascata do grupo “Ações”. No campo Canais em ordem, defina de 2 a 5 etapas. Para cada etapa, indique:

• Integração e Modelo do canal.
• Aguardar — o que considerar sucesso: “enviado”, “entregue” ou “lido”.
• Tempo de espera — para “entregue” e “lido”; por padrão, 15 minutos.

A cascata passa para a próxima etapa se:

• o perfil não tem endereço ou número para o canal, ou o canal dele está fechado — a etapa é pulada imediatamente e a mensagem não é criada;
• a mensagem não saiu: erro de envio ou omissão pelas regras de mensagens;
• o provedor informou que não houve entrega;
• dentro do tempo de espera não chegou a confirmação de entrega ou de leitura.

Nem todos os canais permitem aguardar a entrega e a leitura:

O nó tem duas saídas: chegou — a mensagem de uma das etapas atingiu o objetivo; falhou — nenhum canal funcionou. Enquanto a cascata está em andamento, o participante aguarda no nó.

O envio em cascata entrega uma mesma mensagem. Os modelos de jornada do tipo “Carrinho: push → e-mail → SMS” funcionam de outro jeito: neles, mensagens diferentes saem com pausas até o cliente fazer um pedido.

Cascata pela API

Em vez de template_id, envie steps — as mesmas etapas do nó da jornada:

{
  "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 aceita sent, delivered ou opened; as unidades de timeout são minute, hour, day, week. A resposta 202 contém o id da cascata, e GET /api/v1/messages/cascades/{id} retorna o estado dela:

• status — running, reached ou failed;
• a etapa atual step;
• o canal que funcionou — reached_channel;
• as mensagens das etapas messages.

Plano

As mensagens transacionais e o envio pela API estão disponíveis em todos os planos. A cascata está disponível a partir do plano “Crescimento”; veja Plano e cobrança. No “Inicial”, o nó na paleta do editor aparece com um cadeado, e a API responde 402. Se o plano for rebaixado, nas jornadas já em funcionamento é enviada apenas a primeira etapa da cascata.