Lifecycle Stages
1. Created
A message is created when:- A campaign triggers
- A journey step executes
- An API call is made
- Contact is selected from audience
- Creative is chosen (manual or ML)
- Placeholders are resolved
- Short links are generated
2. Queued
Message enters the queue:QueuedTextMessagerecord created- Scheduled for immediate or future send
- Assigned to sending list
queued
3. Sent
Message executor processes the queue:- Picks up messages due for sending
- Submits to SMS provider (Infobip, etc.)
- Records submission
sent
4. Delivered/Failed
Provider confirms delivery:- Webhook received with status
MessageSentrecord updated- Metrics calculated
delivered or failed
Detailed Flow
Message Statuses
| Status | Meaning |
|---|---|
queued | Waiting to be sent |
sent | Submitted to provider |
delivered | Confirmed delivery to handset |
failed | Delivery failed |
expired | Message expired before delivery |
rejected | Carrier rejected message |
Failure Reasons
| Code | Meaning |
|---|---|
invalid_phone | Phone number is invalid |
unsubscribed | Contact opted out |
carrier_rejected | Carrier blocked message |
spam_detected | Flagged as spam |
timeout | Provider timeout |
unknown | Unknown error |
Timing
Typical Flow
| Stage | Duration |
|---|---|
| Queue → Sent | Seconds to minutes |
| Sent → Delivered | Seconds |
| Failed detection | Immediate to minutes |
Delays
Messages may be delayed by:- Large queue volume
- Provider rate limits
- Network issues
- Carrier congestion
Link Tracking
When a message has tracked links:- Original URLs replaced with short URLs
MessageShortLinkrecords created- On click, redirect service logs event
- User redirected to destination
Monitoring
Dashboard
View message status in:- Schedule detail view
- Contact lookup
- Reports
Discord Alerts
Get notified of:- Delivery failures
- High failure rates
- Spam complaints
Troubleshooting
Messages stuck in queue
Messages stuck in queue
Check:
- Is the message executor running?
- Are there provider issues?
- Is the queue backlogged?
High failure rate
High failure rate
Common causes:
- Invalid phone numbers
- Carrier blocks
- Spam filtering
- Rate limiting
Delayed delivery
Delayed delivery
Possible reasons:
- Provider congestion
- Rate limits hit
- Large campaign ahead in queue