line.* events announce changes to one of your lines: its connection, its ability to send and
receive, its sending limits, its variant and its end. For each of the twelve event types, this page
says when it is sent and when it is not, lists the fields of data, and shows a full event.
Line events do not cover every change of a line. A reservation, an activation, a transfer, a
suspension and a change of configuration send no event: see
What events do not announce, and read the
state of your lines from the API on a schedule.
Common fields
Four events carry a
line object: line.connected, line.disconnected, line.terminated and
line.variant_changed. It is the full line, as its owner reads it. The other events carry
line_id.
Not every line kind gets every event: line.degraded and line.capability_changed are sent for
BYOD lines only, and a shared line gets neither line.connected nor line.offline. See
Line events by line kind.
Personal data. A line object carries phone_number, the number of the line, unmasked. The
reason and error of line.apple_id_flagged are text from the line’s device, and the reason
of line.terminated is free text. Do not copy them into logs, tickets or other tools.
line.connected
Sent when:
- a BYOD device finishes pairing:
connected_atthen equals theactivated_atof the line; - a BYOD line that was offline is heard from again;
- a BYOD line that was degraded passes all the checks that were failing;
- iSnap hands a line over to your account with its device already connected: the line of a pre-order, or another line that iSnap delivers to your account once it is ready;
- a rented line or a test line recovers from an outage that a durable
line.offlineannounced.
line.phone_number.
line.disconnected
Sent when the line’s device signs out, when you terminate the line or a scheduled cancellation is
carried out, when the BYOD slots of the account no longer cover a BYOD line, and when the hosted
macOS session that the line runs on is released while a device session of the line runs on it, even
when the device has stopped reporting. When you terminate a
line, when a scheduled cancellation is carried out, and when BYOD slots no longer cover the line,
the event is sent even if the line had no device session: device_session_id is then null. It is
sent for every line kind.
It is not sent when iSnap terminates a line:
line.terminated then announces the end of the line
without line.disconnected. It is not sent either for the device sessions that a transfer or a
suspension ends, nor when a device session is replaced by a new pairing on the same line or revoked
by iSnap.
line.phone_number.
line.offline
Sent in two forms, told apart by durable.
Immediate form: BYOD lines
Sent when the device of a BYOD line has not reported for 5 minutes, or has not reported at all since it was paired. iSnap checks every 60 seconds: a device that pairs and does not report before the next check is announced offline, withlast_heartbeat_at: null, and announced connected at the first check
after its first report.
A line that is degraded because its reception checks fail gets no line.offline. data adds:
line.connected is sent at the first check, every 60 seconds, after the device reports again.
Durable form: rented lines and test lines
Sent once when the outage of a line that is not a BYOD line reaches 15 minutes.data holds the
four common fields, and no diagnostic field. line.connected is sent when the line recovers.
While the outage lasts, iSnap delivers this event again, with the same event_id, each time the
delivery records of the previous one have been deleted: 72 hours or more after it. Deduplicate on
event_id. Keep the ids you have seen for longer than 72 hours, or make your handling of
line.offline safe to repeat.
line.degraded
BYOD lines only. Sent when the line can still send but no longer receives: the same reception check
fails on two consecutive reports of the device. Recovery is announced by line.connected.
The event is sent again after an offline episode if a reason still holds.
line.apple_id_flagged
Sent once when the line’s device reports that Apple disabled or restricted the Apple ID of the line.
It is sent for every line that has a device of its own.
Only iSnap clears the flag, and no event announces that it was cleared. A report that repeats an
existing flag sends nothing. For a BYOD line, read
apple_id_flagged with
GET /v1/lines/{id}/health.
reason and error are device text.
line.quota_warning
Sent when a message that leaves brings one of the line’s five
sending limits to 80% of its value. It is sent for every
line kind, and never for a trial.
The event is sent at most once per line, per sending limit, per 24 hours. A counter that falls back
and crosses the threshold again inside those 24 hours sends nothing: a warning on the
minute limit
is therefore sent at most once a day. A send that the API refuses with 429, and a held message,
do not trigger it. No event announces that a counter fell back below the threshold.
When one send takes a counter from below 80% to 100% of its limit, which happens for a limit of 4 or
less, only line.quota_exceeded is sent.
line.quota_exceeded
Sent when a message that leaves brings one of the line’s five
sending limits to 100% of its value. The fields are those
of line.quota_warning, without percent, and the same rules apply: at most once per line, per
sending limit, per 24 hours, for every line kind, never for a trial. When one send takes a counter
from below 80% to 100% of its limit, which happens for a limit of 4 or less, line.quota_exceeded
is sent without line.quota_warning.
line.capability_changed
BYOD lines only. Sent when one of the capabilities imessage, sms_fallback, send_text and
send_attachment moves between active and degraded from one report of the device to the next.
A move to or from disabled, and a change of any other capability, send nothing.
line.terminated
Sent once when a line ends for good: you terminated it, a scheduled cancellation was carried out, or
iSnap terminated it. It is sent for every line kind.
A termination sends other events:
line.terminated is not sent when a BYOD line is ended because the BYOD slots of the account no
longer cover it: line.disconnected is then sent alone. It is not sent either when a rented line
returns to the marketplace because its per-line subscription ended.
line.phone_number, and reason when the note holds any.
line.variant_changed
Rented lines only. Sent when the line moves between inbound-only and two-way, immediately or at its
billing anchor. A request for the variant the line already has sends nothing.
line.phone_number.
line.variant_scheduled
Sent when a variant change is scheduled for a billing anchor of the line: the next one, or the first
one at or after the not_before you sent. The change itself is announced by line.variant_changed,
with scheduled: true, when it is applied.
line.variant_unscheduled
Sent when you withdraw a scheduled variant change with
DELETE /v1/lines/{id}/variant.
It is not sent when a scheduled change is dropped: when the line is released, transferred or turned
into a test line, and at the billing anchor when the line is suspended or already has that variant.