Receiving messages

A user must be registered as a contact on your account before their messages will be routed to you. This can be done by sending them a message or adding them as a contact.

Need receive-first texting? Talk to us about our dedicated plans.

Receiving Messages

In order to enable receiving messages, you have to specify the webhooks that you want to use in your API dashboard.

Received Messages will be sent as a POST request to the webhook which you define. These messages will be delivered in the JSON of a POST body which looks like this:

{
  "accountEmail": "your-account-email",
  "content": "Hello!",
  "is_outbound": false,
  "status": "RECEIVED",
  "error_code": null,
  "error_message": null,
  "error_reason": null,
  "message_handle": "99DCC379-DD76-4712-BA65-11EFB33B8CD6",
  "date_sent": "2025-12-12T15:41:20.932Z",
  "date_updated": "2025-12-12T15:41:20.995Z",
  "from_number": "+19998887777",
  "number": "+19998887777",
  "to_number": "+15122164639",
  "was_downgraded": null,
  "plan": "dedicated",
  "media_url": "",
  "message_type": "message",
  "group_id": "",
  "participants": [
    "+19998887777",
    "+15122164639"
  ],
  "send_style": "",
  "opted_out": false,
  "error_detail": null,
  "sendblue_number": "+15122164639",
  "service": "iMessage",
  "group_display_name": null
}

You must send a response to our server in order to avoid receiving multiple webhook calls.

Webhook Body Parsing

Callback Body Field	Type	Description
accountEmail	string	Associated account email
content	string	Message content
is_outbound	boolean	True if message is sent, false if message is received
status	string	The current status of the message
error_code	int	Error code (null if no error)
error_message	string	Descriptive error message (null if no error)
error_reason	string	Additional error context (null if no error)
error_detail	string	Detailed error information (null if no error)
message_handle	string	Sendblue message handle
date_sent	string	ISO 8601 formatted date string of the date this message was created
date_updated	string	ISO 8601 formatted date string of the date this message was last updated
from_number	string	E.164 formatted phone number string of the message dispatcher
number	string	E.164 formatted phone number string of your end-user (not the Sendblue-provided phone number)
to_number	string	E.164 formatted phone number string of the message recipient
was_downgraded	boolean	True if the end user does not support iMessage, null otherwise
plan	string	Value of the Sendblue account plan
media_url	string	A CDN link to any media attached to the message (expires after 30 days for inbound)
message_type	string	Type of message (e.g., “message”)
group_id	string	Group identifier (empty string for non-group messages)
participants	array	Array of participant phone numbers
send_style	string	Expressive message style if used (empty string if none)
opted_out	boolean	True if the recipient has opted out
sendblue_number	string	The Sendblue phone number that received the message
service	string	The messaging service used (e.g., “iMessage”, “SMS”)
group_display_name	string	Display name for group chats (null for non-group messages)