How to send a transactional Failover message

Use POST /failover/transactional when your Failover flow includes transactional Viber steps that must use an approved Rakuten BM template (July 2026 compliance).

Legacy POST /failover is unchanged for promotional/session Viber with a free-form message body.

Base URL and auth

POST https://connect.routee.net/failover/transactional
Authorization: Bearer {access_token}
Content-Type: application/json

Same OAuth and roles as legacy Failover (MT_ROLE_FAILOVER plus SMS/Viber/Voice as needed).

Before you send

Create and get an Approved template — Rakuten Viber transactional templates.
Note your Viber senderInfoTrackingId (Routee Platform → Applications).
Choose destination to (E.164).

Example — template Viber, then SMS

{
  "flow": [
    {
      "type": "Viber",
      "senderInfoTrackingId": "your-sender-info-tracking-id",
      "to": "+306912345678",
      "templateId": "0aac888f-2ee2-4112-9659-1755a951966a",
      "templateLang": "en",
      "templateParams": {
        "customer_name": "Alex"
      },
      "deliveryScope": "PRIMARY_DEVICE",
      "ttl": 10,
      "order": 1,
      "failoverOnStatuses": ["EXPIRED", "FAILED", "UNDELIVERED"]
    },
    {
      "type": "Sms",
      "from": "YourBrand",
      "to": "+306912345678",
      "message": { "body": "We could not reach you on Viber." },
      "ttl": 120,
      "order": 2,
      "failoverOnStatuses": ["FAILED", "UNDELIVERED"]
    }
  ],
  "callback": {
    "strategy": "OnCompletion",
    "url": "https://your-server.com/failover-callback"
  }
}

Transactional Viber step fields

Field	Required	Notes
`type`	Yes	`"Viber"`
`senderInfoTrackingId`	Yes	Active Viber sender for your account
`to`	Yes	E.164 mobile
`templateId`	Yes	Approved BM template UUID
`templateLang`	Yes	e.g. `en`
`templateParams`	No	Default `{}`; OTP templates require `pin`
`deliveryScope`	No	`PRIMARY_DEVICE` (default) or `ALL_DEVICES`
`seq`	No	Optional on request; always echoed in create response
`ttl`	Yes	Viber: minutes as a decimal, 0.5–1440.0 (max one decimal place); default 10 if omitted.
`order`	Yes	Step order in the flow
`failoverOnStatuses`	Yes	`EXPIRED`, `FAILED`, `UNDELIVERED` (case-insensitive)
`inboundUrl`	No	HTTPS URL for inbound Viber messages

Not accepted on this endpoint: Viber message body (text/media), client label.

SMS and Voice steps use the same JSON shape as legacy Failover. For Sms steps, ttl is an integer from 1 to 1440 minutes (default 1200). Voice steps do not use ttl.

Create response

HTTP 200 includes:

trackingId — use for tracking and callbacks
flowKind — always transactional
flow — echoed steps; Viber steps include template fields and seq

Tracking

Get: GET https://connect.routee.net/failover/tracking/{trackingId}
Search: POST https://connect.routee.net/failover/tracking with filter:

[
  {
    "fieldName": "flowKind",
    "searchOperator": "IS",
    "searchTerm": "transactional"
  }
]

When flowKind is transactional, Viber messages in tracking show templateId, templateLang, templateParams, deliveryScope, seq — not promotional body.

Callbacks

Customer webhooks include flowKind: standard or transactional (additive; existing integrations keep working). See Failover Callbacks.

Validation errors (HTTP 400)

Mistake	Guidance
Viber `message` on `/failover/transactional`	Use template fields on this endpoint
`templateId` on `/failover`	Use `/failover/transactional`
Unapproved / unknown template	Fix template or wait for approval
Insufficient balance	Top up account; error type `InsufficientBalance`