Skip to main content

Connect an OMS with API Keys and Event Destinations

Let an external system (booking tool / OMS) upsert contacts and post inbound events. Kazenly maps those events to Contact Fields and can optionally send an approved Utility template.

Admins and managers only. This is not the bot Send to Webhook path (Integrations).

Detail: API Keys · Event Destinations · Contact Fields.

Before you start​

NeedWhere
WhatsApp connected (if you will auto-send Utility)Connect WhatsApp
Contact fields definedContact Fields
Optional Utility templateApproved Utility — G2
Someone who can store secrets securelyAPI key and signing secret are shown once

Path at a glance​

  1. Define Contact Fields
  2. Create an API key
  3. Copy secrets and Quick start
  4. Add an Event Destination
  5. Optional Utility auto-send
  6. Send a test event from your OMS
  7. Check Inbound events and Contact #N

1. Define Contact Fields​

  1. Open Settings → Data & CRM → Contact Fields.
  2. Add field for every value your OMS will send (guest name pieces, booking id, dates, and so on).

You will map Data path → Contact field on the destination.

2. Create an API key​

  1. Open Settings → Data & CRM → API Keys.
  2. Click Create key.
  3. Enter a Name.
  4. Choose Scopes (at least one):
ScopeTypical use
contacts.writeCreate/update contacts and field values
events.inboundAccept booking / OMS events (required for destinations)
messages.send_templateNeeded if a destination sends Utility
flows.triggerReserved for later
consent.writeOnly if the OMS must change campaign addressability
  1. Leave Include signing secret on if your OMS will sign inbound events.
  2. Click Create key.

Empty state before any keys: No API keys yet.

3. Copy secrets and Quick start​

After create, Copy your secrets now:

  • API key (shown once)
  • Signing secret (when included)

Tick I have copied the secret(s). Do not show them again. — Kazenly cannot show the full secret again.

On the API Keys page, Quick start helpers:

  • Copy /me curl
  • Copy /contacts curl (needs contacts.write)
  • Copy /events curl (needs events.inbound and a destination)

Your OMS team uses those samples against your Public API base (from the inbox / bootstrap URL shown in product). Prefer storing secrets in the OMS vault — never in chat or git.

Revoke if a key leaks — Revoke this API key? → Revoke key.

4. Add an Event Destination​

Without a destination, inbound events are rejected (Without a destination, inbound events are rejected until you add one.).

  1. Open Settings → Data & CRM → Event Destinations.
  2. Click Add destination, or Stampede preset / Apply Stampede preset for a booking-oriented start.
  3. In New destination / Edit destination:
    • Event type (for example booking.created — must match what the OMS sends)
    • Display name
    • Guest name path (optional)
    • Active
  4. Under Field map, Add mapping rows: Data path → Contact field.
  5. Click Save destination.

Optional Advanced JSON → Apply JSON to editor.

List rows show field-map count and either a Utility name or upsert only (no send).

5. Optional Utility auto-send​

On the same destination:

  1. Set Utility template name and Language (must be an Approved Utility — not Marketing).
  2. Add Template body parameters (Add body parameter) as needed.
  3. Leave template blank for upsert only (contact/fields update, no WhatsApp send).
  4. Scope messages.send_template must be on the API key if you send.

6. Send a test event from your OMS​

  1. Use Copy /events curl (or your OMS integration) with the new key.
  2. Post an event whose type matches the destination Event type.
  3. Prefer a non-production contact for the first test.

7. Check Inbound events and Contact #N​

On Event Destinations, open Inbound events (last 20):

  • Filters: All types / All outcomes (accepted · duplicate · rejected · send_failed)
  • Refresh
  • Empty: No inbound events yet.
  • Payloads are not stored or shown — outcomes only
  • When a contact was resolved, Contact #N opens Find Contacts / the profile

Confirm field values on the contact Fields tab — Contact Profile.

Quick paths​

PathSetup
A. Upsert onlyContact Fields → key with contacts.write + events.inbound → destination field map · no Utility
B. Booking + UtilitySame as A + Approved Utility on destination + messages.send_template
C. Stampede-styleApply Stampede preset → adjust paths/fields → Save → test event
D. Contacts without eventsKey with contacts.write only → Copy /contacts curl (no destination required)

Common problems​

SymptomWhat to try
Events rejectedAdd/activate a destination for that Event type
No Contact #NEvent did not resolve a contact — check field map / guest paths
Utility not sentTemplate must be Approved Utility · key needs messages.send_template · check send_failed in the log
Lost API secretCreate key again; old secret cannot be revealed
Agent cannot open settingsAdmin/manager only