Messages

Overview

Every call to POST /api/messages creates a message document in Tuco. This page describes the shape of that document, the lifecycle it moves through, and how delivery works under the hood.

Messages sent via API appear in Unibox alongside manually sent and incoming messages. Same recipient = same thread.

Message object

string

Unique message ID (MongoDB ObjectId)

string

Body text

string

"imessage" | "sms" | "email". Defaults to "imessage" when omitted from the API.

string

Current lifecycle state. See Status lifecycle below.

string

Line used to send

string

Denormalized phone from the line

string

Denormalized email from the line

string

Recipient phone number

string

Recipient email address

string

Display name

string

Linked lead (if any)

string

Clerk organization ID

string

Clerk user ID who created the message

string

received for inbound (a reply from the lead), sent for outbound. Inbound messages are where lead-sent photos live.

Attachment fields (photos & files)

string[]

Present only when the message has attachments. Public, signed, 30-day URLs — GET each one (no auth header) to download the real image/file bytes with the correct Content-Type. This is how you retrieve a photo a lead sent you: the raw attachmentUrls below point at private storage and return 403 on their own.

string[]

Filenames aligned 1:1 with attachmentDownloadUrls (e.g. ["IMG_1380.jpeg"]).

string[]

Raw storage URLs (private for inbound / Tuco-hosted). Kept for reference — use attachmentDownloadUrls to fetch bytes.

Scheduling & settings fields

string

ISO 8601 timestamp — when to send

string

Grouping identifier

number

Campaign step index (0 = step 1)

object

Time window settings:

Show settings fields

string

IANA timezone

string

HH:mm

string

HH:mm

number[]

0=Sun … 6=Sat

Delivery tracking fields

string

When actually sent

string

When delivery confirmed via device callback

string

When read (incoming messages only)

string

device message ID

Error & fallback fields

string

Error details when failed or fallback

string[]

Addresses checked for iMessage availability (on fallback)

boolean

When true + message fails, Tuco sends fallback SMS if Twilio is configured. Default: false.

Integration fields

string

Campaign reference

string

HubSpot contact ID

string

HubSpot portal ID

string

GHL contact ID

string

GHL location ID

string

GHL conversation message ID

string

Creation timestamp

string

Last update timestamp

Status lifecycle

queued → pending → sending → sent → delivered
                               ↘ failed
                               ↘ fallback
                          ↗ scheduled (rescheduled)
                     cancelled

Status	Meaning
queued	Not yet picked for send (waiting for line limits, time window, device gap, or contact gap)
pending	Assigned to a line, worker is processing
sending	Worker is actively sending (prevents duplicate sends)
sent	Accepted by the provider (iMessage relay / Twilio)
delivered	Delivery confirmed via device callback (can come later)
failed	Technical send failure after all retries, or availability API error
fallback	Availability check determined recipient has no iMessage
scheduled	Will send at `scheduledDate`, or rescheduled due to device gap
cancelled	User or system cancelled

sent vs delivered: sent means the provider accepted the message. delivered means the recipient’s device confirmed receipt — this can arrive seconds or minutes later via a device callback.

Pre-send checks (why a message stays queued)

These checks run before a message is sent. None of them cause an API error — the message is accepted and waits.

Check	What it does	If it fails
Time window	Only send inside `sendWindowStart`–`sendWindowEnd` on `allowedDaysOfWeek`	Stay queued until next valid time
Line limits	Daily total messages / daily new conversations per line	Stay queued until limits reset
Device gap	Minimum time between sends from the same physical device (default 30s)	Queued or rescheduled
Contact gap	Minimum time between first messages to different contacts on the same line (default 45s)	Stay queued

You can check why a message is still queued by looking at your Loki/Grafana logs for events like individual.message.validation_failed, message.queued_limit, individual.message.device_gap_not_met, or individual.message.gap_not_met.

Retries

Context	Send attempts	Verification between attempts	Gap	Env vars
Individual (API / Unibox)	5	`outgoing_messages` + device gateway `message/query` (poll up to 90s)	60s	`UNIBOX_REPLY_RETRY_*`
App sync fallback	3	Same as individual	30s	`SYNC_FALLBACK_RETRY_*`
Campaign	1 per line; step 0 tries other lines	—	—	—

The “app sync fallback” path only runs when the BullMQ queue is unreachable (e.g. Redis down). In normal operation, the worker handles all sends.

Replying via API

There is no special “reply” endpoint. To reply to a conversation, send another message to the same recipient using POST /api/messages. Unibox groups messages by recipient, so the new message appears in the existing thread.

Where messages appear

Surface	What you see
Unibox	Per-message status icon + label. All statuses except `queued`, `scheduled`, and `cancelled`.
Campaign detail	Recipient-level status badges (Pending, Sent, Delivered, Failed, Fallback).
API	`GET /api/messages` with filters by status, line, lead, etc.

Overview

Webhooks

Errors and status codes

iMessage Availability

Voice / Calling

Replies

Lines & Leads

Campaigns

Analytics

Goal Bots

API Tools

Messages

Overview

Message object

Status lifecycle

Pre-send checks (why a message stays queued)

Retries

Replying via API

Where messages appear

​Overview

​Message object

​Status lifecycle

​Pre-send checks (why a message stays queued)

​Retries

​Replying via API

​Where messages appear

Overview

Message object

Status lifecycle

Pre-send checks (why a message stays queued)

Retries

Replying via API

Where messages appear