Webhook Events

Every event is posted as JSON with Content-Type: application/json, in one of two styles. Standard, which every endpoint created since July 2026 receives, wraps the event body: {"type", "timestamp", "data"}, and you read the fields from data.*. Legacy, for integrations created before July 2026, posts the flat body with no wrapper. Everything inside is identical between the two; the style is fixed per endpoint and shown on the endpoint in the portal.

The event type also rides in the X-SumGenius-Event request header on every delivery, and every delivery is signed: see verifying signatures. How much customer data is included is controlled by your payload profile (full or minimal).

Event body fields

• event_idstring

  32-character hex id, unique per event and stable across retries; it is also the delivery id header. Use it to deduplicate.

• event_typestring

  One of the 14 types in the index.

• occurred_atUTC ISO-8601

  When the event happened on the platform.

• source.platformenum

  facebook · instagram · sms · whatsapp · telegram

• source.channelenum

  meta_dm · twilio_sms · whatsapp_cloud · telegram

• conversation.idinteger | null

  ChatGenius conversation id; pass it to the Send API to reply. Can be null on the very first inbound message from a new person.

• conversation.assigned_to / assigned_to_namefull profile only

  Team member id and name the conversation is assigned to, or null.

• customer.platform_user_idstring

  Platform-assigned user id. Always present, on both profiles: your stable join key.

• customer enrichmentfull profile only

  platform_user_name, platform_user_username, contact_id, tags, stage, custom_fields. custom_fields is a reserved placeholder that is always {}.

• messageobject

  {id, text_raw, attachments[]}. Non-message events replace this block with their own (comment, appointment, lead, escalation, send_failed).

• metaobject

  version (currently v1), payload_profile, generated_at.

Media the customer sent arrives in message.attachments. Four fields are always present; the rest ride on the full profile only.

• typestring

  Attachment category, e.g. image · audio · video.

• media_typestring

  MIME type when available.

• media_idstring

  Platform media identifier.

• received_atUTC ISO-8601

  When the attachment was received.

• urlfull profile only

  Media URL. Time-limited, provided by the platform; download promptly if you need to keep it.

• title / captionfull profile only

  Title or caption text when present.

A customer sent a direct message on Facebook or Instagram (source.platform is facebook or instagram). Fires on text and on attachments.

Share variants

message.reel_shared and message.post_shared fire in addition to message.received for the same message when an Instagram reel or post is shared into the thread, carrying the same message.id. Subscribe to them when you want to react to shares specifically; deduplicate against message.id if you consume both.

A customer left a comment on one of your Instagram or Facebook posts, reels, or live videos. Fires for every inbound comment, whether or not a ChatGenius comment trigger is configured.

There is no message block; the payload carries source_post and comment instead. conversation.id is null for comments: the follow-up DM, if a trigger sends one, arrives as its own message.received event.

• source_postobject

  id is always present: the attribution join key. url is the permalink, populated when the comment matched a trigger targeting a specific post, otherwise null.

• commentobject

  {id, text_raw, matched_keyword, trigger_id, trigger_name, source_type}. source_type is comment · live. The trigger fields (matched_keyword, trigger_id, trigger_name) are null unless a comment trigger matched.

A customer messaged you on SMS, WhatsApp, or Telegram. Same envelope as every other event, plus one channel sub-block under message. The channel pages cover routing identifiers, supported actions, and limits.

• message.smsobject

  {to_phone, from_phone, num_segments, num_media, encoding}. encoding is GSM-7 · UCS-2.

• message.whatsappobject

  {wa_id, phone_number, business_phone_number_id, profile_name, message_type, context_message_id}.

• message.telegramobject

  {chat_id, chat_type, username, message_type}. chat_id is the recipient identifier for the Send API.

Fires once per conversation, the first time an email (or phone) is captured from the conversation content, on any channel. A conversation that captures an email and later a phone produces one of each; the two events are identical except for event_type.

The lead block {email, phone, captured_at} is always included regardless of payload profile: contact info is the point of the event. Fields not yet captured are null.

lead.phone is a phone collected from message content, not the SMS or WhatsApp sender number; on those channels the sender number is already delivered as customer.platform_user_id on every event.

All three carry the same appointment block; the event_type and the appointment's status tell you what happened. appointment.rescheduled fires again on each subsequent reschedule, with the new datetime. The block is always full regardless of payload profile.

• appointmentobject

  {id, confirmation_code, datetime, service_type, duration_minutes, cost, status, timezone, location {city, state}, customer {name, email, phone}}.

• datetimeUTC ISO-8601

  Always UTC. timezone is the appointment's own booking timezone; convert back to display the time the customer chose.

• appointment.customerobject

  The contact details captured during booking. The top-level customer remains the messaging identity.

Fires every time a conversation is handed to a human, triggered by negative sentiment or an explicit hand-off, including repeat escalations on the same conversation. Wire it to Slack or a ticketing system, and match it to a thread via conversation.id.

There is no de-escalation event: the AI stays paused on an escalated conversation by design.

• escalationobject

  {reason, assigned_to, escalated_at}. assigned_to is the agent the conversation was routed to, or null if no agent was available.

Fires when an outbound Send API request permanently fails: the platform returned a non-retryable error (most commonly an expired Meta messaging window) or retries were exhausted. Your system believed the send succeeded; this event lets it reconcile. Match it back to your original request via send_failed.idempotency_key.

• send_failedobject

  {action, idempotency_key, request_id, error_code, error_message, http_code, attempts, text_attempted}.

• text_attemptedfull profile only

  The message text you tried to send. null on the minimal profile.