Merge pull request #460 from signalwire/august-20260623-whatsapp-messaging

Early access WhatsApp messaging: add API reference, spec updates, guides

Author: hey-august

CONTRIBUTING.md

@@ -80,6 +80,9 @@ so the committed OpenAPI/JSON Schema files under `fern/apis/**` and `specs/swml/
 > Change the `.tsp` source in `specs/`, then rebuild with `yarn build:specs` and commit both the source and the regenerated output.
 > See [API specifications](README.md#api-specifications) in the README for the full spec workflow.
 
+> [!NOTE]
+> The OpenAPI emitters (`@signalwire/*` under `specs/emitters/`) are local workspace packages that must be built before the specs compile. `yarn build:specs` handles this for you — prefer it over running an internal sub-step like `build:signalwire-rest` directly. If a build fails with `Couldn't resolve import "@signalwire/..."` or `missing-implementation: Extern declaration...`, the emitter symlinks are missing — run `yarn install`, then rebuild.
+
 ## Checks your PR has to pass
 
 CI runs on every pull request.

fern/apis/signalwire-rest/openapi.yaml

@@ -132,6 +132,13 @@ navigation:
                 slug: webhooks
                 contents:
                   - subpackage_campaignRegistry.ten_dlc_status_callback
+          - section: WhatsApp
+            slug: whatsapp
+            referenced-packages:
+              - whatsAppBusinesses
+              - whatsAppNumbers
+              - whatsAppTemplates
+            contents: []
           - shortCodes
       - section: Phone Number Management
         skip-slug: true

fern/products/apis/apis.yml

@@ -0,0 +1,80 @@
+---
+title: WhatsApp message templates
+slug: /messaging/whatsapp/message-templates
+sidebar-title: Message templates
+description: Create and manage the Meta-approved templates required to start WhatsApp conversations.
+max-toc-depth: 3
+---
+
+Templates are pre-approved message formats required when reaching out to customers who have not
+contacted you first. Think of them as pre-written scripts that Meta reviews and approves in advance.
+Once approved, you can send them to any customer at any time. See
+[Send a template message](/docs/platform/messaging/whatsapp/send-messages#template-message) for how to
+deliver one.
+
+<Info>
+WhatsApp on SignalWire is in **early-access alpha**. Template management through the SignalWire
+Dashboard is planned; today, templates are managed via the API or directly in the Meta Business
+dashboard.
+</Info>
+
+## Template components
+
+A template is made up of components. A **Body** component is required; the header, footer, and
+buttons are optional.
+
+| Component | Description |
+|---|---|
+| `HEADER` | Optional title line. Can be plain text or media (image, video, document). |
+| `BODY` | **Required.** Main message text. Supports variable placeholders for personalization. |
+| `FOOTER` | Optional closing line (e.g. "Thank you for your order"). |
+| `BUTTONS` | Optional interactive buttons: quick reply, phone number, or URL. |
+
+### Parameters
+
+Templates support variable placeholders so you can personalize messages with customer names, order
+numbers, and so on. There are two styles, set by `parameter_format`:
+
+- **Positional** (`positional`): referenced as `{{1}}`, `{{2}}`, `{{3}}` in order.
+- **Named** (`named`): referenced by descriptive labels like `{{first_name}}` or `{{order_status}}`.
+
+### Categories
+
+The `category` field must be one of:
+
+- `marketing`: promotional messages, offers, announcements
+- `utility`: transactional messages, order updates, account alerts
+- `authentication`: one-time passwords and verification codes
+
+## Manage templates
+
+Templates are managed through the API. For the full request and response schemas, see the reference:
+
+<CardGroup>
+<Card title="Create a template" href="/docs/apis/rest/whatsapp/create-whatsapp-template" />
+<Card title="List templates" href="/docs/apis/rest/whatsapp/list-whatsapp-templates" />
+<Card title="Get a template" href="/docs/apis/rest/whatsapp/retrieve-whatsapp-template" />
+<Card title="Update a template" href="/docs/apis/rest/whatsapp/update-whatsapp-template" />
+<Card title="Delete a template" href="/docs/apis/rest/whatsapp/delete-whatsapp-template" />
+</CardGroup>
+
+The example below creates an order-update template with positional parameters. The `components`
+array is the heart of the request; each component's fields depend on its `type`.
+
+<EndpointRequestSnippet endpoint="POST /api/messaging/whatsapp/templates" />
+
+## Approval and updates
+
+<Note>
+Templates must be reviewed and approved by Meta before use. Approval typically takes a few minutes
+to a few hours. A template's current state is reported in its `template_status` field. It must be
+`approved` before it can be used to send messages.
+</Note>
+
+A template can only be updated while it is **not yet approved**. Once approved, delete and recreate
+it to make changes.
+
+<Note>
+Anywhere a template ID is accepted, you can use either the SignalWire template ID (a UUID) or the
+Meta template ID (a numeric string).
+</Note>

fern/products/platform/pages/messaging/whatsapp/message-templates.mdx

@@ -0,0 +1,82 @@
+---
+title: Connect a WhatsApp business number
+slug: /messaging/whatsapp/onboarding
+sidebar-title: Onboarding
+description: Connect a Meta-verified WhatsApp business number to your SignalWire Space during the early-access alpha.
+max-toc-depth: 3
+---
+
+Your SignalWire account connects to WhatsApp through your existing Facebook/Meta Business account.
+Once connected, your WhatsApp business numbers appear in your Space and can be used as the
+`from` address in the [Messaging API](/docs/platform/messaging/whatsapp/send-messages).
+
+<Info>
+WhatsApp on SignalWire is in **early-access alpha** and is enabled per Space. The steps below are
+coordinated with your SignalWire representative. Number provisioning is not yet self-serve. See the
+[overview](/docs/platform/messaging/whatsapp) for what's included in the alpha.
+</Info>
+
+## Prerequisites
+
+- A **Meta Business Account** (Facebook/Meta Business).
+- A **SignalWire Space** with WhatsApp alpha access enabled.
+- SignalWire **project credentials**: your Project ID and an API key with the `numbers` scope. You'll
+  find these in your [SignalWire Dashboard](https://my.signalwire.com).
+
+## Connect your account
+
+<Steps>
+
+### Request alpha access
+
+WhatsApp access is gated at the Space level. [Request early access through this
+form](https://signalwire.typeform.com/to/EyPVZ1St) to have the feature enabled for your Space and
+begin onboarding.
+
+### Complete Meta embedded signup
+
+SignalWire uses Meta's **embedded signup** flow to link your WhatsApp Business Account (WABA) to
+your SignalWire Space. During this flow you authorize the connection with Meta and select the
+business phone number(s) to register.
+
+### Confirm your numbers
+
+After signup completes, your registered WhatsApp numbers appear in your Space, associated with your
+WhatsApp Business Account. Confirm they're present before sending messages.
+
+</Steps>
+
+<Note>
+During the alpha, adding or removing WhatsApp numbers is handled on request by the SignalWire team,
+or directly via the Meta Business dashboard. It cannot be done programmatically through the API or the
+customer-facing SignalWire Dashboard at this time.
+</Note>
+
+## Verify the connection
+
+List the WhatsApp Business Accounts connected to your Space:
+
+<EndpointRequestSnippet endpoint="GET /api/messaging/whatsapp/businesses" />
+
+And list the WhatsApp numbers available to use as a `from` address:
+
+<EndpointRequestSnippet endpoint="GET /api/messaging/whatsapp/numbers" />
+
+<EndpointResponseSnippet endpoint="GET /api/messaging/whatsapp/numbers" />
+
+Each number record includes its association with a WhatsApp Business Account, voice-capability flags,
+and the resource IDs used for routing calls or messages through SignalWire. See the
+[List WhatsApp numbers](/docs/apis/rest/whatsapp/list-whatsapp-numbers) and
+[List WhatsApp Business Accounts](/docs/apis/rest/whatsapp/list-whatsapp-businesses) reference for the
+full response schemas.
+
+## Next steps
+
+<CardGroup>
+<Card title="Send messages" href="/docs/platform/messaging/whatsapp/send-messages">
+  Send text, media, interactive, and template messages over WhatsApp.
+</Card>
+<Card title="Message templates" href="/docs/platform/messaging/whatsapp/message-templates">
+  Create and manage the Meta-approved templates required to start conversations.
+</Card>
+</CardGroup>

fern/products/platform/pages/messaging/whatsapp/onboarding.mdx

@@ -0,0 +1,69 @@
+---
+title: WhatsApp messaging
+slug: /messaging/whatsapp
+sidebar-title: Overview
+position: 0
+subtitle: Send and receive WhatsApp messages through the SignalWire platform, currently in early-access alpha.
+description: Send and receive WhatsApp messages from a Meta-verified business number through SignalWire, in early-access alpha.
+max-toc-depth: 3
+---
+
+SignalWire's WhatsApp integration lets you send and receive WhatsApp messages from a
+Meta-verified business number using the same platform, APIs, and routing you already use for
+SMS, MMS, and voice. Inbound and outbound messages are handled through the same
+[Messaging API](/docs/platform/messaging), so WhatsApp becomes one more channel
+alongside the ones you already run, with no third-party middleware required.
+
+<Info>
+WhatsApp on SignalWire is in **early-access alpha**, enabled per Space. Request access below to join the alpha.
+</Info>
+
+<CardGroup>
+<Card title="Request early access" href="https://signalwire.typeform.com/to/EyPVZ1St">
+  WhatsApp access is gated at the Space level. Request access and the SignalWire team will enable the
+  feature for your Space.
+</Card>
+</CardGroup>
+
+## What's available today
+
+During the alpha, the following is supported:
+
+- **Inbound and outbound messaging** through the SignalWire Messaging API.
+- **Messaging from a Meta-verified business number** that you connect through Meta's embedded
+  signup flow.
+- **Programmatic routing** of inbound messages to your application, just like SMS and MMS.
+
+## Coming soon
+
+The following capabilities are planned and are **not yet available**:
+
+- Inbound and outbound WhatsApp **voice calls**, including routing to [AI Agents](/docs/platform/ai).
+- **Messaging fallback** to SMS/MMS when WhatsApp delivery fails.
+- **Message template management** from the SignalWire Dashboard.
+
+## How it works
+
+Customers reach your business through WhatsApp Ads or a Facebook call-to-action button, which
+opens WhatsApp and starts a conversation with your Meta-verified business number. From there,
+messages are handled programmatically like any other channel, with the
+[Server SDKs](/docs/server-sdks), [SWML](/docs/swml), or [AI Agents](/docs/platform/ai).
+
+## Prerequisites
+
+To use WhatsApp messaging during the alpha, you need:
+
+1. A **Meta Business Account**.
+2. A **SignalWire Space** enabled for WhatsApp alpha access.
+3. To **authorize the connection** between Meta and SignalWire through the embedded signup flow.
+
+Once connected, your registered business number can be used for inbound and outbound messaging
+and programmatic routing.
+
+## Next steps
+
+<CardGroup>
+<Card title="Connect your WhatsApp business number" href="/docs/platform/messaging/whatsapp/onboarding">
+  Walk through Meta's embedded signup to connect a business number to your SignalWire Space.
+</Card>
+</CardGroup>

fern/products/platform/pages/messaging/whatsapp/overview.mdx

@@ -0,0 +1,61 @@
+---
+title: Receive WhatsApp messages
+slug: /messaging/whatsapp/receive-messages
+sidebar-title: Receive messages
+description: View inbound WhatsApp messages and track delivery status through the SignalWire Messaging API.
+max-toc-depth: 3
+---
+
+Inbound messages sent to your WhatsApp business number are automatically received and logged by
+SignalWire. You can view them in your Dashboard or retrieve them through the Messaging API, alongside
+the delivery status of the messages you send.
+
+<Info>
+WhatsApp on SignalWire is in **early-access alpha**. Inbound messages from customers are
+automatically received and logged by SignalWire.
+</Info>
+
+## Message logs
+
+Inbound messages and the delivery status of the messages you send are available through the message
+logs endpoint, [`GET /api/messaging/logs`](/docs/apis/rest/message-logs/list-message-logs), which
+returns history for both inbound and outbound messages. WhatsApp messages are identified by
+`kind: whatsapp`. See the [Message Logs](/docs/apis/rest/message-logs/list-message-logs) reference for
+the full response schema.
+
+## Delivery status
+
+The `status` field updates as an outbound message progresses:
+
+| Status | Meaning |
+|---|---|
+| `sent` | SignalWire has dispatched the message to Meta. |
+| `delivered` | The recipient's device has received the message. |
+| `read` | The recipient has opened the message. |
+
+You can also view message history graphically in your
+[SignalWire Dashboard](https://my.signalwire.com) under **Logs → Messaging**.
+
+To be notified of each status change as it happens, set `status_callback` when
+[sending a message](/docs/platform/messaging/whatsapp/send-messages). SignalWire then POSTs the
+following payload to your URL at each state change:
+
+<WebhookPayloadSnippet webhook="messageStatusCallback" />
+
+## Replying to inbound messages
+
+When a customer messages you first, you can reply with any message type for **24 hours** from their
+last inbound message. Outside that window, you must use an approved
+[template](/docs/platform/messaging/whatsapp/message-templates). See
+[Messaging rules](/docs/platform/messaging/whatsapp/send-messages#messaging-rules) for details.
+
+## Next steps
+
+<CardGroup>
+<Card title="Send messages" href="/docs/platform/messaging/whatsapp/send-messages">
+  Send text, media, interactive, and template messages.
+</Card>
+<Card title="Message templates" href="/docs/platform/messaging/whatsapp/message-templates">
+  Create and manage Meta-approved templates.
+</Card>
+</CardGroup>