Events tools
Report what happened to a contact, such as an order or a booking, so the sequences that listen for that event start. Simulate an event to see what would send.
send_event
Record a named event for a contact (same path as inbound; fires event triggers). `properties` persist on the contact; `event_properties` apply to this event only and are layered over contact props for trigger-filter evaluation.
sms_consentobjectsms_consent.opted_inbooleanrequired- true records opt-in consent; false is a no-op (opt-out is via STOP only).
sms_consent.sourceenumdefault "api"- capture_form | import | manual | api
sms_consent.disclosure_versionstringsms_consent.disclosure_textstringis_staffboolean- Staff contact flag; defaults to false for new contacts and is preserved when omitted for existing contacts. Staff receive only staff event sequences. Static audience membership, broadcasts and bulk emit exclude staff; dynamic-audience previews still count them.
emailstring- Email address; provide email or phone (at least one). Phone-only contacts require a valid phone, normalized to E.164; invalid addresses return 422.
subject_idstring- Stable subject identity shared by all participants, e.g. crm:appointment:123; use <source>:<entity>:<id>. Trimmed, nonblank, at most 200 characters. Required for anchored event enrollment.
occurred_atstring- Event occurrence time: ISO-8601 with an explicit offset or Z, at most 5 minutes in the future. Omit to use database time.
event_namestringrequiredevent_idstringrequirednamestringphonestring- Phone number, normalized to E.164; required when email is omitted.
propertiesobject (any keys)event_propertiesobject (any keys)responder_emailstring | null- Email of a team staff contact who answers this contact's email replies by email: they get each reply and can answer it from their own mail app. null clears it; omit to leave it unchanged. Changes apply only from an event newer than the last change.
teamstringrequired- Brand/team to act on (slug or id) → X-Cadence-Team. Required — your account key authorizes every brand you own, so this picks which one.
emit_event
Emit an event to every eligible contact at once (bulk; eligible = active, not suppressed, and — when audience_key/audience_id is set — a member of that audience at emission time). Each contact gets an idempotent per-contact event (idempotency_key:contact_id), and every active sequence listening for this event enrolls them independently — retries are safe and even heal a previously crashed emit, but can never double-enroll. Use for team-wide or audience-scoped signals (weather, outages, promos); use send_event for one contact.
namestringrequired- Event name sequences listen for, e.g. 'flood'.
propertiesobject (any keys)- Event properties — available in templates as {{event.<key>}}.
idempotency_keystringrequired- Caller-scoped key. Reusing it makes the call a safe no-op (dedup per contact).
audience_keystring | null- Scope the emission to one audience by slug/'everyone' (XOR with audience_id; omitted or null = everyone).
audience_idstring | null- Scope by uuid (XOR with audience_key).
teamstringrequired- Brand/team to act on (slug or id) → X-Cadence-Team. Required — your account key authorizes every brand you own, so this picks which one.
simulate_event
Read-only nominal replay: what would each non-archived sequence (draft and paused included) send for this stored event? No writes, provider calls or Twilio Lookup. Later events are capped at 500; events_truncated reports when the cap is hit. Assumptions: The clock starts at the trigger occurred_at; steps dispatch at planned time with no sweep, provider or quiet-hours delay. Existing enrollments and per-event consumption are ignored, as if the sequence had been active when the event arrived. Contact status, addresses, consent, suppressions, line type, properties and static/dynamic membership are current, not historical. Only stored events are seen. A/B variants are not chosen: the base template is rendered and variant_template_keys are listed.
event_idstringrequiredsequence_idstring- Limit replay to this sequence in the selected team.
teamstringrequired- Brand/team to act on (slug or id) → X-Cadence-Team. Required — your account key authorizes every brand you own, so this picks which one.
list_events
List recent events for the team.
limitnumberoffsetnumbercontact_idstringteamstringrequired- Brand/team to act on (slug or id) → X-Cadence-Team. Required — your account key authorizes every brand you own, so this picks which one.
list_event_types
List the distinct event names this team has received (with counts + last-seen) — the vocabulary an event-triggered sequence must match. Use this BEFORE binding a sequence to event:<name> so the name isn't a typo (or a different convention than your source sends) that silently enrolls no one.
teamstringrequired- Brand/team to act on (slug or id) → X-Cadence-Team. Required — your account key authorizes every brand you own, so this picks which one.