{
  "event": "message.received",
  "message_id": "CZIsqG9ZWd9gwjIEhZpHY",
  "external_id": "+15551234567",
  "text": "Hello, I need help with my order",
  "attachments": [],
  "protocol": "imessage",
  "timestamp": 1703123457474,
  "device_id": "A1B2C3D4",
  "received_at": 1703123456789
}

​
Overview

Blooio sends POST requests to your configured webhook URL for message lifecycle events.

​
Headers

  • Content-Type: application/json
  • X-Blooio-Event: Event type (e.g., message.sent)
  • X-Blooio-Message-Id: Associated message ID

​
Base fields

​
event
string
required
One of: message.received, message.sent, message.delivered, message.failed, message.read.
​
message_id
string
required
Unique identifier for the message.
​
external_id
string
required
Phone number or email.
​
protocol
string
required
One of: imessage, sms, rcs, non-imessage.
​
timestamp
integer
required
Unix timestamp (ms) when the webhook was sent.
​
device_id
string
required
Hashed device identifier that handled the event.

​
message.received

​
text
string
required
Text content of the inbound message.
​
attachments
array[string]
required
Attachment URLs included in the message.
​
received_at
integer
required
Unix timestamp (ms) when the device received the message.
{
  "event": "message.received",
  "message_id": "CZIsqG9ZWd9gwjIEhZpHY",
  "external_id": "+15551234567",
  "text": "Hello, I need help with my order",
  "attachments": [],
  "protocol": "imessage",
  "timestamp": 1703123457474,
  "device_id": "A1B2C3D4",
  "received_at": 1703123456789
}

{
  "event": "message.received",
  "message_id": "RX12ab34cd56",
  "external_id": "+15559876543",
  "text": "Here is the document.",
  "attachments": [
    "https://cdn.example.com/documents/contract.pdf"
  ],
  "protocol": "sms",
  "timestamp": 1704123457000,
  "device_id": "Z9Y8X7W6",
  "received_at": 1704123456900
}

​
message.sent

Text variant includes text; attachment variant includes attachments.
​
text
string
Text content of the sent message (text variant only).
​
attachments
array[string]
Array of attachment URLs (attachment variant only).
​
sent_at
integer
Unix timestamp (ms) when the message was actually sent by the device. May be null.
{
  "event": "message.sent",
  "message_id": "gK2Ig_XGR2M6UkSgmT9FK",
  "external_id": "+15551234567",
  "protocol": "imessage",
  "timestamp": 1703123458158,
  "text": "Thanks for contacting us! How can I help?",
  "device_id": "A1B2C3D4",
  "sent_at": 1703123457370
}

{
  "event": "message.sent",
  "message_id": "hL3Jh_YHR3N7VlThNU0GL",
  "external_id": "+15551234567",
  "protocol": "imessage",
  "timestamp": 1703123459200,
  "attachments": [
    "https://cdn.example.com/product-image.jpg"
  ],
  "device_id": "A1B2C3D4",
  "sent_at": 1703123458900
}

{
  "event": "message.sent",
  "message_id": "smS12345TxT",
  "external_id": "+15559876543",
  "protocol": "sms",
  "timestamp": 1704123460000,
  "text": "Your verification code is 123456",
  "device_id": "Z9Y8X7W6",
  "sent_at": 1704123459900
}

​
message.delivered

​
delivered_at
integer
required
Unix timestamp (ms) when the message was delivered.
{
  "event": "message.delivered",
  "message_id": "gK2Ig_XGR2M6UkSgmT9FK",
  "external_id": "+15551234567",
  "protocol": "imessage",
  "timestamp": 1703123460773,
  "device_id": "A1B2C3D4",
  "delivered_at": 1703123457563
}

{
  "event": "message.delivered",
  "message_id": "smsDELIV123",
  "external_id": "+15559876543",
  "protocol": "sms",
  "timestamp": 1704123461773,
  "device_id": "Z9Y8X7W6",
  "delivered_at": 1704123461500
}

​
message.failed

​
error_code
string
required
Error code indicating the type of failure.
​
error_message
string
required
Human-readable error message.
{
  "event": "message.failed",
  "message_id": "jkl012_failed_msg",
  "external_id": "+15551234567",
  "protocol": "sms",
  "timestamp": 1703123467000,
  "device_id": "A1B2C3D4",
  "error_code": "delivery_timeout",
  "error_message": "Delivery timeout"
}

{
  "event": "message.failed",
  "message_id": "fail0987_alt",
  "external_id": "+15559876543",
  "protocol": "sms",
  "timestamp": 1704123469000,
  "device_id": "Z9Y8X7W6",
  "error_code": "number_blocked",
  "error_message": "Recipient has blocked messages"
}

​
message.read

​
read_at
integer
required
Unix timestamp (ms) when the message was read. iMessage only, recipient must have read receipts enabled.
{
  "event": "message.read",
  "message_id": "gK2Ig_XGR2M6UkSgmT9FK",
  "external_id": "+15551234567",
  "protocol": "imessage",
  "timestamp": 1703123469000,
  "device_id": "A1B2C3D4",
  "read_at": 1703123468402
}

{
  "event": "message.read",
  "message_id": "readXY7890",
  "external_id": "+15551230000",
  "protocol": "imessage",
  "timestamp": 1704123472000,
  "device_id": "Z9Y8X7W6",
  "read_at": 1704123471500
}