Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.politicalcomms.com/llms.txt

Use this file to discover all available pages before exploring further.

Every webhook event has a consistent envelope: 
{
  "data": {
    "event_type": "<event-type>",
    "id": "<event-or-message-id>",
    "occurred_at": "<ISO-8601 timestamp>",
    "payload": { /* event-specific payload */ }
  },
  "meta": { "attempt": 1, "max_attempts": 3 }
}

​
message.sent

Triggered when a message is successfully accepted by the carrier. 
{
  "data": {
    "event_type": "message.sent",
    "id": "msg_7f8a9b0c1d2e3f4g",
    "occurred_at": "2025-01-17T10:30:00Z",
    "payload": {
      "message_id": "msg_7f8a9b0c1d2e3f4g",
      "conversation_id": "conv_1a2b3c4d5e6f7g8h",
      "project_id": "proj_9i8h7g6f5e4d3c2b",
      "to": "+15551234567",
      "from": "+15559876543",
      "status": "sent",
      "sent_at": "2025-01-17T10:30:00Z",
      "contact": {
        "phone_number": "+15551234567",
        "custom_fields": {
          "First Name": "Jane",
          "Last Name": "Smith",
          "Email": "jane@example.com",
          "City": "Austin",
          "State": "TX"
        }
      }
    }
  },
  "meta": { "attempt": 1, "max_attempts": 3 }
}

​
message.delivered

Triggered when the carrier confirms the message was delivered to the recipient’s device. 
{
  "data": {
    "event_type": "message.delivered",
    "id": "msg_7f8a9b0c1d2e3f4g",
    "occurred_at": "2025-01-17T10:30:15Z",
    "payload": {
      "message_id": "msg_7f8a9b0c1d2e3f4g",
      "conversation_id": "conv_1a2b3c4d5e6f7g8h",
      "to": "+15551234567",
      "from": "+15559876543",
      "status": "delivered",
      "delivered_at": "2025-01-17T10:30:15Z",
      "contact": {
        "phone_number": "+15551234567",
        "custom_fields": { "First Name": "Jane", "VoterID": "TX12345678" }
      }
    }
  },
  "meta": { "attempt": 1, "max_attempts": 3 }
}

​
message.failed

Triggered when the carrier rejects the message or delivery fails. error_code is a short delivery-failure code (e.g. "300" opted-out, "012" invalid destination) paired with a human-readable error_message. 
{
  "data": {
    "event_type": "message.failed",
    "id": "msg_7f8a9b0c1d2e3f4g",
    "occurred_at": "2025-01-17T10:30:20Z",
    "payload": {
      "message_id": "msg_7f8a9b0c1d2e3f4g",
      "to": "+15551234567",
      "from": "+15559876543",
      "status": "failed",
      "failed_at": "2025-01-17T10:30:20Z",
      "error_code": "012",
      "error_message": "Invalid destination number",
      "contact": { "phone_number": "+15551234567", "custom_fields": {} }
    }
  },
  "meta": { "attempt": 1, "max_attempts": 3 }
}

​
message.replied

Triggered when an inbound SMS/MMS is received from a contact. 
{
  "data": {
    "event_type": "message.replied",
    "id": "msg_inbound_abc123",
    "occurred_at": "2025-01-17T11:00:00Z",
    "payload": {
      "message_id": "msg_inbound_abc123",
      "conversation_id": "conv_1a2b3c4d5e6f7g8h",
      "from": "+15551234567",
      "to": "+15559876543",
      "text": "Thanks for the update!",
      "is_opt_out": false,
      "is_opt_in": false,
      "received_at": "2025-01-17T11:00:00Z",
      "contact": {
        "phone_number": "+15551234567",
        "custom_fields": { "First Name": "Jane", "Last Name": "Smith" }
      }
    }
  },
  "meta": { "attempt": 1, "max_attempts": 3 }
}
Triggered when a recipient clicks a tracking link in your message. 
{
  "data": {
    "event_type": "link.clicked",
    "id": "click_xyz789",
    "occurred_at": "2025-01-17T10:35:00Z",
    "payload": {
      "tracking_link_id": "link_xyz789",
      "message_id": "msg_7f8a9b0c1d2e3f4g",
      "project_id": "proj_9i8h7g6f5e4d3c2b",
      "short_url": "https://link.yourdomain.com/abc123",
      "destination_url": "https://yoursite.com/volunteer-signup",
      "clicked_at": "2025-01-17T10:35:00Z",
      "device": "iPhone",
      "browser": "Safari 17.2",
      "os": "iOS 17.2",
      "ip_address": "203.0.113.42",
      "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.2 Mobile/15E148 Safari/604.1",
      "is_bot": false,
      "is_unique_click": true,
      "is_share_click": false,
      "contact": {
        "phone_number": "+15551234567",
        "custom_fields": { "First Name": "Jane", "City": "Austin" }
      }
    }
  },
  "meta": { "attempt": 1, "max_attempts": 3 }
}