Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.useinvent.com/llms.txt

Use this file to discover all available pages before exploring further.

Transactional broadcasts fire one message at a time, triggered by your backend the moment something happens: a sign-up, a purchase, a password reset. Instead of choosing an audience and a send time, you set up the message once, activate it, then call its endpoint whenever you need to send. Each call delivers to a single recipient and fans out across every channel you configured. Use them for one-to-one, event-driven messages such as one-time passcodes, receipts, order confirmations, and password resets.
This page covers the transactional-specific flow. For the building blocks every broadcast shares (channels, templates, and properties), start with the Broadcasts overview. To send one message to a whole segment at once, see Marketing broadcasts.
No audience, no schedule. A transactional broadcast sends one message each time you trigger it, so there is no list to send to and no moment to schedule. Each recipient is messaged on every channel they are reachable on: someone with both an email and a WhatsApp number gets both. It is not a fallback chain.
A transactional broadcast showing the trigger panel and the Ready to activate checklist

​
How it works

1

Create a transactional broadcast

Click + Create Broadcast, name it, and choose Transactional as the type. The type cannot be changed after creation.
2

Add channels and content

Add one or more channels and complete a template for each. This is the same editor that marketing broadcasts use.
3

Define your variables

Add any properties your templates need, such as otp or order_id. For transactional broadcasts, the values arrive with each trigger rather than from a contact list.
4

Activate

Click Activate Broadcast to open the endpoint. The broadcast moves to Active and starts accepting triggers immediately.
5

Trigger from your backend

Call the send endpoint whenever the event happens. Each call delivers to one recipient.

​
Setting up the trigger

The Trigger section has two tabs: API and Manual.

​
API

The API tab shows the exact endpoint for this broadcast, a ready-to-copy cURL example, and a link to manage your API keys.
Trigger API tab showing the POST endpoint, a cURL example, and a Manage API keys button
The endpoint is: 
POST https://api.useinvent.com/orgs/<ORG_ID>/broadcasts/<BROADCAST_ID>/send
A complete request looks like this: 
curl -X POST 'https://api.useinvent.com/orgs/<ORG_ID>/broadcasts/<BROADCAST_ID>/send' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "user@example.com",
    "variables": {
      "otp": "123456"
    }
  }'
Authenticate with an organization API key, sent as a bearer token in the Authorization header. Create and manage keys in Settings, API keys.

​
Identifying the recipient

Every trigger names exactly one recipient. Provide at least one identifier, in order of precedence:
FieldTierUse it when
contact_channel_idMost specificYou already know the exact channel to send on. Skips contact resolution and the channel-availability filter.
contact_idKnown contactYou have the contact’s ID. The channel is inferred per template at send time.
phone or emailRawYou only have a raw identifier. Invent finds or creates the contact. You can pass either or both.

​
Overriding the recipient details

phone, email, and name double as per-send overrides. When you also pass a contact_id or contact_channel_id, any of these you include replaces the resolved channel and contact value for that send only. The contact and its stored channels are never modified.
FieldOverrides
phoneThe phone the message is delivered to
emailThe email the message is delivered to
nameThe display name used in the message
name is an override, not an identifier. It cannot resolve a recipient on its own, so a trigger still needs one of contact_channel_id, contact_id, phone, or email.

​
Request body

FieldRequiredDescription
contact_channel_id, contact_id, phone, emailAt least oneRecipient identifiers, sent at the top level of the body. See Identifying the recipient for precedence.
nameNoDisplay-name override for this send. See Overriding the recipient details.
variablesNoValues for your broadcast fields. They override the contact’s stored values, and any field you omit falls back to its configured default.
template_idsNoA subset of templates to fire. Omit to fire every template on the broadcast.
backgroundNoWhen false (default), the call waits for the send and returns an external_message_id per template. When true, it enqueues and returns immediately.
The response returns one recipient record per template fired, so you can confirm exactly what was sent.
The send endpoint is rate limited to 100 requests per 60 seconds. Queue or batch on your side if you expect bursts above that.

​
Manual

Manual triggering from the dashboard is coming soon. It will let you fire a broadcast for a specific contact straight from the UI. For now, use the API tab to send from your backend.

​
Variables

Transactional templates use the same properties as marketing broadcasts, with one difference in where the values come from:
  • Defaults are set on the broadcast and used when a trigger omits a value.
  • Per-trigger values are passed in the variables object and override the defaults for that send.
This lets one broadcast serve many cases. A single order_confirmation broadcast can carry a different order_id and total on every call.

​
Activating, pausing, and resuming

1

Activate

With at least one complete template, click Activate Broadcast. Activating opens the endpoint, and the broadcast starts accepting triggers immediately. Status: Active.
2

Pause

Click Pause to stop accepting triggers. Calls are rejected while paused, and your configuration is preserved. Status: Paused.
3

Resume

Click Resume to reopen the endpoint. The broadcast returns to Active with the same setup.
You can pause and resume as often as you need without losing templates, variables, or settings. A transactional broadcast stays live until you pause it.

​
Monitoring

An active broadcast shows a live status banner: it is active and accepting triggers since the activation date, along with how many messages have been sent across how many channels. A paused broadcast shows the paused state and the same totals. The Recipients table lists every triggered message with its channel, delivery status, and a Source column showing whether the trigger came from the API or a manual send. Because each trigger fans out across templates, one call can produce several rows, one per template.
Transactional broadcasts respect each contact’s subscription status, just like marketing broadcasts. If the recipient has unsubscribed or is blocked, the trigger is rejected: the API returns an error and no message is sent, so you do not need to filter these contacts yourself.
Even so, use transactional broadcasts only for genuinely transactional messages the recipient is expecting, such as one-time passcodes, receipts, and confirmations. For promotional content, use a marketing broadcast. On WhatsApp, match the template category to the content: send these under Utility or Authentication templates, not Marketing. See Template categories and WhatsApp Best Practices.

​
Next steps

Marketing Broadcasts

Send one message to a whole segment at once

API keys

Create and manage the keys that authenticate your triggers

WhatsApp

Configure WhatsApp Templates for transactional sends

Broadcasts Overview

Channels, properties, and statuses shared by every broadcast