iMessage connection and routing

Use this page to choose an iMessage connection mode and understand how Skyline routes iMessage conversations.

Connection modes

Cloud (default)
Dedicated

Authenticates with the Interactions control plane and connects to managed iMessage infrastructure via gRPC. Full DM feature set: send, receive, typing, reactions, and replies.

imessage.config();

Tokens renew automatically at 80% of their TTL. Requires projectId and projectSecret:

const app = await Skyline({
  projectId: process.env.SKYLINE_PROJECT_ID!,
  projectSecret: process.env.SKYLINE_PROJECT_SECRET!,
  providers: [imessage.config()],
});

Connect directly to one or more iMessage gRPC endpoints with your own tokens. Use this when you run your own iMessage relay and want to skip cloud auth. Each entry must include the phone number the instance serves:

imessage.config({
  lines: [
    { address: "instance-1.example.com:50051", token: "your-token", phone: "+15551111111" },
  ],
});

Multiple lines route messages based on the phone number associated with each space.

Line model

Cloud mode routes your messages through phone numbers, also called lines, provisioned by Interactions.

Plan	Line allocation	What end users see
Free	Shared pool. Each end user is routed through a different number from a shared pool.	A normal iMessage from a number that may differ across recipients.
Business	Dedicated. All end users text the same number, which belongs to your project.	A normal iMessage, always from the same number.

End-user delivery is identical in both modes. The distinction is which number sends.

Quotas (free plan)

Default per-project quotas apply on the free tier:

5,000 messages per project per day across all chats.
50 new conversations per line per day. A new conversation is the first message your line sends to a recipient it has never messaged before. Replies within existing conversations do not count.
10 registered users per project. Add recipients with the Users API before messaging them on shared lines.

Contact support@interactions.co.in for quota increases on paid plans.

User registration (shared pool)

On the free plan, register each recipient before your agent can message them:

sky skyline users add --phone +15551234567

Or via API:

curl -u "$PROJECT_ID:$PROJECT_SECRET" \
  -X POST "https://api.interactions.co.in/api/projects/$PROJECT_ID/skyline/users" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber": "+15551234567", "type": "shared"}'

Check availability before adding:

curl -u "$PROJECT_ID:$PROJECT_SECRET" \
  "https://api.interactions.co.in/api/projects/$PROJECT_ID/skyline/users/availability?phone=+15551234567"

Space types

iMessage conversations are direct messages (dm) on the free plan. Group chats require a dedicated line on a paid plan. Detect group context from inbound messages:

for await (const [ message] of app.messages) {
  if (message.group?.isGroup) {
    // group chat logic (Business plan)
  }
}

Creating conversations

Open a channel by handle:

const space = app.space("+15551111111");
await space.send("Hi Alice");

On the free plan, group creation is not available. Message registered users in DMs only.

Per-phone routing

Per-phone routing applies to dedicated lines on the Business plan only. On shared-pool plans, routing is automatic.

​Connection modes

​Line model

​Quotas (free plan)

​User registration (shared pool)

​Space types

​Creating conversations

​Per-phone routing