- 1Get a template approved. Open the Notification page for your event type. If you have no approved UTILITY template, use the inline Create a template and submit to Meta button — it writes a starter whose variable names already match the payload fields for that event. Then wait for approval and use Sync Status on Templates.
- 2Select the template in the *Template to send* dropdown. Only approved UTILITY templates owned by your workspace appear there.
- 3Copy the endpoint URL and the API key. Reveal the key with the eye button and copy it with the copy button.
- 4Send one real payload from your system, even if it fails. MsgOrb stores the most recent payload it receives and uses it to suggest field paths in the mapper.
- 5Map the fields. Each MsgOrb field gets a path into your payload, written as
{{customer.phone}}. Plain text with no braces is treated as a fixed value. - 6Test with `?dry_run=1`. See Testing a notification.
- 7Save and let the real events flow.
The field mapper
Your system sends its own shape. The mapper translates it. For a delivery event you might map:
| MsgOrb field | Path in your payload |
|---|---|
| Recipient Phone | {{customer.phone}} |
| Customer Name | {{customer.first_name}} |
| Order ID | {{order.number}} |
| Delivery Status | {{order.fulfillment_status}} |
| Tracking Link | {{order.tracking_url}} |
Dotted paths walk into nested objects, and numeric segments index arrays — items.0.id.
Your template's variable names must match the MsgOrb field names for the event. The starter templates are written that way deliberately. A template variable called
customer on a delivery event has nothing to fill it, and the call is rejected with HTTP 400 naming the missing value.Rotating the API key
The Regenerate button on the Authentication panel issues a new key and invalidates the old one immediately, with no grace period. Every external tool using the old key starts receiving *401 Invalid API key* until you paste the new one in. Only the workspace owner can do it.