SMS vs. iMessage

Lead Hero sends both SMS and iMessage through the same endpoint - POST /sms/{organization}/{leadId} - differentiated by the channel field. They are not interchangeable: each channel has its own sending requirements and a different set of features.

At a glance

	SMS	iMessage
channel value	"sms" (default)	"imessage"
Sends from	An owned phone number with SMS enabled	An iMessage line
Required on send	text	lineId, and text or mediaUrl
orgNumber on send	Optional - omit to auto-pick a number	Not used
Voice messages	Not supported	Supported (upload via uploadVoice, then pass the URL as mediaUrl)
Tapback reactions	Not supported	Supported (react)
Typing indicator	Not supported	Supported (typing), and only within a few minutes of the lead's last message
Read receipts	Not reported back	Reported back to the lead in real time on markRead
Setup required before sending	None - any owned number with SMS enabled works	Yes - an iMessage line must exist first

Requirements

SMS - you need at least one owned phone number with SMS enabled (inboundSmsEnabled/SMS toggled on for the number). Sending picks a number automatically unless you pass orgNumber to pin a specific one.

iMessage - you need at least one active iMessage line before you can send. A line is a dedicated blue-bubble sender identity (phone number + display name/photo shown to the lead), separate from your regular SMS-capable phone numbers:

1. Order a new line (or attach one already provisioned with us if this is your organization's first line) - a one-time setup fee applies, billed the same way for both.
2. Wait for the line to leave pending status and become active.
3. Pass that line's ID as lineId when sending with channel: "imessage".

Listing and filtering

GET /sms/{organization} and the conversation/thread endpoints return both channels mixed together - check channel on each message to tell them apart. To filter to one conversation, pass orgNumber: a phone number for SMS, or an iMessage line's sender ID for iMessage.