The HeyGil SMS help centre

Let’s get you connected.

Start with the essentials, choose your channel, and find a useful next step. Need a hand? We’re here.

01 · A place to begin

Create your workspace.

  1. Create an account with your name and work email. Your first workspace is created with it.
  2. Open Devices to pair an Android phone or Mac, or open Channels to configure a cloud provider.
  3. Add a contact, import a CSV, or connect the tools you already use.
  4. Send a test message to a number you control and check the reply and delivery history.
02 · Your Android relay

Connect your phone and your number.

You need Android 8.0 or later, an active SIM, and a phone that can reach your server.

Your deployment needs its Android relay package. The project’s Android app can be built with ./gradlew assembleDebug from android-app/.

  1. Install the relay app. It is listed as SMS Connector in the phone’s app settings.
  2. In your workspace, open Devices → Pair Device and name the phone.
  3. Scan the QR code, or enter the reachable server base URL and 8-character token. The token expires after 15 minutes.
  4. Grant SMS/phone permissions and unrestricted battery use. Optional notification access adds best-effort observations; it does not enable native outbound RCS.
  5. Check the heartbeat, then send and receive a real test message. SMS uses the phone’s default SMS subscription.
03 · Your Mac companion

Bring iMessage into the conversation.

  1. Sign in to Messages.app on a Mac with Python 3 available.
  2. Generate a fresh device pairing token and download the Mac installer from the device page.
  3. Run the installer on the Mac. It installs the Python companion and a background LaunchAgent.
  4. Allow Messages.app Automation and Full Disk Access for the relevant Terminal/Python process.
  5. Check a real outbound message, inbound reply, and the Mac’s connection status.

You can also configure a BlueBubbles HTTP bridge in Channels. Read about iMessage setup

04 · Your people

Prepare your contact list.

Use Contacts to add people individually or import a CSV with a header row. Keep international phone numbers in full country-code format, such as +61400111001. Use tags to organise an audience and record opt-outs before a campaign.

Import supports contact details such as name, phone number, email, company, and tags. The Contacts page shows the supported format and validates the file. Export is available from the same page.

05 · Your connected tools

Send through the REST API.

Create an API token in Integrations. Keep it private and include it as a bearer token. Send to and content to POST /api/v1/messages. Reuse an Idempotency-Key when retrying the same send.

Example request · replace the server and token
curl -X POST https://your-server.example/api/v1/messages \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reminder-1042" \
  -d '{"to":"+61400111001","content":"See you tomorrow at 10!","channel":"sms"}'

Inspect GET /api/v1/messages/{id} for status and event history. The OpenAPI specification lists the API contract. The public health endpoint reports gateway status.

06 · Helpful follow-through

Connect rules and events.

Use Automations to configure keyword replies, opt-out rules, and outbound webhook subscriptions. Configure your endpoint secret and verify the signature against the raw request body. The event log shows delivery attempts and provides replay controls.

The X-SmsConnector-Signature header contains a timestamp and an HMAC-SHA256 signature over timestamp + "." + raw_body. Protocol header names retain the original gateway identity for integration compatibility.

Drip pacing, working hours, API tokens, CRM webhook URLs, and workspace switching are available in Integrations. Cloud provider credentials are configured in Channels.

07 · Thoughtful messaging

Send with context and permission.

Use contacts who have agreed to hear from your business. Keep messages relevant, identify yourself, and honour opt-out requests. Configure the workspace’s opt-out automations and review suppression before sending a campaign.

Carrier, provider, regional, and channel requirements still apply. Mobile plans and cloud-provider charges are separate from platform pricing. RCS observations can be incomplete; native outbound RCS is not implemented.

08 · Privacy & data

Your workspace data, in context.

HeyGil SMS stores account details, contacts, conversation content, delivery events, device telemetry, and integration settings in the configured deployment. Connected providers process the data needed for the channels you enable.

The web app uses a session cookie for sign-in and browser storage for your theme preference. Update account details in My account, manage tokens in Integrations, and remove or re-pair devices from Devices. Workspace data requests should be directed to the workspace owner or deployment operator.

For questions about access, data handling, or your setup, contact hello@heygil.ai. This guide describes the product; your deployment’s data location, retention settings, and applicable privacy terms should be confirmed with its operator.

09 · The Gil family

Looking for HeyGil?

HeyGil is our sister product for gyms, Pilates, and yoga studios. It focuses on member context, retention, lead conversion, and AI-assisted team follow-through.

Meet HeyGil

Ready for your first hello?

Bring your own devices, connect your tools, and give your team one clear place to keep the conversation moving.

Create your workspace