Phone & Voice

Connect with your users via phone calls and SMS. Your AI agents can answer calls, send texts, and hand off to humans when needed.

Setting Up Phone Numbers

1. Go to Phone Numbers
2. Click Add Phone Number
3. Choose a number and configure it

Phone Number Settings

Setting	What It Does
Name	Internal name for this number
Enable Voice	Allow incoming/outgoing calls
Enable SMS	Allow text messaging
Default Workflow	Which workflow handles conversations
Brand Name	How the AI introduces itself

Voice Calls

How AI Voice Works

When someone calls your number:

1. Your AI agent answers with a greeting
2. The caller speaks naturally
3. AI responds in real-time with speech
4. The conversation follows your workflow

The AI can:

• Answer questions
• Collect information
• Book appointments
• Transfer to humans
• End calls appropriately

Work Modes

Control when AI handles calls vs. forwarding:

Mode	Behavior
Always On	AI always answers
Forward Off-Hours	AI during business hours, forward after
Message Off-Hours	AI during hours, auto-reply message after
Always Forward	Always forward to another number
Voicemail	Always send to voicemail (record message + transcribe)
Voicemail Off-Hours	AI during hours, voicemail after hours

Setting Business Hours

1. Go to Settings → Workspace Settings
2. Configure your business hours
3. Use is_business_hours in CEL conditions

Call Forwarding

Transfer calls to humans when needed:

1. Configure a Forward Number on your phone number
2. The AI can transfer using the Forward Call ability
3. Or forward automatically during off-hours

SMS Messaging

How SMS Works

Text messages work like chat:

1. User texts your number
2. AI responds via text
3. Conversation follows your workflow
4. Full history saved to chat

SMS Settings

Setting	What It Does
Enable SMS	Turn on text messaging
SMS Work Mode	Same options as voice
Off-Hours Message	Auto-reply when closed
Forward Number	Where to forward texts

WhatsApp Messaging

The same phone numbers can also handle WhatsApp. If your workspace has the WhatsApp feature enabled, a per-number WhatsApp toggle appears alongside Enable SMS and Enable Voice. Turning it on lets the number send and receive WhatsApp messages through the same workflow as SMS.

Key differences from SMS:

• Feature flag required — whatsapp must be enabled on the workspace (ask your org admin)
• Per-member opt-in — Members have a separate WhatsApp notification toggle that defaults to off; outbound actions skip members who haven't opted in
• 24-hour window — Outbound sends after 24 hours of member inactivity must use an approved WhatsApp template
• Same workflow — Inbound WhatsApp uses the phone number's Default Workflow, just like SMS
• Opt-out via STOP — Members opt out the same way as SMS, by replying STOP

See WhatsApp Messaging for the full guide, including Twilio sandbox setup, template messages, and the whatsapp:send action.

Web Voice

Users can also make voice calls from your websites:

1. Enable voice on your Site
2. Users click the microphone icon
3. Browser-based voice call with your AI

No phone number needed - works directly through the browser.

Voice Configuration

Agent Voice

Pick how your AI sounds:

1. Go to Members → Agents
2. Edit your agent
3. Select a Voice option

Available voices vary by AI model.

Phone Abilities

Add these to workflows for phone-specific features:

Ability	What It Does
Hang Up	AI can always end phone calls (enabled by default)
Forward Call	AI can transfer to another number

Add via the Abilities tab on workflows or tasks.

Common Setups

Customer Support Line

• Voice: Always On
• SMS: Always On
• Workflow: Support workflow with escalation task
• Abilities: Hang Up, Forward Call
• Forward number: Your support team

Appointment Booking

• Voice: Always On
• Workflow: Booking workflow with calendar access
• Abilities: Calendar Booking, Hang Up
• Let AI schedule appointments by voice

After-Hours Answering

• Voice: Message Off-Hours
• Off-Hours Message: "Thanks for calling. We're closed. Leave a message."
• Business Hours: 9am-5pm weekdays
• AI handles calls during hours, voicemail after

Sharing via QR Code

On each phone number's detail page, the Share QR Code section generates a scannable QR that encodes a tel: or sms: URI for the workspace number.

1. Go to Phone Numbers and open a phone number
2. Scroll to Share QR Code on the General tab
3. Toggle between Call (tel:) and Text (sms:) modes
4. Download as PNG or SVG for flyers, signage, websites, or contact cards

When a visitor scans the code with a phone camera, their dialer or SMS composer opens with your workspace number pre-filled — no typing required.

Direct Member Calls

Call other workspace members directly (human-to-human, no AI):

1. Navigate to a member's profile or open their chat
2. Click the Call button (visible in member lists and chat windows)

Prerequisites: Both you and the recipient must have a phone number configured and enabled for voice in the workspace.

Experience: You receive an incoming call first (from the workspace number), answer it, then the system bridges you to the other member.

Common errors (e.g., "no phone configured", "recipient unavailable") are shown in-app with guidance.

Tips

• Test your number - Call it yourself first
• Set clear greetings - Configure initial messages in your workflow
• Use business hours - Don't let AI respond at 3am (unless you want it to)
• Enable SMS too - Some users prefer texting
• Check call logs - Review conversations in Chats

Related

• Phone Call Tools — Give AI control over hang up and call forwarding
• Workspace Settings — Configure business hours for call routing
• Sites — Enable browser-based web voice on your sites

Business Profile for A2P SMS

Org admins configure the Business Profile tab (found under Organization settings) to provide the business information required by Twilio before A2P 10DLC SMS can be used.

Required information

• Business details such as legal name, EIN, address, website, contacts, and industry
• Details for two authorized representatives

Submission flow

1. Fill in the required fields in the Business Profile form.
2. Click Submit for Twilio Review (enabled only after an internal compliance check passes).
3. The status banner indicates progress through Twilio review, which typically takes 1–3 business days.

Status values

• draft — Profile is being prepared
• pending-review — Submitted and awaiting review
• in-review — Currently under Twilio review
• twilio-approved — Approved; A2P SMS registration is now unlocked
• twilio-rejected — Review failed; edit the profile using the scrubbed reasons shown, then resubmit

After approval the A2P tab under Sub-account becomes available.

A2P Registration

Once your Business Profile is approved and you have the a2p_registration add-on enabled, org admins complete the A2P registration process from the A2P tab under Sub-account in Organization settings. This registers your organization with carriers so your phone numbers can send SMS reliably.

Brand registration

1. Open the A2P tab in Organization settings.
2. Enter your Brand Name (the legal business name) and a Brand Description (a plain-English summary of how your organization uses SMS — for example, "Healthcare appointment reminders and care coordination messages sent to patients who have opted in").
3. Click Start Registration. The system submits a Brand Registration to Twilio and begins carrier review.

Sample message approval

After brand registration submits, the system generates sample SMS messages that represent what your members will receive. These samples are presented to you for review before the campaign is submitted to carriers.

As an org admin you will see a list of sample messages on the A2P tab. You can:

• Approve the messages as shown, or
• Edit any message text to better match your actual SMS content before approving.

Once you click Approve, the campaign is submitted to carriers for review. Approval typically takes 1–5 business days.

Campaign submission and polling

After you approve the sample messages, the system submits the A2P campaign to Twilio and begins polling for a carrier decision every 5 minutes. You do not need to stay on the page — the status updates automatically.

Registration status values

Status	What it means
registering	Brand or campaign submission is in progress
review_needed	Carrier review requires manual attention; contact support
pending	Campaign submitted and awaiting carrier approval
active	Registration approved — SMS is now enabled on your numbers
failed	Registration was rejected; check the error details and contact support

Once the status reaches active, SMS is automatically enabled on all phone numbers in your organization.

Note: The timed_out status may appear if polling exceeds the expected window. Contact support if registration remains in this state.

SMS Consent Setup

Before a campaign can be submitted to carriers, your brand must have a configured, published opt-in surface. The SMS Consent tab (under Organization settings → Sub-account → A2P) is where you configure that surface. It is available once an A2P brand exists (see A2P Registration above).

How the consent model works

The opt-in checkbox label you set here is the single source of truth: the patient enrollment form, the A2P evidence page sent to TCR, and the campaign MessageFlow are all generated from it. Keeping them in sync is automatic — the evidence never overclaims what the real form says.

Consent text fields

Field	What it controls
Opt-in checkbox label	The exact line a patient checks to agree to SMS. Quoted verbatim in the MessageFlow submitted to TCR.
Disclosure	Supplementary text shown beneath the checkbox — optionality notice, message frequency, data rates, and opt-out instructions (e.g. "Reply STOP to opt out or HELP for help").

After editing either field, click Save to persist the overrides. The Live preview panel on the right updates the rendered enrollment-form checkbox as you type, and refreshes the MessageFlow preview after you save.

Default opt-in / opt-out / help keywords

Carriers require that standard keywords trigger the corresponding automated responses:

Keyword	Effect
STOP	Member opts out; automatic opt-out reply sent
START	Re-subscribes a previously opted-out member
HELP	Automatic help reply sent with support contact

These keywords are pre-configured as carrier defaults and do not need to be listed in the disclosure text unless you want to surface them explicitly to patients.

Multi-brand organizations

If your organization has more than one A2P brand, a Brand selector appears at the top of the SMS Consent tab. Each brand has independent consent text and its own linked enrollment site. Switch brands to edit each independently.

Enrollment Site Setup

An Enrollment site is a published patient-facing opt-in form linked to a specific brand. The submission gate requires a live enrollment site to be linked before a campaign can be submitted to TCR (A2P Phase 4). The gate triggers at the sample-message approval step and returns HTTP 412 ("set up your SMS consent form first") if no site is linked.

How sites are provisioned

For most organizations the site is provisioned automatically. When you click Start Registration and your organization has exactly one workspace, the system creates (or reuses) a gravity-health-enrollment site in that workspace and links it to the brand — no manual action needed.

For organizations with more than one workspace, auto-provisioning cannot determine the right workspace, so the site is not provisioned automatically. The Enrollment site section of the SMS Consent tab shows a workspace picker and a Create enrollment site button in this case.

Linking an enrollment site

The Enrollment site card within the SMS Consent tab shows the current state:

State	What to do
No site linked, single workspace	Click Create enrollment site — the system provisions and links in one step.
No site linked, multiple workspaces	Select a workspace from the picker, then click Create enrollment site.
Existing published site available	Use Or link an existing enrollment site to pick from eligible sites already in the org.
Site linked	The linked site name and workspace are shown. Click Unlink to remove the association.

Eligible sites

An eligible enrollment site is one of the following:

• A published source site (a source-site-template site with a published release)
• A site using an enrollment theme such as cosan-enrollment or gravity-health-enrollment

The site does not need to be set to public; enrollment forms are served regardless of the is_public flag.

Patient enrollment link

Once a site is linked, the Patient enrollment link appears in the Enrollment site card. Append &external_id=<member_external_id> to each link before sharing so enrollments are associated with the correct member record. The brand is encoded in the URL so a single shared site can serve multiple brands — each brand's link routes patients to that brand's consent text.

The 412 gate

If you reach the Approve samples step in A2P registration and see a 412 error ("set up your SMS consent form first"), it means no enrollment site is linked to the brand. Go to Organization settings → Sub-account → A2P → SMS Consent, provision or link a site using the steps above, then return to A2P and approve the samples again.

Note: start_org_a2p_registration is not gated — the brand (and its site link) can be set up after registration starts. The gate fires at the sample-approval step, which is the point at which the campaign is submitted to carriers.