Engage Messaging Integration Guide

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:

• ConversationStarted: Triggered when an individual replies to the initial broadcast message, starting a conversation.
• NewMessage: 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": null,
         "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

• 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

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.