FireFlo OMNI

Sends one message to one person, with failover: each step of the route names a channel, what counts as done on it (sent, delivered, read, or answered for a call) and how long to wait. A channel that refuses, fails or runs out of time hands over to the next. The first step is tried before the answer comes back; what happens next arrives as message.* webhook events, or read it back with GET /v1/messages/{message_id}.

Needs the messages:send scope.

Body

Field	Type	Required	Notes
`to`	string	One of `to` or `contact`	The number, with its country code: `+919876543210`.
`contact`	string	One of `to` or `contact`	A contact’s id. Their main number is used.
`template`	string	One of `template` or `content`	A template’s name (or id). Its version for each channel is sent.
`values`	object	When the template or content has `{{tags}}`	Names to text, filled into every `{{name}}`. A tag with no value is refused.
`content`	object	One of `template` or `content`	Content by channel, e.g. `{"sms": {"text": "…"}}`. Replaces the template’s version for that channel.
`route`	string	No	A route’s name. Without `route` or `steps`, the default route is used.
`steps`	array	No	The steps themselves, instead of a route: up to 6 of `{"channel", "succeed_on", "within"}`.
`purpose`	string	No	`transactional` (the default) or `marketing`: which consent the person’s settings are checked against.
`reference`	string	No	Your own reference, up to 128 characters. Filter by it on GET /v1/messages.
`expires_in`	integer	No	Seconds, from 60 to 604800: stop trying after this.

What each channel takes as content: SMS {"text"}; WhatsApp {"text"} inside the 24-hour window, and {"template", "language", "params"} (an approved WhatsApp template and its values, in order) outside it. A message to someone who has asked not to be contacted fails at once on every channel; one inside their quiet hours is postponed until they end. Send an Idempotency-Key header to make a retry safe: the same key with the same body is answered once, and the first answer repeated (with Idempotent-Replayed: true).

Request

curl -X POST https://api.fireflo.au/v1/messages \
  -H "Authorization: Bearer $OMNI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-A-1042-shipped" \
  -d '{
    "to": "+919876543210",
    "template": "order_shipped",
    "values": {
      "name": "Asha",
      "order": "A-1042"
    },
    "route": "whatsapp-then-sms",
    "reference": "order-A-1042"
  }'

import os

import requests

response = requests.post(
    "https://api.fireflo.au/v1/messages",
    headers={
        "Authorization": f"Bearer {os.environ['OMNI_API_KEY']}",
        "Idempotency-Key": "order-A-1042-shipped",
    },
    json={
        "to": "+919876543210",
        "template": "order_shipped",
        "values": {
            "name": "Asha",
            "order": "A-1042",
        },
        "route": "whatsapp-then-sms",
        "reference": "order-A-1042",
    },
)
print(response.status_code, response.json())

const response = await fetch("https://api.fireflo.au/v1/messages", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OMNI_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "order-A-1042-shipped",
  },
  body: JSON.stringify({
    "to": "+919876543210",
    "template": "order_shipped",
    "values": {
      "name": "Asha",
      "order": "A-1042"
    },
    "route": "whatsapp-then-sms",
    "reference": "order-A-1042"
  }),
});
console.log(response.status, await response.json());

Response

202 Accepted — the message as it stands after its first step.

{
  "id": "msg_8f14e45fceea167a5a36dedd4bea2543",
  "status": "delivering",
  "to": "+919876543210",
  "reference": "order-A-1042",
  "purpose": "transactional",
  "test": false,
  "outcome": null,
  "error": null,
  "steps": [
    {
      "channel": "whatsapp",
      "succeed_on": "read",
      "within": 600
    },
    {
      "channel": "sms",
      "succeed_on": "delivered",
      "within": 900
    }
  ],
  "attempts": [
    {
      "step": 0,
      "channel": "whatsapp",
      "status": "sent",
      "code": null,
      "reason": null,
      "channel_message": "cm_918273",
      "at": "2026-10-05T09:14:22.518204+00:00",
      "updated": "2026-10-05T09:14:22.518204+00:00"
    }
  ],
  "created": "2026-10-05T09:14:22.413512+00:00",
  "finished_at": null
}

The message

Field	Notes
`id`	`msg_` and 32 hex characters.
`status`	`delivering` (trying a channel or waiting for its report), `postponed` (held until the person’s quiet hours end), then one of `succeeded`, `failed`, `expired` or `canceled`.
`to`	The number, in international format.
`reference`, `purpose`	As sent.
`test`	True when sent with a test key: no channel is reached, and the first step succeeds at once.
`outcome`	Once it succeeded: `{"channel", "status"}` — the channel that got there and how far (`sent`, `delivered`, `read` or `answered`). Otherwise null.
`error`	Once it failed, expired or was canceled: `{"code", "message"}`, with code `not_permitted` (the person may not be contacted), `no_channel_left`, `expired` or `canceled`. Otherwise null.
`steps`	The route it follows: each `{"channel", "succeed_on", "within"}`.
`attempts`	One per channel tried: `step` (from 0), `channel`, `status` (`refused`, `sent`, `delivered`, `read`, `answered`, `failed` or `timed_out`), `code` and `reason` when refused, `channel_message` (the `cm_` id of the message it sent, or null), `call` (the id of the call a Voice step placed, or null), `at`, `updated`.
`created`, `finished_at`	When it was asked for, and when it settled (null until then).

An attempt is refused when its channel can’t take the message now and the next step runs at once. Its code says why: channel_off, no_content, window_closed (WhatsApp’s 24-hour window is closed and no approved template was given), no_dlt_match (the SMS text fills in none of your registered DLT templates), not_permitted or provider_refused.

Errors

Every refusal is {"error": {"code", "message", "field"}}; field is there when one input is at fault.

Status	Error code	When
400	`invalid_request`	An input is wrong; `field` names it (`to`, `contact`, `template`, `values`, `content`, `route`, `steps`, `purpose` or `expires_in`).
400	`no_channel`	No route was named and the account has no channel that takes messages.
400	`invalid_json`	The body isn’t valid JSON.
400	`invalid_idempotency_key`	The `Idempotency-Key` is over 255 characters.
409	`idempotency_mismatch`	The `Idempotency-Key` was used for a different request.
409	`idempotency_in_progress`	A request with the same `Idempotency-Key` is still being answered.
403	`scope_missing`	The key doesn’t have the `messages:send` scope.

Any request can also be refused for its key, its account or its rate (key_required, invalid_key, account_suspended, plan_excludes_api, address_not_allowed, rate_limited); see the overview.

Overview

Account

Messages

Routes

Templates

Contacts

Conversations

Senders

Calls

Usage

Webhooks

WhatsApp

SMS

Try it

POST /v1/messages

Body

Request

Response

The message

Errors

​Body

​Request

​Response

​The message

​Errors

Body

Request

Response

The message

Errors