Connect a phone

A phone becomes a channel in two steps: pair the MyComm app with your account, then connect a SIM. If your users pair their own phones, use hosted connect and skip this page.

Pairing#

POST /v1/pairing-codes (needs channels:write) returns a code for the phone to enter or scan:

• The code is 8 characters (Crockford base32), single use and valid for 10 minutes.
• Render qr_payload as it is as a QR code; the app scans it.
• At most 20 unused codes exist at once and 60 are created per account per hour; beyond that the API answers 429 PAIRING_CODE_LIMIT_REACHED with retry_after_seconds and a Retry-After header.

Show the pairing QR and poll GET /v1/pairing-codes/{id} until the phone reaches awaiting_confirmation; the person confirms on the phone. If they refuse, the code's last_error.code is DECLINED_ON_DEVICE. A phone that is already paired to another account returns DEVICE_IN_USE and must be unpaired there first (POST /v1/devices/{id}/revoke). DELETE /v1/pairing-codes/{id} invalidates a code you no longer want to be used.

When pairing completes, the device.paired event is sent and the device appears in GET /v1/devices.

Connecting a SIM#

A device can carry more than one SIM. GET /v1/devices/{id}/sims lists them; POST /v1/devices/{id}/sims/{sim_id}/connect connects one (or enable auto-connect for a verified device). Connecting verifies that the SIM can send, and the result is recorded on the channel: verified, awaiting_confirmation, declined_on_device, or failed with its connection_reasons. A failed verification can be retried with POST /v1/channels/{id}/verify.

When it works, channel.connected is sent and the channel joins the Direct line's senders (as the primary when it is the first, else as the last backup), ready to send from. Add it to other lines with PUT /v1/lines/{id}/senders.

Reading the state of a phone#

The device and the channel show connection state, operator, SIM label, last heartbeat and connection_reasons. Use the reasons when you explain why a phone is offline or cannot send, for example permission_missing:SEND_SMS or battery_low. Messages to an offline phone wait with hold_reason: device_offline and go out when it comes back; see the message lifecycle. Events: device.online, device.offline, device.degraded, device.revoked, channel.disconnected, channel.paused, channel.resumed.

Pause, resume, disconnect#

POST /v1/devices/{id}/pause and resume stop and restart sending from a phone without unpairing it; the same for a channel (POST /v1/channels/{id}/pause). disconnect ends a channel, and revoke unpairs a device.