Lines

A channel is one connected number (a SIM in a phone today). A line is what your app sends from and receives into. A line sends through an ordered sender list of the account's channels: the first healthy one sends, and when it cannot (the phone is offline, the SIM is out of budget or keeps failing) queued messages move to the next one. Several lines can share a channel, so your CRM and your billing service can use the same SIM and still keep their conversations, rules, keys and webhooks apart.

Every account has one Direct line (kind: direct). Each number you verify joins it, and replies nobody else claims land there. Lines you create are app lines.

Create one#

POST /v1/lines needs channels:write, which only an account-wide key holds:

curl -sS -X POST "$MYCOMM_URL/v1/lines" \
  -H "Authorization: Bearer $MYCOMM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Billing", "senders": [{"channel_id": "SIM_1_ID"}, {"channel_id": "SIM_2_ID"}]}'

The first sender is the primary and the rest are backups, unless you set role on an entry; a sender you mark primary is moved to the front, so the primary is always tried first. A name is unique in the account, ignoring case (409 NAME_TAKEN). Each sender in the answer carries healthy, whether it could send right now.

Change it#

• PATCH /v1/lines/{id} changes name, reply_window_days (1 to 365, default 30), show_in_portal and settings.
• PUT /v1/lines/{id}/senders replaces the whole sender list; the order you send is the order they are tried in. It fires line.sender_changed. GET /v1/lines/{id}/senders reads it.

Use it#

• Give the app a key for this line with line_ids: [id]. That key sees only this line's traffic and sends without naming a sender at all.
• Send from it with line_id. Add channel_id only to force one SIM: such a message is sender_pinned and never moves.
• Replies come back to it. A reply on a channel the line wrote from within reply_window_days lands on this line. A channel that is in exactly one line besides the Direct line sends its other replies there; anything else goes to the Direct line.
• Follow failover with the line.failover and line.no_sender events, and per message in sender_attempts.
• Hand a conversation to another line with POST /v1/conversations/{id}/handover. Its queued messages go with it: unpinned ones then send from the new line's senders (a line.failover with reason sender_removed when their SIM is not one of them); pinned ones keep their SIM.

Archive it#

DELETE /v1/lines/{id} archives an app line (the Direct line answers 422 LINE_IS_DIRECT). Sends from it are refused (LINE_ARCHIVED), reply routing skips it and its open conversations move to the Direct line; keys limited to it keep read access. POST /v1/lines/{id}/unarchive brings it back.