# Documentation

## Pages

- [Documentation](/docs): Concepts, walkthroughs, embeddable UI, and operational setup for Surge messaging and voice.
- [Channels Roadmap](/docs/channels-roadmap)
- [RCS and WhatsApp](/docs/channels-roadmap/rcs-and-whatsapp): RCS and WhatsApp are coming to Surge. How to build SMS workflows today so your code extends to new channels without rewrites.
- [Voice](/docs/channels-roadmap/voice): Voice calls, recording, voicemail, and AI voice agent integrations available now; full GA arrives after HIPAA compliance ships.
- [Concepts](/docs/concepts)
- [Consent Flows: How Users Opt In](/docs/concepts/consent-flows): Valid opt-in methods, what makes a consent flow carrier-compliant, and how to write the consent_flow description.
- [Deliverability](/docs/concepts/deliverability): T-Mobile volume caps, Verizon batching delays, Surge's content policy layer, and how to monitor message delivery health.
- [Required Disclosures and Opt-In Templates](/docs/concepts/required-disclosures): The three required SMS disclosures, where to place them, and copy-ready opt-in templates for common use cases.
- [SMS Segments & Encoding](/docs/concepts/sms-segments): How SMS segments and character encodings work, why emoji messages use more segments, and practical cost advice.
- [The Campaign Registry (TCR) and Becoming a CSP](/docs/concepts/tcr): What TCR is, how Surge submits your registrations as your CSP, and when becoming a CSP yourself makes sense.
- [Embeddable UI Components](/docs/embeddable): Add a messaging inbox, conversation view, and dialpad to your app using Surge's embeddable UI components and JWT auth.
- [Conversation Component](/docs/embeddable/conversation): Mount the Conversation component to display a single message thread with send capability for the current End User.
- [Working with End Users](/docs/embeddable/end-users): Provision End Users via the API, generate short-lived JWTs for embedded components, and attribute messages to users.
- [Inbox Component](/docs/embeddable/inbox): Mount the Inbox component to show a real-time, paginated conversation list scoped to the current End User.
- [Phone (dialpad)](/docs/embeddable/phone): Embed a working dialpad so end users can place outbound voice calls directly from inside your application.
- [Unread Count Component](/docs/embeddable/unread-count): Embed a live unread conversation count badge that updates in real time as new messages arrive.
- [Overview](/docs/overview)
- [How Surge is Organised](/docs/overview/how-surge-is-organised): The Platform, Account, and User hierarchy, what each level owns, and how the API is structured.
- [Send Your First Message](/docs/overview/send-your-first-message): Send your first SMS in under five minutes using Surge's demo number. No registration or phone number purchase required.
- [What is Surge](/docs/overview/what-is-surge): An introduction to Surge, the SMS and voice API for developers.
- [Phone Numbers](/docs/phone-numbers)
- [Attaching a Number to a Campaign](/docs/phone-numbers/attaching): How Surge automatically attaches phone numbers to active campaigns and when to listen for the attachment event.
- [Importing a Number](/docs/phone-numbers/importing): Port an existing phone number into Surge or host an external number to route its messaging traffic through Surge.
- [International Numbers](/docs/phone-numbers/international): US and Canada numbers are available via API. Numbers in other countries are available through support on request.
- [Purchasing a Number](/docs/phone-numbers/purchasing): Purchase local, toll-free, or short code phone numbers via API and understand per-plan phone number limits.
- [Receiving Messages & Webhooks](/docs/receiving): Configure a webhook endpoint, verify Surge webhook signatures, and handle incoming events in Python, TypeScript, Ruby, and Elixir.
- [Webhook Events](/docs/receiving/events): The complete catalogue of 13 webhook event types with full payload shapes and when each fires.
- [Two-Way Messaging Patterns](/docs/receiving/two-way): Receive inbound messages, reply in the same thread, handle opt-outs inline, and avoid duplicate event processing.
- [Register Your Business](/docs/registration): Carrier registration overview: what you need, how the review process works, and how to choose your registration path.
- [Register via API](/docs/registration/api-walkthrough): Step-by-step: create an account, submit a campaign, purchase a phone number, and reach production via the Surge API.
- [Avoiding Rejection: Patterns from Real Registration Reviews](/docs/registration/avoiding-rejection): The seven most common campaign rejection reasons with real reviewer quotes and specific fixes for each.
- [Register via Dashboard](/docs/registration/dashboard): Register your brand and campaign using the Surge dashboard form, the current path for toll-free verification.
- [Fixing a Rejected or Changes-Needed Campaign](/docs/registration/fixing-rejected): How to read reviewer feedback, update a campaign in a valid status, and get back to production after rejection.
- [Building on Surge: One Account per Customer](/docs/registration/one-account-per-customer): Why vertical SaaS platforms should create one Surge account per customer and how to implement the pattern.
- [Canonical Schema Reference](/docs/registration/schema-reference): All valid enum values for organization type, industry, regions, campaign use cases, content includes, and volume.
- [Sole Proprietor Path](/docs/registration/sole-proprietor): How sole proprietors register on Surge: no EIN required, dashboard-first flow, and lower throughput expectations.
- [Toll-Free Verification](/docs/registration/toll-free): How toll-free number verification works on Surge and how it differs from standard 10DLC local number registration.
- [Sending Messages](/docs/sending)
- [Ongoing Conversations](/docs/sending/conversations): How contacts and conversation threads work, when to use them, and how to manage opt-out state per thread.
- [Handle Failures](/docs/sending/handle-failures): Every send-time and delivery-time error code, retryability, and specific remediation steps for each failure type.
- [Send to Many People](/docs/sending/send-many): Blasts vs Audiences: when to use each, how to create and send to both, and campaign volume caps.
- [Send to One Person](/docs/sending/send-one): Send SMS and MMS to a single recipient: required fields, attachments, scheduling, personalization, and common errors.
- [Track Message Delivery](/docs/sending/track-delivery): How message delivery statuses work, webhook-based tracking, and how to list messages with cursor pagination.
- [Verifications](/docs/verifications)
- [Send and verify a code](/docs/verifications/send-and-verify): Send a six-digit OTP to a phone number and verify the user's code with two API calls, expiry and retry limits included.
- [Usage patterns and delivery gotchas](/docs/verifications/usage-patterns): Opted-out contacts, international quirks, carrier filtering, and security tips for OTP verification in production.