iMessage API with several numbers on one account

What you get with several lines

• One API key, one webhook and one live stream for every line.
• Every message, conversation, opt-out, typing event and webhook payload carries line (the number) and line_id. An account with one number does not get either field.
• Lines can be grouped. Lines in a group share one business name and photo, and you can run several senders on one account.
• Read all lines together, or add ?line_id= to see one.

How a send is routed

You call POST /api/imessage/send with the same {to, text} as always. ZeroSettle picks the line:

• A contact you already have a conversation with is always messaged from the line that conversation is on. Each person hears from one number.
• A new contact goes to the line with the most room left today.
• If you pass line_id, the message goes out from that line.

Use line_id when you run something different on each line and the same person texts more than one of them. Copy the line_id from the message.received you are answering.

curl -s -X POST -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"to":"+18055559876","line_id":"ln_8c41e07d92b3f615","text":"Hi from the second line"}' \
  https://portal.zerosettle.io/api/imessage/send

If the line you name is not yours, the call returns 404 unknown_line and nothing is sent. If the line is being retired, a send to a new contact returns 409 line_draining. A retiring line still answers its existing conversations.

When a number is replaced

Sometimes ZeroSettle has to replace the number behind a line, for example when it fails or is flagged. The line keeps its line_id, conversations, message ids, name and photo, and STOPs. Only the number changes. Store line_id in your code and show line to people.

Limits and usage per line

New contacts are counted per line. Each line can reach its plan’s limit every day: 5 on Pro, 25+ on Growth. The count resets at 3 AM Eastern. People who text you first and ongoing conversations do not count.

GET /api/imessage/line returns the account total in usage and each line’s own usage in lines. This example is an account with three Growth lines:

{"handle": "+18055550100",
 "usage": {"new_contacts": {"used": 38, "limit": 150, "period": "day"}},
 "lines": [
  {"id": "ln_3f9a0c2e7b1d4a56", "number": "+18055550100", "group_id": "lg_5e0c9a1f2b7d3e84",
   "usage": {"new_contacts": {"used": 20, "limit": 50, "period": "day"}}},
  {"id": "ln_8c41e07d92b3f615", "number": "+18055550111", "group_id": "lg_5e0c9a1f2b7d3e84",
   "usage": {"new_contacts": {"used": 12, "limit": 50, "period": "day"}}},
  {"id": "ln_d27b5e9f0a6c1843", "number": "+18055550122", "group_id": "lg_a73f18c0d94e2b65",
   "usage": {"new_contacts": {"used": 6, "limit": 50, "period": "day"}}}]}

A send to a new contact returns 429 new_contact_limit only when every line is full. If you named a line, it returns that error when that line is full. A STOP to any of your lines blocks the contact on all of them.

Add lines from code

You can add lines from the console or from the API, on any plan with a card subscription. Only the account owner’s key can buy. A team member’s key can get a quote.

1. GET /api/imessage/lines/quote?count=1 returns the monthly price and what the card is charged today. It charges nothing.
2. POST /api/imessage/lines buys up to 5 lines per request. The lines are live when it returns.

curl -s -X POST -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"new_group": true}' https://portal.zerosettle.io/api/imessage/lines

Each line is billed monthly with your subscription. Today’s charge is prorated to your renewal date. {"new_group": true} starts a new sender with its own name and photo. Without it, the new line uses the same sender as your primary number.

Pricing

Plans are billed monthly by Stripe. Pro has a 30-day money-back guarantee. Full plan details are on the iMessage API page.

What it doesn’t do

• It is iMessage only. SMS fallback is a limited pilot that ZeroSettle switches on for an account. Without it, a first message to someone not on iMessage is not sent.
• New-contact limits apply to each line. Adding a line adds that line’s daily allowance and its monthly price.
• There is no SLA. ZeroSettle publishes 99.9% uptime, which is not an SLA (how uptime is defined).