SMS device relay (agent phone)

Agents can send engagement SMS from their own phone in two ways:

• Play Store and App Store apps: Tap-to-Send. Hub queues the message; the agent confirms Send in the system SMS / Messages app. No SEND_SMS / RECEIVE_SMS permissions. Inbound customer replies stay on the Hub / Twilio number.
• Android Relay APK (sideload only): background SIM relay. Download from aventora.ai/hub-relay-apk. Never uploaded to Google Play. See Mobile agent app.

Build	Mode	Outbound	Inbound replies
Play Store	Tap-to-Send	Agent confirms in the system SMS app	Hub / Twilio number
App Store	Tap-to-Send	Agent confirms in Messages	Hub / Twilio number
Site Relay APK	Full Android relay	Automatic via app	Forwarded to Hub

Hub relay_mode values: android_tap_to_send, ios_tap_to_send (and legacy tap_to_send), android_sms_relay. If both a relay device and a Tap-to-Send device are online, Hub prefers the relay device.

When relay is used (Android)

Outbound SMS from engagements (admin, API, bulk) goes through the relay when all of the following are true:

1. SMS_RELAY_ENABLED is not disabled on the Hub (default: enabled).
2. The engagement’s request_data includes a resolvable external_user_id (domain-chatbot user id) or Hub user_id that maps to one.
3. That user has a registered Android device with relay_enabled = true on the Hub.
4. The device polled the Hub within SMS_RELAY_STALE_SECONDS (default 120 seconds).

Otherwise the Hub sends via Twilio/Telnyx as before.

When Tap-to-Send is used (Play Store, App Store, and iOS)

Store Android and all iPhone builds register relay_mode: android_tap_to_send or ios_tap_to_send. They poll GET /api/mobile/sms/jobs?mode=tap_to_send and open the system composer. The agent sends in the system app and confirms status (opened_composer, user_confirmed_sent, user_cancelled, skipped).

Background relay cannot be enabled for Tap-to-Send devices (Hub returns 400). Inbound POST /api/mobile/sms/inbound is rejected (403) unless relay_mode is android_sms_relay.

Agent setup (Android Relay APK)

1. Download Aventora Relay from aventora.ai/hub-relay-apk (not Play Store). Allow unknown sources, verify SHA-256.
2. Sign in with the same domain-chatbot credentials as Aventora Admin.
3. Register the device (relay_mode: android_sms_relay).
4. Grant SMS permissions and turn Relay on — Hub validates the SIM against your broker phone in Admin.

Agent setup (Tap-to-Send — Play Store and App Store)

1. Install Aventora from Google Play or the App Store.
2. Sign in with the same domain-chatbot credentials as Aventora Admin.
3. Register the device — Hub stores android_tap_to_send or ios_tap_to_send (no SMS send/receive permissions).
4. When jobs are ready, open the system composer, send, then confirm Sent or Skip.

Broker phone validation

When relay is enabled, the app sends sim_phone_number from the device SIM. Hub compares it (E.164) to:

• domain-chatbot user setting phone_number
• Hub per-user overrides default_broker_phone / display_number

Mismatch → 400 with phone_mismatch. No profile phone → profile_phone_missing.

GET /api/mobile/devices/expected-broker-phone lists acceptable numbers for the logged-in user.

Inbound replies (Android only)

When a customer replies to a message sent from the agent’s SIM, the Android app forwards the SMS to POST /api/mobile/sms/inbound. The Hub runs the same session logic as the Twilio SMS webhook (bot turn or chat-center routing).

iOS Tap-to-Send does not receive or forward inbound SMS.

Hub environment variables

Variable	Default	Purpose
SMS_RELAY_ENABLED	true	Master switch for relay routing
SMS_RELAY_STALE_SECONDS	120	Max age of last_seen_at for an active device

Changelog

Date	Change
2026-08-19	Store apps are Tap-to-Send only. Android SIM relay is a site-only APK (android_sms_relay). Hub prefers a live relay device over Tap-to-Send.