---
title: "Send a transactional Failover Message"
method: POST
path: "/failover/transactional"
---

# Send a transactional Failover Message

`POST /failover/transactional`

Same lifecycle as `POST /failover`, but **Viber steps are template-only** (BM transactional compliance).

## Headers

- `Content-Type` string, required
- `Authorization` string, required

## Request body

- object
  - `flow` object[], required — Ordered list of failover steps. **Viber** steps must use BM template fields only (no free-form `message`). **Sms** and **Voice** steps match legacy Failover.
    - `type` string — The type of the flow channel. Supported values: **Sms**, **Viber** (template-only), **Voice**.
    - `from` string — [For SMS and Voice] The name of the sender id, it can be a telephone number or an alphanumeric string. NOTICE FOR VOICE: Alphanumeric sender is not supported by all networks (e.g. Greek networks). Check restrictions and features here: https://go.routee.net/#/management/restrictions-and-features.
    - `to` union
      - string — [For SMS and Viber] E.164 mobile number.
      - object — [For Voice only] Destination object.
        - `phone` string — The recipient phone [must exist (NotBlank) if viber and sip are both null]
        - `sip` string — A valid sip address. (ex 1111@test.com:55080) [must exist (NotBlank) if phone and viber are both null]
        - `viber` string — A valid phone number. The recipient should have the Viber application installed to be able to receive a Viber call. [must exist (NotBlank) if phone and sip are both null]
    - `ttl` number — [For SMS and Viber] Time range until message expires in minutes. **SMS:** integer, 1–1440 (default 1200). **Viber:** decimal (1 decimal place), 0.5–1440.0 (default 10).
    - `order` integer — Defines the priority order.
    - `failoverOnStatuses` string[] — Defines the statuses which will trigger the next channel. **SMS:** FAILED, UNDELIVERED (default: Undelivered, Failed). **Viber:** EXPIRED, FAILED, UNDELIVERED (default: Expired, Failed, Undelivered). **Voice:** Busy, NoAnswer (default). Case-insensitive.
    - `senderInfoTrackingId` string — [For Viber only] The unique sender id. You can find it at: [Routee Platform-applications page](https://dev.routee.net/#/management/applications).
    - `templateId` string, uuid — [For Viber only — transactional] Approved Rakuten BM template UUID. Required on this endpoint. Use [Rakuten Viber transactional templates](/docs/rakuten-viber-transactional-templates) to create and approve templates.
    - `templateLang` string — [For Viber only — transactional] Template language code (e.g. `en`). Required when `type` is Viber.
    - `templateParams` object — [For Viber only — transactional] Placeholder values for the template. Default `{}`. OTP-category templates require a `pin` key.
    - `deliveryScope` 'PRIMARY_DEVICE' | 'ALL_DEVICES' — [For Viber only — transactional] `PRIMARY_DEVICE` (default) or `ALL_DEVICES`.
    - `seq` integer — [For Viber only — transactional] Optional client sequence number; always echoed in the create response.
    - `inboundUrl` string — [For Viber only] Defines the callback URL that will receive the inbound messages. Check [here](/docs/viber-inbound-messages) for details.
    - `message` object — [For SMS only] **Not accepted on Viber steps** for this endpoint — use template fields instead. Sending Viber `message` returns **400**.
      - `body` string, required — [For SMS only] The message you want to send. Use "\n" to create a new line in your message.
      - `flash` boolean — [For SMS only] Indicates if the SMS is a flash SMS.
      - `label` string — [For SMS only] A generic label which can be used for tagging the failover message. The maximum length is 350 characters.
      - `transcode` boolean — [For SMS only] If “transcode” is set to true/false, then the message body will be/not be transcoded.
      - `urlShortener` object
        - `urlValidity` integer — Seconds the shorten URL will be valid (3600–2592000). Default 2592000.
    - `dialPlan` object — A combination of action verbs to be executed. Can not be empty. Check [here](/docs/dialplan-verbs) for possible "SAY" and "PLAY" avalues.
      - `verbs` object[] — An array of SAY and PLAY verbs.
        - string
    - `machineDetection` object — [For Voice only] It is used to detect if the call is answered by human or machine and define the desired actions (in case of machine).
      - `strategy` string — The strategy to follow when a machine has been detected. Possible values: "Hangup" (terminate the call) or "Continue" (give another dialplan to execute)
      - `eventUrl` string — The URL that Routee will POST to when a machine is detected (only for "Continue" strategy). A valid dialplan is expected as response.
    - `hangupDelay` integer — [For Voice only] Seconds waiting for answer (1–60).
    - `maxDuration` integer — [For Voice only] Maximum call duration in seconds.
  - `callback` object — Details about the callback, more information at [Callbacks (Webhook)](https://docs.routee.net/docs/failover-callbacks)
    - `strategy` string — When the URL will be called. Two possible values: on every status change (OnStep) or when a final status arrives (OnCompletion).
    - `url` string — Defines the URL in which a payload with the information about the request will be posted

## Response `200`

Transactional flow created; first step submission attempted.

- CreateFlowView
  - `trackingId` string
  - `flowKind` 'standard' | 'transactional' — Present on create response; `standard` for `POST /failover`, `transactional` for `POST /failover/transactional`.
  - `flow` CreateFlowViewStep[]
    - union
      - CreateFlowViewSmsStep
        - `type` 'Sms', required
        - `from` string, required
        - `to` string, required
        - `message` object, required
        - `ttl` integer, required
        - `order` integer, required
        - `failoverOnStatuses` string[], required
      - CreateFlowViewViberStep
        - `type` 'Viber', required
        - `senderInfoTrackingId` string, required
        - `to` string, required
        - `message` object — Promotional/session content; absent on transactional create responses.
        - `templateId` string — Present on transactional create responses (echoed from request).
        - `templateLang` string
        - `templateParams` object
        - `deliveryScope` 'PRIMARY_DEVICE' | 'ALL_DEVICES'
        - `seq` integer — Always present on transactional Viber steps in create response (client value or generated).
        - `ttl` number, required — Minutes.
        - `order` integer, required
        - `failoverOnStatuses` string[], required
        - `label` string — Standard flows only; transactional flows omit client label (platform sets `transaction` on send).
        - `inboundUrl` string, uri
        - `expireOnDelivery` boolean
      - CreateFlowViewVoiceStep
        - `type` 'Voice'
  - `callback` object
    - `strategy` 'OnStep' | 'OnCompletion'
    - `url` string
  - `createdAt` string, date-time

## Other responses

- `400` — Validation error or business rule failure (e.g. template on wrong endpoint, insufficient balance).
- `403` — Forbidden — missing role or scope.
- `404` — Unknown sender info or related resource not found.

---

[API](https://skmtc.net/routee/apis/auth.md) · [All operations](https://skmtc.net/routee/apis/auth/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/routee/auth/versions/5cef04e8f7d8/schema)