Engage Messaging is a broadcast and two-way text messaging platform that enables you to interact with leads via automated and manual conversations. The integration is built on webhooks that notify your system when key events occur and HTTP endpoints that allow your system to retrieve conversation data and send commands (messages and dispositions).
Below, you’ll find detailed instructions for handling each webhook event, using the provided endpoints, and a complete reference for the webhook payload structure.
Webhook Event Types
Pure CallerID sends webhooks for the following events:
- DeliveryResult: Triggered on every DELIVERED or FAILED event on the initial broadcast message. Note: Please ensure your web server that is receiving this webhook is capable of handling a potentially high volume of concurrent HTTP requests.
-
ConversationStarted: Triggered when an individual replies to the initial broadcast message, starting a conversation.
- Conversation is started when:
- An inbound reply contains text and indicates a valid response (non-negative sentiment, non-OptOut intent).
- MMS-only messages (media with no text body), which are treated as conversation starters.
- The following types of inbound messages do not start a conversation, but will trigger MessageReceived if configured:
- Completely empty messages (no text, no media) — those are acknowledged and saved, but do not start a conversation.
- Incoherent or invalid responses that do not indicate opt-out intent
- Once a conversation has started, subsequent messages trigger MessageReceived instead.
- Conversation is started when:
- MessageReceived: Triggered when the individual sends a new message within an ongoing conversation.
- Disposition: Triggered when an agent provides a final chat disposition.
- OptOut: Triggered when the individual replies with “STOP.”
- OptIn: Triggered when the individual replies with “START.”
Webhook Payload Structure
Each webhook payload consists of three main sections:
- eventType: Indicates the type of event (e.g., ConversationStarted, NewMessage).
- data: Contains the conversation data, including campaign information, lead details, messages, and dispositions.
- endpoints: Provides URLs for interacting with the conversation (e.g., sending messages or dispositions).
Complete Webhook Payload and Property Documentation
Below is a sample webhook payload for a ConversationStarted event. This section documents each property and element in the campaign and lead sections to help you understand and process the data.
Complete Payload Sample
{
"eventType": "ConversationStarted",
"data": {
"campaign": {
"id": "67a64d8a95cca62641af5249",
"name": "Test Campaign",
"senderSourceType": "CORE_CAMPAIGN"
},
"lead": {
"id": "67c6e4ee56677e0be32346f9",
"orgId": 1,
"workspaceId": 14,
"messagingCampaignId": "67a64d8a95cca62641af5249",
"messagingListId": "67c6e4e4d4e2da2a270c5fa9",
"status": "DELIVERED",
"statusMessage": null,
"carrier": "CELLCO PARTNERSHIP DBA VERIZON WIRELESS ",
"normalizedCarrier": "Verizon Wireless",
"phone": "+15555551212",
"fromNumber": "+17165127760",
"timeZone": "America/New_York",
"zip": "12345",
"state": "NY",
"lat": 43.075993,
"lon": -73.774821,
"leadData": {
"Zip": "12345",
"Phone": "5555551212",
"FirstName": "John",
"State": "NY",
"LastName": "Doe",
"Address1": "123 Any St",
"City": "Anytown"
},
"created": "2025-03-04T11:33:43.637Z",
"sent": "2025-03-04T11:33:52.948Z",
"result": "2025-03-04T11:33:53.601Z",
"retryAfter": null,
"conversationStarted": true,
"disposition": null,
"dispositionTimestamp": null
},
"messages": [
{
"id": "67c6e52056677e0be32346fb",
"sender": "+17165127760",
"direction": "OUTBOUND",
"timestamp": "2025-03-04T11:33:52.509Z",
"message": "Hi John - This is just a test message. Please respond to trigger the webhook."
},
{
"id": "67c6e55ffa3e252ec81d5dda",
"sender": "+15555551212",
"direction": "INBOUND",
"timestamp": "2025-03-04T11:34:55.805Z",
"message": "Hi! I would love to chat with someone about this offer."
}
],
"dispositions": [
{
"id": "4f2b2fd3-1ba3-43c5-8509-a30af2f9972e",
"disposition": "OK",
"success": false,
"doNotContact": false
},
{
"id": "22924996-83b2-4a1f-96fd-d4a78bdc8794",
"disposition": "Not OK",
"success": false,
"doNotContact": false
}
]
},
"endpoints": {
"embeddableWidget": "https://agent.purecallerid.dev/engage?key=YOUR_KEY_HERE",
"conversationEndpoint": "https://api.purecallerid.dev/api/public/engage/conversation?key=YOUR_KEY_HERE",
"sendMessageEndpoint": "https://api.purecallerid.dev/api/public/engage/conversation/send?key=YOUR_KEY_HERE",
"dispositionEndpoint": "https://api.purecallerid.dev/api/public/engage/conversation/disposition?key=YOUR_KEY_HERE"
}
}
Campaign Object Properties
- id: (String) Unique campaign identifier.
- name: (String) Campaign name for display and internal identification.
- senderSourceType: (String) Indicates the campaign source (e.g., “CORE_CAMPAIGN”).
Lead Object Properties
- id: (String) Unique lead identifier across conversation events.
- orgId: (Integer) Organization identifier associated with the lead.
- workspaceId: (Integer) Workspace or team identifier.
- messagingCampaignId: (String) Messaging campaign ID linked to this lead.
- messagingListId: (String) Identifier for the specific messaging list.
- status: (String) Current delivery status (e.g., “DELIVERED”).
- statusMessage: (Nullable String) Additional status details, if any.
- carrier: (String) Original carrier name provided by the sender.
- normalizedCarrier: (String) Cleaned-up version of the carrier name.
- phone: (String) Lead’s phone number (with international dialing code).
- fromNumber: (String) Sender’s number used for the broadcast.
- timeZone: (String) Lead’s time zone for localization.
- zip: (String) Postal code associated with the lead’s address.
- state: (String) Lead’s state or region.
- lat: (Number) Latitude coordinate of the lead’s location.
- lon: (Number) Longitude coordinate of the lead’s location.
- leadData: (Object) Additional lead details (see LeadData below).
- created: (Nullable String) Timestamp when the lead was created.
- sent: (String) ISO 8601 timestamp when the broadcast message was sent.
- result: (String) ISO 8601 timestamp when the delivery result was recorded.
- retryAfter: (Nullable Value) Indicates if/when a message retry should occur.
- conversationStarted: (Boolean) Flag indicating if the conversation was initiated.
- disposition: (Nullable String) Final disposition from the agent (null until set).
- dispositionTimestamp: (Nullable String) Timestamp for when the disposition was recorded.
LeadData Object Properties (Note: This will contain all of your Lead Data that was loaded – this is only an example of what could be in the collection)
- Zip: (String) Lead’s postal code.
- Phone: (String) Lead’s phone number (typically without country code).
- FirstName: (String) Lead’s first name.
- State: (String) Lead’s state or region.
- LastName: (String) Lead’s last name.
- Address1: (String) Lead’s primary address line.
- City: (String) Lead’s city.
Endpoints Properties (will be 'null' on DeliveryResult)
- embeddableWidget: (URL) Iframe URL for embedding the conversation widget into your agent’s workflow.
- conversationEndpoint: (URL) GET endpoint to retrieve the complete conversation payload including all messages and current lead state.
- sendMessageEndpoint: (URL) POST endpoint (form-url-encoded) used to send messages to the lead; expects a single “message” input.
- dispositionEndpoint: (URL) POST endpoint (form-url-encoded) for submitting a final chat disposition; expects a single “disposition” input matching one of the provided disposition values.
Handling Webhook Events
DeliveryResult
Trigger: On the result of every message sent in the initial broadcast
Actions:
- Listen for the event: Set up your webhook listener to capture incoming payloads. Look for the eventType field with the value DeliveryResult.
- Process the payload:
- Optionally log the send event in your database for reporting purposes
ConversationStarted
Trigger: When a recipient replies to the broadcast message for the first time.
Actions:
- Listen for the event: Set up your webhook listener to capture incoming payloads. Look for the eventType field with the value ConversationStarted.
- Process the payload:
- Read the campaign details to understand which campaign the message belongs to.
- Parse the lead information to capture the user’s details and metadata (e.g., phone, timeZone).
- Iterate over the messages array to log the conversation history. Note that it includes both the initial broadcast and the recipient’s reply.
- Optionally, store the available dispositions for later use.
NewMessage
Trigger: When a recipient sends another message after the conversation has already started.
Actions:
- Listen for the event: Check for eventType with the value NewMessage.
- Process the payload: The messages array here only contains the most recent message. Update your conversation record with the new content.
Disposition
Trigger: When an agent submits a final chat disposition.
Actions:
- Listen for the event: Check for eventType with the value Disposition.
- Process the payload:
- Capture the selected disposition from the payload for internal reporting or further workflow processing.
OptOut
Trigger: When a recipient replies with “STOP.”
Actions:
- Listen for the event: Check for eventType with the value OptOut.
- Process the payload: Update the lead’s status in your system to indicate they no longer wish to receive messages.
OptIn
Trigger: When a recipient replies with “START.”
Actions:
- Listen for the event: Check for eventType with the value OptIn.
- Process the payload: Update the lead’s status to re-enable communications, removing any opt-out flags.
Interacting with the Conversation via Endpoints
The payload includes several endpoints for further actions during a conversation. Each endpoint is designed for a specific function.
Embeddable Widget
Endpoint:embeddableWidget
Usage: Embed this iframe-able HTML page into your agent’s workflow to facilitate two-way conversations and disposition submissions.
Example:
<iframe src="https://agent.purecallerid.app/engage?key=YOUR_KEY_HERE" width="100%" height="600px"></iframe>
Conversation Endpoint
Endpoint: conversationEndpoint
Method: HTTP GET
Usage: This endpoint returns the entire conversation payload, including all messages and the current state of the lead.
Example:
curl -X GET https://api.purecallerid.app/api/public/engage/conversation?key=YOUR_KEY_HERE
Send Message Endpoint
Endpoint: sendMessageEndpoint
Method: HTTP POST (application/x-www-form-urlencoded)
Usage: Send a message to the lead by including a single form input called message.
Example:
curl -X POST
"https://api.purecallerid.app/api/public/engage/conversation/send?key=YOUR_KEY_HERE" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "message=Hello, how can we help you today?"
Disposition Endpoint
Endpoint: dispositionEndpoint
Method: HTTP POST (application/x-www-form-urlencoded)
Usage: Submit a final chat disposition. The form input should include a field called disposition that matches one of the disposition names provided in the webhook payload.
Example:
curl -X POST "https://api.purecallerid.dev/api/public/engage/conversation/disposition?key=YOUR_KEY_HERE" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "disposition=OK"
Summary
This guide has provided:
- Webhook Event Handling: Detailed instructions on how to listen for and process ConversationStarted, NewMessage, Disposition, OptOut, and OptIn events.
- Complete Payload Documentation: A comprehensive breakdown of the webhook payload sample and detailed descriptions of each property in the campaign and lead objects.
- Endpoint Integration: Guidance on how to embed the Engage widget, retrieve conversation data, send messages, and submit dispositions using HTTP GET and POST methods.
By following this guide, your integration should seamlessly interact with Pure CallerID’s Engage Messaging platform, ensuring efficient and secure handling of conversations and real-time updates. Feel free to adapt these examples and documentation to your specific system requirements.