Skip to main content
The 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_at then equals the activated_at of 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.offline announced.
It is not sent when you activate or assign a line, and a rented line or a test line that recovers from an outage that was not announced sends nothing.
Personal data: 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.
Personal data: 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, with last_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.
Personal data: none.

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.
Personal data: none.

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.
Personal data: 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.
Personal data: none.

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.
Personal data: none.

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.
Personal data: none.

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.
Personal data: 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.
Personal data: 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.
Personal data: none.

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.
Personal data: none.