Event Endpoint Payloads

Event Endpoint — Webhook Payload Specification

When an event endpoint subscription is active, the system sends an HTTP POST to the subscriber's URL each time a matching event occurs. This document describes the payload shape for every event type.

HTTP request details

Headers (always present):

Headers (conditional on auth config):

Custom headers may also be configured per endpoint.

Base payload: Every event payload includes:

{"orgId":1234}

Common models

Reusable object shapes referenced across multiple event types. All fields marked read-only are system-generated and cannot be set by the caller.

UserModel

Base model for all user types.

CustomerModel

Extends UserModel with customer-specific fields.

CustomerChannelModel

CustomerIdentityModel

CustomerTagModel

Extends TagModel.

MemberContactListModel

Extends ContactListModel.

MessageModel

ConversationModel

ConversationMemberModel

ConversationBotModel

InteractionConfigModel

TeamMemberModel

TeamMemberUserModel

Extends UserModel.

TeamMemberIdentityModel

InstantAppModel

Parameter:

OrgChannelModel

Channel type enum: SMS | HISTORIC_FB | TWILIO | LINE | HISTORIC_ZW | SMOOCH_CHAT | YTEL | INTERNAL | BANDWIDTH | MANAGED_BANDWIDTH | MANAGED_SIGNAL_WIRE | SIGNAL_WIRE | DECANTR | MANAGED_DECANTR | MANAGED_SINCH | MANAGED_INFOBIP

Provider-specific sub-models (smsModel, twilioModel, ytelModel, smoochModel, lineModel, bandwidthModel, managedBandwidthModel, decantrModel, managedDecantrModel, managedSinchModel, managedInfobipModel) are included when the channel type matches. Their shapes are provider-specific and omitted here for brevity.

UploadModel

ScheduledActionModel

ScheduledActionFulfillmentModel

NotificationPrefModel

TeamMemberNotificationModel

Customer events

customer/added

Fired when a new customer is created.

{"orgId":1287,"customer":{"id":3,"displayName":"Jane Doe","createdTimestamp":1711114892361,"createdDate":"2024-03-22T15:21:32.361Z","userType":"CUSTOMER","channels":[{"identityType":"SMS","key":"+15551234567"}],"tags":[{"id":5,"name":"VIP","colorCode":"#FF5733","note":"","addedTimestamp":1711114892361,"addedDate":"2024-03-22T15:21:32.361Z"}],"globalOptOut":false,"globalOptOutTimestamp":0,"globalOptOutDate":null,"identities":[{"type":"SMS","key":"+15551234567"}],"contactLists":[{"id":10,"name":"Newsletter Subscribers","apiId":"newsletter-subs","icon":null,"description":"","externalUrl":null,"type":"PROMPT","addedTimestamp":1711114892361,"addedDate":"2024-03-22T15:21:32.361Z"}]}}

customer/modified

Fired when customer data changes. Batched in groups of up to 100 customers.

{"orgId":1287,"customers":[{"id":3,"displayName":"Jane Doe","createdTimestamp":1711114892361,"createdDate":"2024-03-22T15:21:32.361Z","userType":"CUSTOMER","channels":[{"identityType":"SMS","key":"+15551234567"}],"tags":[],"globalOptOut":false,"globalOptOutTimestamp":0,"globalOptOutDate":null,"identities":[{"type":"SMS","key":"+15551234567"}],"contactLists":[]}]}

customer/optOut — Global opt-out

Fired when a customer globally opts in or out. Batched in groups of up to 100 customers.

{"orgId":1287,"customers":[{"id":3,"displayName":"Jane Doe","createdTimestamp":1711114892361,"createdDate":"2024-03-22T15:21:32.361Z","userType":"CUSTOMER","channels":[],"tags":[],"globalOptOut":true,"globalOptOutTimestamp":1774639484493,"globalOptOutDate":"2026-03-27T12:04:44.493Z","identities":[],"contactLists":[]}],"optOutType":"GLOBAL","optOut":true,"timestamp":1774639484493}

customer/optOut — Phone provider opt-out

Fired when a customer opts in or out on a specific channel via phone provider (e.g. carrier STOP).

{"orgId":1287,"customer":{"id":3,"displayName":"Jane Doe","createdTimestamp":1711114892361,"createdDate":"2024-03-22T15:21:32.361Z","userType":"CUSTOMER","channels":[],"tags":[],"globalOptOut":false,"globalOptOutTimestamp":0,"globalOptOutDate":null,"identities":[],"contactLists":[]},"optOutType":"PHONE_PROVIDER","optOut":true,"timestamp":1774639484493,"orgChannel":{"id":5,"name":"Main SMS","apiId":"main-sms","channelType":"BANDWIDTH","registrationStatus":"REGISTERED","active":true,"channelKey":"+15559876543","firstMessage":null,"firstMessageEnabled":false,"apiOptOutMessage":null,"apiOptOutMessageEnabled":false,"optOutFinalMessage":null,"optOutFinalMessageEnabled":false,"incomingCallResponseType":null,"incomingCallAudioUploadId":null,"incomingCallForwardNumber":null,"unsupportedMediaMessage":null,"prePurchased":false,"channelApps":[]},"customerChannel":{"identityType":"SMS","key":"+15551234567"},"phoneProviderOptOut":true}

Message events

message/added

Fired when a new message is created (sent or received).

{"orgId":1287,"message":{"id":22852,"createdTimestamp":1774639484493,"externalMessageId":null,"userType":"TEAM_MEMBER","userId":2,"content":"test","instantApp":null,"uploads":null,"status":"QUEUED","hasInstantApp":false},"interaction":{"id":37807,"orgChannelId":5,"customerId":3,"createdTimestamp":1711114892361,"lastUpdatedTimestamp":1774639484498,"conversationMembers":[{"teamMemberId":2,"active":true}],"conversationBots":[],"status":"ACTIVE","firstCustomerMessage":{"id":19154,"createdTimestamp":1711114892405,"externalMessageId":"0adc2142-9e13-4345-bec8-44c7ca9da1f4","userType":"CUSTOMER","userId":3,"content":"Blast","instantApp":null,"uploads":null,"status":"RECEIVED","hasInstantApp":false},"topic":null},"postingUser":{"id":2,"displayName":"Jane Agent","createdTimestamp":1654878821461,"createdDate":"2022-06-10T16:33:41.461Z","userType":"TEAM_MEMBER","identities":[{"type":"EMAIL","key":"agent@example.com"},{"type":"NATION_BUILDER","key":"99001"},{"type":"SALESFORCE","key":"005000000000001AAA"}]},"customerChannel":"+15551234567","orgChannel":"+15559876543","bulkActionId":0}

message/status

Fired when message delivery status changes.

Behavior depends on the INDIVIDUAL_STATUS_UPDATE_EVENTS feature flag:

Individual mode (flag enabled): One event per message with message field.

{"orgId":1287,"timestamp":1774639490000,"message":{"id":22852,"createdTimestamp":1774639484493,"externalMessageId":"ext-abc-123","userType":"TEAM_MEMBER","userId":2,"content":"test","instantApp":null,"uploads":null,"status":"DELIVERED","hasInstantApp":false}}

Batch mode (flag disabled): One event with messages array.

{"orgId":1287,"timestamp":1774639490000,"messages":[{"id":22852,"createdTimestamp":1774639484493,"externalMessageId":"ext-abc-123","userType":"TEAM_MEMBER","userId":2,"content":"test","instantApp":null,"uploads":null,"status":"DELIVERED","hasInstantApp":false}]}

message/error

Fired when a message fails to send.

{"orgId":1287,"message":{"id":22853,"createdTimestamp":1774639484493,"externalMessageId":null,"userType":"TEAM_MEMBER","userId":2,"content":"Hello!","instantApp":null,"uploads":null,"status":"FAILED","hasInstantApp":false},"errorMessage":"Carrier rejected message: invalid destination number"}

message/scheduled

Fired when a message is scheduled for future delivery.

{"orgId":1287,"scheduledAction":{"id":500,"userId":2,"orgChannel":{"id":5,"name":"Main SMS","apiId":"main-sms","channelType":"BANDWIDTH","registrationStatus":"REGISTERED","active":true,"channelKey":"+15559876543","firstMessage":null,"firstMessageEnabled":false,"apiOptOutMessage":null,"apiOptOutMessageEnabled":false,"optOutFinalMessage":null,"optOutFinalMessageEnabled":false,"incomingCallResponseType":null,"incomingCallAudioUploadId":null,"incomingCallForwardNumber":null,"unsupportedMediaMessage":null,"prePurchased":false,"channelApps":[]},"customerChannel":{"identityType":"SMS","key":"+15551234567"},"createdTimestamp":1774639484493,"fulfillment":{"message":"Reminder: your appointment is tomorrow","whisper":null,"instantAppSchema":null,"instantAppMessage":null,"instantAppParameters":null,"uploadId":null},"status":"SCHEDULED","deliverOn":1774725884493}}

message/scheduled/deleted

Fired when a scheduled message is cancelled. Same shape as message/scheduled.

message/scheduled/modified

Fired when a scheduled message is modified. Same shape as message/scheduled.

Conversation events

conversation/added

Fired when a new conversation is created.

{"orgId":1287,"interaction":{"id":37808,"orgChannelId":5,"customerId":3,"createdTimestamp":1774639484493,"lastUpdatedTimestamp":1774639484493,"conversationMembers":[],"conversationBots":[],"status":"PENDING","firstCustomerMessage":{"id":22860,"createdTimestamp":1774639484493,"externalMessageId":"abc-123","userType":"CUSTOMER","userId":3,"content":"Hi there","instantApp":null,"uploads":null,"status":"RECEIVED","hasInstantApp":false},"topic":null}}

conversation/joined

Fired when team members join a conversation.

{"orgId":1287,"interaction":{"id":37807,"orgChannelId":5,"customerId":3,"createdTimestamp":1711114892361,"lastUpdatedTimestamp":1774639484498,"conversationMembers":[{"teamMemberId":2,"active":true}],"conversationBots":[],"status":"ACTIVE","firstCustomerMessage":null,"topic":null},"users":[{"id":2,"displayName":"Jane Agent","createdTimestamp":1654878821461,"createdDate":"2022-06-10T16:33:41.461Z","userType":"TEAM_MEMBER"}],"timestamp":1774639484498}

conversation/left

Fired when team members leave a conversation. Same shape as conversation/joined.

conversation-config/modified

Fired when conversation configuration changes.

{"orgId":1287,"interactionConfig":{"id":37807,"orgChannelId":5,"customerId":3,"phoneProviderOptOut":false}}

Agent / team member events

agent/login

Fired when a team member logs in.

{"orgId":1287,"agent":{"id":2,"email":"agent@example.com","user":{"id":2,"displayName":"Jane Agent","createdTimestamp":1654878821461,"createdDate":"2022-06-10T16:33:41.461Z","userType":"TEAM_MEMBER","identities":[{"type":"EMAIL","key":"agent@example.com"},{"type":"SALESFORCE","key":"005000000000001AAA"}]},"otpLoginPhoneNumber":null,"mfaPhoneNumber":"+15550198765","mfaVerified":true},"timestamp":1774639484493}

agent/logout

Fired when a team member logs out. Same shape as agent/login.

agent/added

Fired when a new team member is added.

{"orgId":1287,"agent":{"id":15,"email":"newagent@example.com","user":{"id":15,"displayName":"New Agent","createdTimestamp":1774639484493,"createdDate":"2026-03-27T12:04:44.493Z","userType":"TEAM_MEMBER","identities":[{"type":"EMAIL","key":"newagent@example.com"}]},"otpLoginPhoneNumber":null,"mfaPhoneNumber":null,"mfaVerified":false}}

agent/deleted

Fired when a team member is deleted. Same shape as agent/added.

agent/modified

Fired when a team member is modified. Same shape as agent/added.

Agent tools events

agentTools/enter

Fired when an agent tools session starts.

{"orgId":1287,"agent":{"id":2,"email":"agent@example.com","user":{"id":2,"displayName":"Jane Agent","createdTimestamp":1654878821461,"createdDate":"2022-06-10T16:33:41.461Z","userType":"TEAM_MEMBER","identities":[]},"otpLoginPhoneNumber":null,"mfaPhoneNumber":null,"mfaVerified":false},"timestamp":1774639484493}

agentTools/leave

Fired when an agent tools session ends. Same shape as agentTools/enter.

agentTools/idle

Fired when agent tools becomes idle. Same shape as agentTools/enter.

agentTools/booted

Fired when agent tools boots up with a conversation context.

{"orgId":1287,"agent":{"id":2,"email":"agent@example.com","user":{"id":2,"displayName":"Jane Agent","createdTimestamp":1654878821461,"createdDate":"2022-06-10T16:33:41.461Z","userType":"TEAM_MEMBER","identities":[]},"otpLoginPhoneNumber":null,"mfaPhoneNumber":null,"mfaVerified":false},"conversation":{"id":37807,"orgChannelId":5,"customerId":3,"createdTimestamp":1711114892361,"lastUpdatedTimestamp":1774639484498,"conversationMembers":[{"teamMemberId":2,"active":true}],"conversationBots":[],"status":"ACTIVE","firstCustomerMessage":null,"topic":null},"timestamp":1774639484493}

Monitor events

monitor/enter

Fired when a monitor session starts.

Same shape as agentTools/enter.

monitor/leave

Fired when a monitor session ends. Same shape as monitor/enter.

monitor/inspect

Fired when a monitor inspects a conversation.

{"orgId":1287,"agent":{"id":2,"email":"agent@example.com","user":{"id":2,"displayName":"Jane Agent","createdTimestamp":1654878821461,"createdDate":"2022-06-10T16:33:41.461Z","userType":"TEAM_MEMBER","identities":[]},"otpLoginPhoneNumber":null,"mfaPhoneNumber":null,"mfaVerified":false},"interaction":{"id":37807,"orgChannelId":5,"customerId":3,"createdTimestamp":1711114892361,"lastUpdatedTimestamp":1774639484498,"conversationMembers":[],"conversationBots":[],"status":"ACTIVE","firstCustomerMessage":null,"topic":null}}

Channel events

channels/added

Fired when a new communication channel is added.

{"orgId":1287,"channel":{"id":12,"name":"Support Line","apiId":"support-line","channelType":"BANDWIDTH","registrationStatus":"REGISTERED","active":true,"channelKey":"+16105551234","firstMessage":"Welcome! How can we help?","firstMessageEnabled":true,"apiOptOutMessage":"Reply STOP to unsubscribe","apiOptOutMessageEnabled":true,"optOutFinalMessage":"You have been unsubscribed.","optOutFinalMessageEnabled":true,"incomingCallResponseType":"REJECT","incomingCallAudioUploadId":null,"incomingCallForwardNumber":null,"unsupportedMediaMessage":"Sorry, we cannot process media files.","prePurchased":false,"channelApps":[]}}

channels/deleted

Fired when a channel is deleted. Same shape as channels/added.

channels/modified

Fired when a channel is modified. Same shape as channels/added.

Instant app events

instantApp/added

Fired when a new instant app is created.

{"orgId":1287,"instantApp":{"id":800,"createdTimestamp":1774639484493,"customerUrl":"https://app.prompt.io/ia/abc123","status":"ACTIVE","schemaApiId":"feedback-form","parameters":[{"key":"title","value":"How was your experience?"}]},"customer":{"id":3,"displayName":"Jane Doe","createdTimestamp":1711114892361,"createdDate":"2024-03-22T15:21:32.361Z","userType":"CUSTOMER","channels":[],"tags":[],"globalOptOut":false,"globalOptOutTimestamp":0,"globalOptOutDate":null,"identities":[],"contactLists":[]}}

instantApp/customerConnected

Fired when a customer connects to an instant app.

{"orgId":1287,"instantApp":{"id":800,"createdTimestamp":1774639484493,"customerUrl":"https://app.prompt.io/ia/abc123","status":"ACTIVE","schemaApiId":"feedback-form","parameters":[]},"customer":{"id":3,"displayName":"Jane Doe","createdTimestamp":1711114892361,"createdDate":"2024-03-22T15:21:32.361Z","userType":"CUSTOMER","channels":[],"tags":[],"globalOptOut":false,"globalOptOutTimestamp":0,"globalOptOutDate":null,"identities":[],"contactLists":[]},"timestamp":1774639490000}

instantApp/customerDisconnected

Fired when a customer disconnects from an instant app. Same shape as instantApp/customerConnected.

instantApp/status

Fired when instant app status changes.

instantApp/update

Fired when instant app parameters are updated.

{"orgId":1287,"instantApp":{"id":800,"createdTimestamp":1774639484493,"customerUrl":"https://app.prompt.io/ia/abc123","status":"ACTIVE","schemaApiId":"feedback-form","parameters":[{"key":"rating","value":"5"}]},"customer":{"id":3,"displayName":"Jane Doe","createdTimestamp":1711114892361,"createdDate":"2024-03-22T15:21:32.361Z","userType":"CUSTOMER","channels":[],"tags":[],"globalOptOut":false,"globalOptOutTimestamp":0,"globalOptOutDate":null,"identities":[],"contactLists":[]},"newValues":{"rating":"5"},"oldValues":{"rating":"3"},"timestamp":1774639490000}

instantApp/custom

Fired for custom instant app events. The value field is parsed as JSON if it looks like a JSON object, otherwise stored as a string.

{"orgId":1287,"value":{"action":"button_clicked","buttonId":"submit-feedback"},"instantApp":{"id":800,"createdTimestamp":1774639484493,"customerUrl":"https://app.prompt.io/ia/abc123","status":"ACTIVE","schemaApiId":"feedback-form","parameters":[]},"customer":{"id":3,"displayName":"Jane Doe","createdTimestamp":1711114892361,"createdDate":"2024-03-22T15:21:32.361Z","userType":"CUSTOMER","channels":[],"tags":[],"globalOptOut":false,"globalOptOutTimestamp":0,"globalOptOutDate":null,"identities":[],"contactLists":[]},"timestamp":1774639490000}

instantApp/error

Fired when an instant app script encounters an error.

{"orgId":1287,"errorMessage":"TypeError: Cannot read property 'value' of undefined","errorCode":"SCRIPT_ERROR","instantApp":{"id":800,"createdTimestamp":1774639484493,"customerUrl":"https://app.prompt.io/ia/abc123","status":"ERROR","schemaApiId":"feedback-form","parameters":[]}}

Broadcast / bulk action events

contactAction

Fired for each contact processed during a bulk action (broadcast). The endpoint path may include a custom suffix: contactAction/{eventEndpointPath}.

{"orgId":1287,"progress":42,"total":500,"customer":{"id":3,"displayName":"Jane Doe","createdTimestamp":1711114892361,"createdDate":"2024-03-22T15:21:32.361Z","userType":"CUSTOMER","channels":[{"identityType":"SMS","key":"+15551234567"}],"tags":[],"globalOptOut":false,"globalOptOutTimestamp":0,"globalOptOutDate":null,"identities":[],"contactLists":[]}}

contactAction/carrierRejectionRate

Fired when carrier rejection rate exceeds the configured threshold during a broadcast.

{"orgId":1287,"bulkActionId":150,"rateLimit":0.05,"rejectionCount":30,"messageCount":500,"progress":500,"total":1000}

broadcast/state

Fired when broadcast status changes.

Status values: DRAFT | SCHEDULED | PROCESSING | COMPLETE | PAUSED | ABANDONED | PENDING_APPROVAL

Status message examples:

• "Processing. "

• "Delivery Paused. "

• "Delivery Paused - Excessive Carrier Rejections. "

• "Confirmations Paused. "

• "Processing Paused. "

• "Broadcast is being edited. "

• Combinations of the above (e.g. "Delivery Paused. Confirmations Paused. ")

{"orgId":1287,"bulkActionId":150,"status":"PROCESSING","statusMessage":"Processing. "}

Notification events

notification/sent

Fired when a notification is sent to a team member.

{"orgId":1287,"agent":{"id":2,"email":"agent@example.com","user":{"id":2,"displayName":"Jane Agent","createdTimestamp":1654878821461,"createdDate":"2022-06-10T16:33:41.461Z","userType":"TEAM_MEMBER","identities":[]},"otpLoginPhoneNumber":null,"mfaPhoneNumber":null,"mfaVerified":false},"notifications":{"trigger":"NEW_MESSAGE","type":"EMAIL","sentTo":"agent@example.com"}}

notification/modified

Fired when notification settings change.

{"orgId":1287,"agent":{"id":2,"email":"agent@example.com","user":{"id":2,"displayName":"Jane Agent","createdTimestamp":1654878821461,"createdDate":"2022-06-10T16:33:41.461Z","userType":"TEAM_MEMBER","identities":[]},"otpLoginPhoneNumber":null,"mfaPhoneNumber":null,"mfaVerified":false},"notification":{"notificationGroups":[{"trigger":"NEW_MESSAGE","sendSound":true,"soundUrl":null,"soundVolume":50,"soundRepeatInterval":0,"sendSms":false,"sendEmail":true,"slackChannel":null,"sendToSlackUsername":false,"mentionSlackUserNameInChannel":false}],"vacation":false,"hideSystemMessages":false,"slackUsername":null,"phoneNumber":null}}

Integration events

integrations/sheets/read

Fired when data is read from Google Sheets.

{"orgId":1287,"integrationId":10,"spreadsheetId":"1AbCdEfGhIjKlMnOpQrStUvWxYz0123456789abcde","tabName":"Sheet1","readValues":[{"rowNumber":1,"values":["Name","Phone","Status"]},{"rowNumber":2,"values":["Jane Doe","+15551234567","Active"]}]}

integrations/sheets/write

Fired when data is written to Google Sheets.

{"orgId":1287,"integrationId":10,"spreadsheetId":"1AbCdEfGhIjKlMnOpQrStUvWxYz0123456789abcde","tabName":"Sheet1","rowNumber":3,"writeValues":["John Smith","+15550198765","Pending"],"newRow":true}

Console events

console/log

Fired for info-level console log messages.

{"orgId":1287,"timestamp":1774639484493,"component":"INSTANT_APP","message":"Form submitted successfully"}

console/warn

Fired for warning-level console log messages. Same shape as console/log.

console/error

Fired for error-level console log messages. Same shape as console/log.

Misc events

smartlink/clicked

Fired when a smartlink is clicked.

{"orgId":1287,"customerId":3,"customerChannel":"+15551234567","timestamp":1774639490000,"smartlinkId":42,"bulkActionId":150}

error/alterra

Fired for Alterra-related errors. Payload structure depends on the specific error context.

Appendix: All event types