app/docs/runbooks/10dlc-pilot-registration.md

10DLC Pilot Tenant Registration Runbook

Authored for GRO-106 Phase 1.

---

Pre-Flight Checklist

Before starting Telnyx registration, collect the following:

Item	Details
Legal business name	Exact name on EIN / business registration
EIN (Employer Identification Number)	9-digit IRS format: XX-XXXXXXX
Business type	Sole Proprietor / LLC / Corporation
Primary contact email	General contact address (postmaster@, info@, etc.)
Primary contact phone	Direct line for carrier verification
Website URL	Must be live and contain privacy policy
Sample message templates	See Sample Templates below
Messaging use case	Customer Care / Account Notification

---

Step 1 — Telnyx Account Requirements

• Active Telnyx account with billing configured.
• Role required: Admin or Super User to register brands and campaigns.

---

Step 2 — Brand Registration

Via Telnyx Console

1. Log in to Telnyx Portal.
2. Navigate to Messaging → A2P 10DLC → Brands.
3. Click Register Brand.
4. Fill in:
   • Brand Name: Legal business name
   • Legal Company Name: Exact EIN name
   • Company Type: Select from dropdown
   • EIN: XX-XXXXXXX
   • Primary Contact: Name, email, phone
   • Website: Must be accessible
   • BusinessVertical: Select appropriate vertical
5. Acknowledge the Terms of Service.
6. Submit.

Via API

curl -X POST https://api.telnyx.com/v2/10dlc/brands \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Your Legal Business Name",
    "legal_company_name": "Your Legal Business Name",
    "company_type": "llc",
    "ein": "XX-XXXXXXX",
    "primary_contact": {
      "name": "Jane Doe",
      "email": "compliance@example.com",
      "phone": "+1XXXXXXXXXX"
    },
    "website": "https://www.example.com",
    "business_vertical": "PROFESSIONAL_SERVICES"
  }'

Response fields to record:

• brand_id — required for campaign registration
• brand_score — affects campaign vetting speed

Expected Fees

Fee Type	Amount
Brand registration fee	~$0 (no direct fee from Telnyx)
Campaign registration fee	~$15–$25 per campaign (Telnyx fee, subject to change)
Carrier fees	Passed through from T-Mobile/AT&T/Verizon

Expected Approval Window

• Vetting by Telnyx: 1–3 business days after submission.
• Carrier (T-Mobile/AT&T/Verizon) review: 2–5 business days after Telnyx approval.
• Total end-to-end: 3–8 business days.

---

Step 3 — Campaign Registration

Use Case Selection

• Primary: Customer Care
• Secondary: Account Notification

Via Telnyx Console

1. Navigate to Messaging → A2P 10DLC → Campaigns.
2. Click Register Campaign.
3. Select Brand (use the brand registered in Step 2).
4. Fill in:
   • Campaign Name: e.g., groombook-pilot-customer-care
   • Use Case: Customer Care / Account Notification
   • Sample Messages: Paste exactly the templates from Sample Templates below.
   • Description: Brief description of messaging program
   • Estimated Volume: Enter monthly estimate (e.g., 500)
5. Submit.

Via API

curl -X POST https://api.telnyx.com/v2/10dlc/campaigns \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brand_id": "YOUR_BRAND_ID",
    "name": "groombook-pilot-customer-care",
    "use_case": "CUSTOMER_CARE",
    "sample_messages": [
      "Hi {{first_name}}, this is a reminder from {{business_name}} that your appointment is scheduled for {{date}} at {{time}}. Reply STOP to opt out.",
      "Your appointment with {{business_name}} is confirmed for {{date}}. Need to reschedule? Reply HELP or call us at {{phone}}."
    ],
    "description": "Appointment reminders and account notifications for grooming clients",
    "estimated_monthly_volume": 500
  }'

Response fields to record:

• campaign_id — required for messaging profile
• status — initially PENDING, transitions to ACTIVE after carrier approval

Campaign Vetting — STOP/HELP Language Requirements

Every campaign must include compliant STOP/HELP messaging. The following must appear in your sample messages or be included in your terms of service:

• STOP: Users can text STOP to opt out of all messages.
• HELP: Users can text HELP to receive contact information.

Example STOP/HELP block:

Text STOP to opt out. Text HELP for help. Msg & data rates may apply.

---

Step 4 — Messaging Profile + Phone Number Provisioning

Create Messaging Profile

1. In Telnyx Portal, navigate to Messaging → Messaging Profiles.
2. Click Create Messaging Profile.
3. Name it (e.g., groombook-pilot-prod).
4. Copy the Messaging Profile ID (messaging_profile_id) — record this in the DB.

Provision a 10DLC Phone Number

1. Navigate to Messaging → Phone Numbers.
2. Search for a number in your desired area code.
3. Confirm the number is 10DLC-capable.
4. Purchase the number.

Associate Number with Messaging Profile

# Assign number to messaging profile
curl -X PATCH https://api.telnyx.com/v2/phone_numbers/YOUR_PHONE_NUMBER_ID \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_profile_id": "YOUR_MESSAGING_PROFILE_ID"
  }'

---

Step 5 — Record in Database

Once GRO-981 lands, record the following against the business record:

SQL Path (when GRO-981 is complete)

UPDATE businesses
SET
  messaging_phone_number = '+1XXXXXXXXXX',
  telnyx_messaging_profile_id = 'YOUR_MESSAGING_PROFILE_ID',
  telnyx_brand_id = 'YOUR_BRAND_ID',
  telnyx_campaign_id = 'YOUR_CAMPAIGN_ID',
  telnyx_brand_status = 'APPROVED',
  telnyx_campaign_status = 'ACTIVE',
  updated_at = NOW()
WHERE id = 'pilot_business_id';

Manual Admin Path (before GRO-981)

Until GRO-981 is complete, use the Telnyx Portal to verify and record values manually in your internal ops sheet:

Field	Value
messagingPhoneNumber	+1XXXXXXXXXX
telnyxMessagingProfileId	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
telnyxBrandId	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
telnyxCampaignId	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
brandStatus	APPROVED / PENDING
campaignStatus	ACTIVE / PENDING

---

Sample Message Templates

These must match exactly what your system will send. Vetting reviewers compare templates against actual traffic.

Transactional Appointment Reminder

Hi {{first_name}}, this is a reminder from {{business_name}} that your appointment is scheduled for {{date}} at {{time}}. Reply STOP to opt out. Msg & data rates may apply.

Manual Staff Message

Your appointment with {{business_name}} is confirmed for {{date}}. Need to reschedule? Reply HELP for assistance or call us at {{phone}}. Msg & data rates may apply.

---

Failure Modes + Retry Guidance

Vetting Rejection — Brand

Rejection Reason	Common Fix
Legal name mismatch with EIN	Ensure exact EIN name matches legal company name exactly
Website not accessible / missing privacy policy	Add privacy policy page to website before resubmitting
Incomplete primary contact	Provide direct phone and real email (no noreply)
High-risk business vertical	Contact Telnyx support for pre-screening before resubmitting

Campaign Rejection

Rejection Reason	Common Fix
Sample messages do not match actual traffic	Update sample messages to match exactly what the system sends
Missing STOP/HELP language	Add compliant STOP/HELP block to sample messages
Volume estimate too low/high	Revise estimate to be realistic
Use case mismatch	Re-select use case that matches actual messaging

Re-submission

After fixing the rejection reason, re-submit via the same API endpoint. Telnyx will re-run vetting (typically 24–48 hours).

---

Cost Summary

Telnyx Fees (as of 2026)

Fee Type	Amount	Notes
10DLC number (monthly)	~$1.00–$2.50/number	Varies by type and area code
Outbound message	$0.005–$0.015/message	Depends on destination carrier
Inbound message	Included	No charge for received messages
Campaign registration	~$15–$25 one-time	Per campaign, subject to change

Carrier Fees (T-Mobile / AT&T / Verizon)

Carrier	Outbound Fee	Notes
T-Mobile	~$0.005–$0.01/message	Varies by message size (segment)
AT&T	~$0.005–$0.015/message	Varies by message size (segment)
Verizon	~$0.005–$0.01/message	Varies by message size (segment)

Note: Carrier fees are subject to change. Check Telnyx pricing page and carrier fee schedules for current rates.

Example Monthly Cost (Pilot — 500 messages/month)

Line Item	Cost
1x 10DLC number	~$2.00
500 outbound messages	~$5.00–$7.50
Carrier pass-through	~$2.50–$7.50
Estimated Monthly Total	~$9.50–$17.00

---

Rollback / De-provisioning

If the pilot tenant must be de-provisioned:

1. Release the phone number: Telnyx Portal → Phone Numbers → Release.
2. Archive the campaign: set status to INACTIVE via API or console.
3. Remove DB record: clear messagingPhoneNumber, telnyxMessagingProfileId, telnyxCampaignId fields in the business record.
4. Brand can remain registered (no harm) but will not be used.

---

Contacts

Resource	Contact
Telnyx Support	support@telnyx.com
Telnyx Dashboard	portal.telnyx.com
Internal Engineering	Raise issue in GRO-106

---

Owner: Engineering · Last updated: 2026-05-04