How to Use and Understand the Webhook Payload #

This guide provides a comprehensive explanation of the webhook payload structure for your application. A webhook is a way for an application to provide other applications with real-time information. Below, we break down the payload fields and explain their purposes to help you integrate and use this data effectively.

Webhook Payload Structure #

{
    "id": "",
    "did": "",
    "participant": "",
    "direction": "",
    "sender_id": "",
    "timestamp": Date,
    "media": [
        {
            "url": "",
            "content_type": "",
            "filename": ""
        }
    ],
    "body": "",
    "status": ""
}

Field Explanations #

• id: Unique identifier for the webhook event. Example: "abc123def456"
• did: The DID (Direct Inward Dialing) number associated with the event. Example: "+1234567890"
• participant: The phone number or identifier of the other participant in the communication. Example: "+0987654321"
• direction: Indicates the direction of the communication. Possible values: "incoming", "outgoing"
• sender_id: Identifier of the sender. Example: "system" or "user123"
• timestamp: The date and time when the event occurred. Example: "2024-12-10T15:30:00Z"
• media: List of media objects associated with the event. Example structure:

  {
      "url": "https://example.com/media/123",
      "content_type": "image/jpeg",
      "filename": "photo.jpg"
  }

• body: The textual content of the message. Example: "Hello, this is a test message."
• status: The current status of the event. Possible values: "delivered", "failed", "pending"

Example Use Cases #

Incoming Text Message #

{
    "id": "msg123456",
    "did": "+1234567890",
    "participant": "+0987654321",
    "direction": "incoming",
    "sender_id": "",
    "timestamp": "2024-12-10T15:30:00Z",
    "media": [],
    "body": "Hi, I need help with my order.",
    "status": "delivered"
}

Outgoing Message with Media #

{
    "id": "msg654321",
    "did": "+1234567890",
    "participant": "+0987654321",
    "direction": "outgoing",
    "sender_id": "agent123",
    "timestamp": "2024-12-10T16:00:00Z",
    "media": [
        {
            "url": "https://example.com/media/photo.jpg",
            "content_type": "image/jpeg",
            "filename": "photo.jpg"
        }
    ],
    "body": "Here is the photo you requested.",
    "status": "delivered"
}

Conclusion #

By understanding the webhook payload structure, you can integrate this data into your application for seamless functionality. This includes tracking message delivery, managing media files, and processing text content for further automation.