Getting Started

This guide walks you through the current Android onboarding flow for SemaFore: opening an invitation link, signing in with your phone number, selecting the right organisation, and waiting for approval.

Screenshot pending — see prompt sync-sf-android-screenshot-capture.md.

Before you begin

You will need:

• An Android device running Android 8.0 or later
• The phone number your organisation administrator invited
• Access to SMS on that phone number
• An invitation link from your organisation administrator

Your administrator must invite you before you can join. If you have not received an invitation link, or are unsure whether you were invited, contact your SemaFore administrator.

Step 1 — Open the invitation link

SemaFore invitations use the join-link format https://app.semafore.io/join/{token}.

If the SemaFore app is already installed, tapping the link opens the invitation directly in the app.

If the app is not installed yet, install SemaFore from the Google Play Store, then return to the invitation link and open it again.

Step 2 — Sign in with your phone number

If you are not signed in already, SemaFore takes you to the sign-in screen.

Select your country, then enter the mobile number your administrator invited. The country dial code is shown inline with the number field.

Tap Send code. You will receive a six-character SMS OTP within a few seconds.

Enter the code. SemaFore verifies it and creates your account.

If you opened an invitation link before signing in, the invitation is preserved through this step and resumed automatically after OTP verification.

Step 3 — Choose your organisation

If your account belongs to more than one organisation, SemaFore asks you to choose the active organisation context for this session.

The active organisation controls which members, conversations, groups, and broadcasts you see. You can switch later using the in-app organisation switcher.

Step 4 — Device registration

After sign-in, SemaFore registers your device with your organisation automatically.

Your organisation administrator will see your device appear in the portal Members list with status Registered. They must approve your account before you can send or receive messages.

This is intentional. Approval is a deliberate administrative step that confirms to your organisation that it was you who signed in, not someone else using your phone number.

Step 5 — Wait for approval

You will see a Waiting for approval screen while your administrator reviews your device registration.

Once your administrator approves you, the app moves to the messaging interface automatically. You do not need to restart the app.

If you have been waiting for more than a few minutes, contact your administrator directly.

Step 6 — You are ready

Once approved, you can:

• start a private message thread with any other approved member of your organisation
• be added to group threads by your administrator
• receive broadcasts sent by administrators to all members

All messages are encrypted on your device before they leave. SemaFore’s server routes the encrypted data but cannot read it.

Push notifications

SemaFore uses push notifications via Firebase Cloud Messaging to wake the app when a new message is waiting. The push payload contains routing identifiers only, never decrypted message content.

Tapping a notification opens the relevant thread. If the notification belongs to a different organisation from the one you are currently viewing, SemaFore switches you into the correct organisation context before opening the thread.

Allow SemaFore to send you notifications when Android prompts you. If you declined the prompt, go to Settings → Apps → SemaFore → Notifications and enable them.

Battery optimisation

Android battery optimisation settings can delay background delivery. If you notice delayed message notifications:

Go to Settings → Apps → SemaFore → Battery and select Unrestricted or Don’t optimise. The exact label varies by Android version and device manufacturer.

Troubleshooting

I did not receive an OTP code.
Check that you entered the correct phone number with the full country code. SMS delivery can occasionally take up to 60 seconds. If the code still does not arrive, tap Resend code.

The invitation link opened a sign-in screen instead of the invitation.
Sign in with the invited phone number. SemaFore preserves the invitation and resumes it after OTP verification.

The app shows “Waiting for approval” for a long time.
Your administrator needs to approve your device registration in the portal. Contact them directly.

I registered a new device and can no longer access my messages on my old device.
Each device registration is independent. Every device receives its own encrypted copy of each message, and message history does not automatically move from one device to another.

Messages are delivered late or only when I open the app.
Android battery optimisation is likely restricting SemaFore’s background activity. See the Battery optimisation section above.

What comes next

• Messaging — how private messages, group threads, receipts, and thread controls work on Android
• Security Indicators — what the encryption indicators mean