> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Voiceflow through Apple Messages

> Connect Apple Messages for Business to a Voiceflow text agent. Configure the platform, host the relay, test replies and prepare release.

## Overview

Answer Apple Messages for Business text conversations using Voiceflow and Zendesk Sunshine Conversations as the Messaging Service Provider. Your relay handles text automation; Sunshine routes it to Apple and provides the Agent Workspace escalation path.

<a id="before-you-begin"></a>

## Before you begin

Collect the agent, account and host access.

| Requirement | Obtain before installation |
| --- | --- |
| Voiceflow owner | An existing agent with a known support answer, a private project API key, project ID and reviewed Environment alias. [Build the agent](/docs/documentation/build/overview) first, then [publish the intended release](/docs/documentation/deploy/environments/publishing). |
| Apple business approval | An approved Apple Messages for Business account, Business ID and an Apple-approved MSP. This recipe uses Zendesk Sunshine Conversations. |
| Zendesk administrator | A dedicated Sunshine Conversations app with API access, credentials and an Apple channel integration; an Agent Workspace team that can receive escalations. |
| Human support | A tested live-agent path, staffing hours and an escalation notice. Apple does not approve automation-only deployments. |
| Relay operator | A Node.js host, public HTTPS hostname, private secrets and persistent disk; an operator who can investigate paused conversations. |

The example provides public-policy text support. Keep private Voiceflow and platform credentials on the host; a customer’s messaging identity does not authorize access to orders or account records. Have the agent return text only and provide a support route in its instructions. Buttons, audio and Handoff traces need additional adapters; see [Adapt agent replies](/docs/guides/channels/messaging/adapt-agent-replies).

<a id="create-platform-app"></a>

## Prepare the platform account

Create the exact app or account this relay will use.

### 1. Register the business and MSP

Work with your MSP, then sign in to [Apple Business Register](https://register.apple.com/) and add a **Messages for Business Account**. Supply the business and technical contacts, brand assets, customer response information and support hours. Select Zendesk/Sunshine Conversations as your MSP and submit the account for review. Add authorized testers and complete the MSP connection test.

Copy the issued Business ID. In your Sunshine app’s channel integrations, select **Apple Messages for Business**, supply that Business ID, and connect it. Retain the Apple channel integration ID. An Apple developer account or consumer iMessage account does not replace business approval. See [the MSP’s connection procedure](https://docs.smooch.io/guide/apple-messages-for-business/) and [Apple’s requirements](https://register.apple.com/resources/messages/messaging-documentation/faq).

### 2. Create the relay integration and escalation route

In Zendesk Admin Center, open **Apps and integrations → APIs → Conversations API**. Obtain the Sunshine App ID and create an app API key; store its Key ID and Key secret. Create a conversations integration for your relay with the callback and triggers in the next section. Save its integration ID and generated webhook **Shared secret**. The webhook shared secret is separate from the API key secret.

After creating the relay integration and configuring `.env` below, run `node --env-file=.env configure-apple-switchboard.mjs` from the archive. The script reads or creates the app’s Switchboard, links Agent Workspace (`zd:agentWorkspace`) and your relay integration, disables the bot’s standby events, sets its next responder to Agent Workspace, and enables it as the default responder for the app and the configured Apple channel. It prints the resulting Switchboard IDs. Keep `ZENDESK_INTEGRATION_ID` set to the original conversations integration ID; the printed bot Switchboard ID is a separate resource.

This changes the app’s default routing: use a dedicated test app and have its administrator review the saved result before production. Ensure Agent Workspace is enabled, staffed and able to reply to Apple conversations. The relay checks current Switchboard ownership again before sending to reduce competing replies. The ownership check and send are separate requests; changing control cannot cancel a send already in flight. The [provider API reference](https://developer.zendesk.com/api-reference/conversations/) supplies optional field details.

<a id="run-relay"></a>

## Run the relay

Configure and host the supplied executable example.

Use the [configuration file](/docs/examples/messaging/apple-messages-for-business.env.example) for this platform. Every name below is read by the supplied artifact; IDs identify the resources prepared above. `VF_ENVIRONMENT` is the Environment alias, not a version label pasted from another project.

```dotenv
VF_API_KEY=YOUR_PRIVATE_VOICEFLOW_PROJECT_KEY
VF_PROJECT_ID=YOUR_VOICEFLOW_PROJECT_ID
VF_ENVIRONMENT=YOUR_ENVIRONMENT_ALIAS
DATA_DIR=/var/lib/voiceflow-messaging
PORT=8080
PLATFORM=apple-messages-for-business
ZENDESK_SUBDOMAIN=YOUR_ZENDESK_SUBDOMAIN
ZENDESK_APP_ID=YOUR_SUNSHINE_APP_ID
ZENDESK_KEY_ID=YOUR_SUNSHINE_KEY_ID
ZENDESK_KEY_SECRET=YOUR_SUNSHINE_KEY_SECRET
ZENDESK_WEBHOOK_SECRET=YOUR_WEBHOOK_SHARED_SECRET
ZENDESK_INTEGRATION_ID=YOUR_RELAY_CUSTOM_INTEGRATION_ID
ZENDESK_APPLE_INTEGRATION_ID=YOUR_APPLE_CHANNEL_INTEGRATION_ID
```

### 1. Download and configure the relay

On a Linux host you administer, create `/opt/voiceflow-messaging` and extract the [relay archive](/docs/examples/messaging/messaging-relay.zip) there. Use Node.js 22.12 or later. Run `node --test fixtures.test.mjs` first: it generates signed synthetic events and mocks all remote calls, without credentials or live messages. Save the configuration above as `.env`, replacing every `YOUR_` value; restrict it to the service account with `chmod 600 .env`. Set `DATA_DIR` to a private persistent directory that this account can write.

The archive includes `core.mjs`, platform adapters, HTTP/Teams entry points, local fixture tests and a package manifest. Run `node --env-file=.env relay.mjs serve`. The HTTP relay uses only Node built-ins; it does not need `npm install`.

### 2. Expose the HTTPS endpoint

Point your own DNS hostname to the host. Terminate HTTPS with a valid public certificate and proxy to `127.0.0.1:8080`. For example, with [Caddy](https://caddyserver.com/docs/quick-starts/reverse-proxy) installed:

```sh
caddy reverse-proxy --from support.example.com --to 127.0.0.1:8080
```

Replace the example hostname, allow inbound 80/443 for certificate provisioning and keep the relay port private. Use a separate hostname and credentials for testing. Confirm `https://YOUR_HOST/health` returns `ok` before registering `/webhook`.

### 3. Keep one process running

After the foreground check, stop it and create a service using the unit below. Keep one process and one writable data directory per installation. Do not run this file store on ephemeral serverless storage or start multiple replicas.

```ini
# /etc/systemd/system/voiceflow-messaging.service
[Unit]
Description=Voiceflow messaging relay
After=network-online.target

[Service]
User=relay
WorkingDirectory=/opt/voiceflow-messaging
ExecStart=/usr/bin/node --env-file=.env relay.mjs serve
Restart=on-failure
UMask=0077

[Install]
WantedBy=multi-user.target
```

Create the non-login `relay` service user, give it read access to the application and `.env`, and ownership of `/var/lib/voiceflow-messaging`. Confirm `/usr/bin/node --version` is 22.12 or later, or substitute your actual Node path. Then run `sudo systemctl daemon-reload` and `sudo systemctl enable --now voiceflow-messaging`. Expect the service to stay active; keep the HTTPS proxy running through its own service.

The file store is a small single-process starting point. Back it up privately and monitor disk space, queue age and failures. Higher traffic needs a transactional inbox/outbox and per-conversation workers before adding replicas. Session keys and customer text are stored in the data directory; apply your retention and access policy there as well as in Voiceflow.

<a id="register-events"></a>

## Register incoming events

Connect the platform to your hosted endpoint.

Set the relay integration’s webhook target to `https://YOUR_HOST/webhook`, version **v2**, with these triggers:

| Trigger | Purpose |
| --- | --- |
| `conversation:message` | Receive user text; business-authored replies are filtered out. |
| `conversation:message:delivery:channel` | Record delivery to Apple. |
| `conversation:message:delivery:failure` | Record failed delivery. |
| `switchboard:passControl:failure` | Diagnose unsuccessful escalation in the provider logs. |

Save the integration and put its generated Shared secret in `ZENDESK_WEBHOOK_SECRET`. Sunshine sends this value in `X-Api-Key`; the relay validates it over HTTPS and also checks the app and Apple channel integration IDs. It is a shared-secret header, not an HMAC signature. See [receiving messages](https://developer.zendesk.com/documentation/conversations/messaging-platform/programmable-conversations/receiving-messages/).

Use the Apple Business Register tester connection to confirm that a user text produces a v2 event with `source.type: apple`, the intended source integration ID, a user ID and a conversation ID. Sunshine webhook retries can repeat event IDs; save those IDs before acknowledgment.

<a id="conversation-routing"></a>

## Route conversations and replies

Keep the customer, agent session and reply destination aligned.

| Stage | Mapping in the example |
| --- | --- |
| Customer identity | Sunshine app + conversation ID + user ID. Apple’s opaque identity does not provide a phone number or verified business-account login. |
| Incoming text | v2 `conversation:message`, `author.type: user`, `source.type: apple` and the configured Apple integration ID. |
| Visible reply | POST `/sc/v2/apps/{app-id}/conversations/{conversation-id}/messages` as `author.type: business` with text content. |
| Human escalation | A customer message equal to `human` calls `/{conversation-id}/passControl` with `switchboardIntegration: zd:agentWorkspace`, then pauses local automation. |

The relay hashes platform, destination account, customer/thread, project and Environment into a bounded Voiceflow `userID`. It creates a session with the private project key, stores the returned `sessionKey`, launches once, then sends `{ action: { type: "text", payload: text } }` to `/v4/interact`. Text traces become platform replies. Follow-ups reuse the key; starting a session every message would reset the conversation.

Tell customers that they can type **human**. That keyword follows the provider’s Switchboard route; it does not execute a Voiceflow Handoff step. Agent Workspace must receive the conversation and a person must answer before you consider escalation usable. Return control to the relay in Sunshine, reconcile queued jobs, reset its session if appropriate, and explicitly resume it before restoring automation.

Apple requires live-agent support and an approved MSP. The example does not implement Apple Pay, list/time pickers or authentication messages. `STOP` and `UNSUBSCRIBE` suppress local automation without another AI turn. If a customer closes the Apple conversation, the MSP marks the Apple client blocked: stop sending and do not attempt to reopen it. Keep delivery-failure monitoring active; only a customer’s later permitted initiation can re-establish contact. Follow [Apple’s conversation and opt-out rules](https://register.apple.com/resources/messages/messaging-documentation/faq).

<a id="test-conversation"></a>

## Test a customer conversation

Verify the reply in the destination you installed.

### 1. Send a real platform message

Use an approved Apple tester’s Messages entry point to send the prepared policy question. Expect the text answer in the same Apple Messages conversation.

### 2. Check continuity and isolation

Ask a related follow-up, then test with a second authorized customer. Confirm the intended Voiceflow project and exchange in [Transcripts](/docs/documentation/measure/transcripts). Run `node --env-file=.env relay.mjs inspect` while the service is stopped to compare event IDs, conversation keys and completion states without printing session tokens.

### 3. Check this platform’s delivery behavior

Type `human`: verify Agent Workspace takes control, a teammate’s reply reaches Apple Messages, and the relay makes no competing AI turn. Test STOP and customer closure, then confirm a blocked conversation receives no automatic retry.

A saved callback, accepted API request or successful Voiceflow Run does not prove this platform conversation. Keep local signed-fixture tests separate from this authenticated customer test.

<a id="troubleshooting" />

### The callback saves but no reply arrives

Check platform access as well as endpoint connectivity.

Check the approved Business ID, connected Apple integration, app region/subdomain, webhook Shared secret and Switchboard control. A ticket or successful API write is not evidence of an Apple-visible reply or a live-agent escalation.

### A conversation is paused or a reply is duplicated

Reconcile remote effects before resuming the saved job.

Inspect the event’s `phase`, `failedDuring`, saved traces and accepted chunks in the private data file. A runtime timeout can occur after a tool action; a send timeout can occur after the platform accepted the message. The sample pauses that conversation and does not retry either effect automatically. Follow [Recover failed messages](/docs/guides/channels/messaging/recover-failed-messages), then repeat the platform test.

<a id="go-live"></a>

## Release and maintain the connection

Promote the tested route and keep recovery available.

### 1. Approve the production destination

Complete Apple/MSP approval, publish the reviewed entry points and staffing information, then repeat the text, human escalation and closure tests. Do not launch an automation-only deployment. Business-ID moves between Sunshine apps require the MSP’s assistance.

### 2. Release the reviewed agent

Have the Voiceflow owner publish the tested agent to the intended Environment. Deploy that alias and production credentials to the relay, restart its service and repeat the [customer test](#test-conversation) with a fresh customer/session. Existing session keys are not an automatic migration to a new release. Keep the previous deployment and state backup available for rollback.

### Rotate, update or disconnect

Maintain both the provider registration and the relay state.

Stop the service before changing `.env` or running maintenance commands. Rotate the platform credentials using its administrator controls, update the secret file and restart. If a webhook secret changes, update both sides and check a real event. For a release change, drain or reconcile pending jobs first; do not erase the state file to resolve a delivery problem.

To disconnect, disable/remove this callback or uninstall this app in the provider, stop the relay and revoke its unused credentials. Confirm no new events arrive and retain/delete customer state according to your policy. Keep the registration details needed to reconnect. See [Pause automated replies](/docs/guides/channels/messaging/pause-automated-replies) for a temporary conversation-specific pause.
