Projects with several lines

A line is one number your messages come from. A project can hold many lines, and one key sends from all of them. GET /v1/whoami lists them under lines[], each with its id, its address and how much room it has for new people.

Most integrations never pick a line. This page says what the platform does when you do not, how to pick one when you need to, and how to tell which number a person wrote to.

How a send picks a line

A person is pinned to the first line they meet. That is the line your first message to them went out from, or the line they first wrote to. A pin never moves, so they never see your number change on its own. Which line a later send goes out from is in Replying.

Somebody new gets the best line the platform has. Of your active lines on the channel whose connection is up and that have a place left, that is the one with the healthiest connection, then one that has not reached today's pace for new people, then the one with the most places left, then the oldest. Lines that are paused, full or whose connection is down are skipped. Once the send goes out, the person is pinned to that line.

What the 202 tells you

Every accepted command names the line it went out on and why:

{
  "commandId": "cmd-1",
  "status": "queued",
  "disposition": "queued",
  "lineId": "0192a7b0-3e4f-7051-8c6d-7e8f9a0b1c2d",
  "lineSelection": "new_best_line"
}

Sending from a specific number

To send from one line on purpose, put its id in the target at target.lineId. A person who is new is reached from that line and pinned to it. A person pinned to another line gets a second conversation on the line you named, beside the first; their pin does not move. That person now sees two numbers from one business, which Apple can read as spam, so do this sparingly.

The rules and refusals are in Choosing the line.

Which number a person wrote to

When a person writes to you, the message says which of your lines it arrived on. The lineId is on:

• the message frame on /v1/response_stream,
• the message.received webhook,
• each message in a conversation's history.

Match it against the id values in GET /v1/whoami's lines[] to know which number they texted. A message stored before the field existed has no lineId, and neither does one whose line no longer exists.

Replying

You can answer a person who has written to more than one of your numbers without picking a line. A send goes out on the first of these that applies:

1. The line you named. A send with target.lineId goes out on that line.
2. The conversation's line. A send into a conversation, by target.conversationId, goes out on that conversation's line.
3. The line of the message you are answering. A reply that names target.replyToMessageId goes out on the line of the conversation holding that message. If that line is paused or released, the reply is refused rather than moved to another number.
4. The number they last wrote to. Any other send by the person's address goes out on the line of their newest message to you on that channel, among your active lines. A line whose connection is down still counts: the send is not moved to another number, and fails there if that line cannot send. A paused or released line is skipped for the next line they wrote to.
5. The line your conversation began on. If they have not written to any of your active lines, the send goes out on their first line. If that line is paused or released, the send is refused with 503 line_unavailable.

Somebody new to your project has no line yet, so steps 4 and 5 do not apply; the platform picks one for them, as in How a send picks a line.

Any command sent to the person's address, not only a message, follows the same order. A tapback or read receipt that names a message must reach the conversation holding it; if the order picks another line, send it by target.conversationId instead. Answering on a number they wrote to does not move their first line, and it opens nothing new: they already have a conversation there.

Which number to show somebody new

When a person will text you first — from a sign-up page or an app — call GET /v1/lines/available and show them the address it returns. It picks the same line a first send to a new person would get. It reserves nothing, so ask each time you show a number. When a person who is new to your project texts it, they are pinned to that line and take a place on it; someone already on another line keeps that as their first line, and their message opens a conversation on this one, where later sends to them now go, since it is the number they last wrote to.

If every line is full, paused or down, it answers with the same 503 a send would. A test key answers with the sandbox's line for the channel, whose number is always the same.

Related