Message delivery status webhooks

Peach can trigger various webhooks as part of Template messages as well as interactive messages' delivery life-cycle, if those have been configured from within Peach.

message_delivery.sent - this is triggered when the message has been sent to the contact.

The webhook payload:

when the message is a Template message:

{
  "type": "message_delivery.sent",
  "data": {
    "message": {
      "id": "cmsg_1234abcd",
      "status": "sent",
      "type": "template_message",
      "reason": null,
      "created_at": "2025-05-22T11:25:06.239Z",
      "updated_at": "2025-05-22T11:25:06.239Z"
    },
    "contact": {
      "id": 1,
      "account_id": 1,
      "name": "John Doe",
      "phone_number": "+919988776655",
      "first_name": "John",
      "last_name": "Doe",
      "country_code": "91",
      "language": null,
      "email": "johndoe@example.com"
    },
    "event": null
  }
}

when the message is an interactive message:

{
  "type": "message_delivery.sent",
  "data": {
    "message": {
      "id": 1,
      "status": "sent",
      "type": "message",
      "reason": null,
      "created_at": "2025-05-03T02:17:07.420Z",
      "updated_at": "2025-05-03T02:17:07.420Z"
    },
    "contact": {
      "id": 1,
      "account_id": 1,
      "name": "John Doe",
      "phone_number": "+919988776655",
      "first_name": "John",
      "last_name": "Doe",
      "country_code": "91",
      "language": null,
      "email": "johndoe@example.com"
    },
    "event": null
  }
}

message_delivery.delivered - this is triggered when the message has been delivered to the contact.

The webhook payload:

when the message is a Template message:

{
  "type": "message_delivery.sent",
  "data": {
    "message": {
      "id": "cmsg_1234abcd",
      "status": "delivered",
      "type": "template_message",
      "reason": null,
      "created_at": "2025-05-22T11:25:06.239Z",
      "updated_at": "2025-05-22T11:25:06.239Z"
    },
    "contact": {
      "id": 1,
      "account_id": 1,
      "name": "John Doe",
      "phone_number": "+919988776655",
      "first_name": "John",
      "last_name": "Doe",
      "country_code": "91",
      "language": null,
      "email": "johndoe@example.com"
    },
    "event": null
  }
}

when the message is an interactive message:

{
  "type": "message_delivery.sent",
  "data": {
    "message": {
      "id": 1,
      "status": "delivered",
      "type": "message",
      "reason": null,
      "created_at": "2025-05-03T02:17:07.420Z",
      "updated_at": "2025-05-03T02:17:07.420Z"
    },
    "contact": {
      "id": 1,
      "account_id": 1,
      "name": "John Doe",
      "phone_number": "+919988776655",
      "first_name": "John",
      "last_name": "Doe",
      "country_code": "91",
      "language": null,
      "email": "johndoe@example.com"
    },
    "event": null
  }
}

message_delivery.failed - this is triggered when the message could not be sent to the contact.

The webhook payload:

when the message is a Template message:

{
  "type": "message_delivery.sent",
  "data": {
    "message": {
      "id": "cmsg_1234abcd",
      "status": "failed",
      "type": "template_message",
      "reason": "failure reason",
      "created_at": "2025-05-22T11:25:06.239Z",
      "updated_at": "2025-05-22T11:25:06.239Z"
    },
    "contact": {
      "id": 1,
      "account_id": 1,
      "name": "John Doe",
      "phone_number": "+919988776655",
      "first_name": "John",
      "last_name": "Doe",
      "country_code": "91",
      "language": null,
      "email": "johndoe@example.com"
    },
    "event": null
  }
}

when the message is an interactive message:

{
  "type": "message_delivery.sent",
  "data": {
    "message": {
      "id": 1,
      "status": "failed",
      "type": "message",
      "reason": "failure reason",
      "created_at": "2025-05-03T02:17:07.420Z",
      "updated_at": "2025-05-03T02:17:07.420Z"
    },
    "contact": {
      "id": 1,
      "account_id": 1,
      "name": "John Doe",
      "phone_number": "+919988776655",
      "first_name": "John",
      "last_name": "Doe",
      "country_code": "91",
      "language": null,
      "email": "johndoe@example.com"
    },
    "event": null
  }
}

message_delivery.read - this is triggered when the message was read by the contact.

The webhook payload:

when the message is a Template message:

{
  "type": "message_delivery.sent",
  "data": {
    "message": {
      "id": "cmsg_1234abcd",
      "status": "read",
      "type": "template_message",
      "reason": null,
      "created_at": "2025-05-22T11:25:06.239Z",
      "updated_at": "2025-05-22T11:25:06.239Z"
    },
    "contact": {
      "id": 1,
      "account_id": 1,
      "name": "John Doe",
      "phone_number": "+919988776655",
      "first_name": "John",
      "last_name": "Doe",
      "country_code": "91",
      "language": null,
      "email": "johndoe@example.com"
    },
    "event": null
  }
}

when the message is an interactive message:

{
  "type": "message_delivery.sent",
  "data": {
    "message": {
      "id": 1,
      "status": "read",
      "type": "message",
      "reason": null,
      "created_at": "2025-05-03T02:17:07.420Z",
      "updated_at": "2025-05-03T02:17:07.420Z"
    },
    "contact": {
      "id": 1,
      "account_id": 1,
      "name": "John Doe",
      "phone_number": "+919988776655",
      "first_name": "John",
      "last_name": "Doe",
      "country_code": "91",
      "language": null,
      "email": "johndoe@example.com"
    },
    "event": null
  }
}

message_delivery.replied - this is triggered when the template message was replied to by the contact.

The webhook payload:

{
  "type": "message_delivery.replied",
  "data": {
    "message": {
      "id": "cmsg_1234abcd",
      "status": "read",
      "type": "template_message",
      "reason": "",
      "created_at": "2025-09-30T04:40:33.514Z",
      "reply": {
        "id": 1,
        "conversation_id": 1,
        "author": {
          "id": 1,
          "account_id": 1,
          "name": "John Doe",
          "phone_number": "+919999776655",
          "first_name": "John",
          "last_name": "Doe",
          "country_code": "91",
          "language": "en"
        },
        "author_type": "Subscriber",
        "text": "Thanks for the update!",
        "content_type": "text",
        "direction": "inbound",
        "_phone_number": "+91 88776 65544",
        "reply_to": {
          "id": 1,
          "reply_to_type": "Wa::TemplateMessage",
          "template_id": "wat_1234abcd",
          "template_name": "Sample WhatsApp Template"
        }
      },
      "updated_at": "2025-09-30T04:40:35.671Z"
    },
    "contact": {
      "id": 1,
      "account_id": 1,
      "name": "John Doe",
      "phone_number": "+919999776655",
      "first_name": "John",
      "last_name": "Doe",
      "country_code": "91",
      "language": "en"
    },
    "event": null
  }
}

conversation.message_sent - this is triggered when a free-form (non-template) outbound message is sent to a contact.

Subscribing: open Developers → Webhooks → Create webhook in Peach, enter your endpoint URL and tick conversation.message_sent in the Events list (it is listed alongside conversation.message_received and the message_delivery.* events). Available to all accounts (Core and CoPilot). Payload type is conversation.message_sent.

The webhook payload:

{
  "type": "conversation.message_sent",
  "data": {
    "message": {
      "id": 1,
      "status": "sent",
      "type": "message",
      "reason": null,
      "created_at": "2025-05-03T02:17:07.420Z",
      "updated_at": "2025-05-03T02:17:07.420Z"
    },
    "contact": {
      "id": 1,
      "account_id": 1,
      "name": "John Doe",
      "phone_number": "+919988776655",
      "first_name": "John",
      "last_name": "Doe",
      "country_code": "91",
      "language": null,
      "email": "johndoe@example.com"
    },
    "event": null,
    "source": "ui"
  }
}

data.source is always present and is one of:

ui - sent by a human from the Peach inbox.

business_app - sent from the native WhatsApp Business App on a coexistence number (echoed into Peach).

api - sent through the developer API / MCP: MCP peach_reply_to_conversation free-form replies, and the public API events send_message, send_quick_reply_message and send_list_reply_message.

Not delivered for: messages sent by the Peach AI Agent, automation/flow/playbook sends (including send_app_message), and template sends (send_template_message, send_flow, and the template fallback of peach_reply_to_conversation); use the message_delivery.* events for template messages. Consumers should ignore source: "api" events produced by their own integration to avoid feedback loops.